Skip to content

Commit 50414e9

Browse files
author
Andrea Cambieri
committed
wip readme
1 parent ca08566 commit 50414e9

1 file changed

Lines changed: 140 additions & 0 deletions

File tree

‎Readme.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
![logo.svg](img/logo.svg)
2+
3+
![Test Status](https://github.com/acamb/continuity/actions/workflows/makefile.yml/badge.svg)
4+
5+
# Continuity - Load balancing made simple.
6+
Continuity is a lightweight load balancer designed for simplicity and ease of use, with a focus on small environments and home labs.
7+
## Features
8+
- Simple configuration backed to a single YAML file
9+
- Can be managed statically via yaml file or via CLI client / RESTful API
10+
- Zero downtime deployments of applications behind the load balancer via transactional API
11+
- Configurable health checks for backend services
12+
- Sticky sessions via application cookies or managed by the load balancer
13+
- Dynamic pool configuration via API
14+
- Custom routing via request headers
15+
- Human-readable and JSON output for CLI client
16+
17+
## Installation
18+
19+
Continuity is distributed as a Docker image, .deb and .rpm packages, statically linked binary, or can be built from source.
20+
The CLI client is also available for Windows.
21+
22+
### Docker
23+
The simplest way to run Continuity is via Docker. You can pull the latest image from Docker Hub:
24+
25+
```bash
26+
docker pull acamb/continuity:latest
27+
```
28+
29+
Then, run the container with your configuration file mounted:
30+
31+
```bash
32+
docker run -d -p 80:80 -v /path/to/continuity.yaml:/opt/continuity/config.yaml acamb/continuity:latest
33+
```
34+
35+
or using docker-compose:
36+
37+
```yaml
38+
services:
39+
continuity:
40+
image: acamb/continuity:latest
41+
ports:
42+
- "80:80"
43+
volumes:
44+
- /path/to/continuity.yaml:/opt/continuity/config.yaml
45+
```
46+
47+
### Debian and RPM Packages
48+
49+
You can download and install the latest .deb or .rpm package from the release page.
50+
For example on Debian-based systems:
51+
52+
```bash
53+
apt install ./continuity-x.y.z.deb
54+
```
55+
And to install the client:
56+
57+
```bash
58+
apt install ./continuity-client-x.y.z.deb
59+
```
60+
61+
Both `.deb` and `.rpm` packages will install the server binary to `/usr/bin/continuity-server` and will create a systemd service for the server running as the `continuity-server` user.
62+
For the client, the binary will be installed to `/usr/bin/continuity`.
63+
64+
### Statically Linked Binary / Manual installation
65+
66+
A statically linked version of Continuity is available for Linux amd64 and can be downloaded from the release page.
67+
68+
You can generate a configuration file template using:
69+
70+
```bash
71+
./continuity-server -sample-config
72+
```
73+
And for the client:
74+
75+
```bash
76+
./continuity sample-config
77+
```
78+
79+
In both cases a config.yml file will be created in the current directory.
80+
81+
### Building from Source
82+
83+
To build Continuity from source, ensure you have Go installed (version 1.18 or later), then clone the repository and build:
84+
85+
```bash
86+
make server
87+
```
88+
This will create the server (`continuity-server`) binary in the `bin/` directory.
89+
90+
To build the CLI client:
91+
92+
```bash
93+
make client
94+
```
95+
This will create the client binary (`continuity`) in the `bin/` directory.
96+
97+
## Client Usage
98+
99+
Run the client in the directory containing your configuration file (config.yaml by default) or specify the config file with the `-config` flag.
100+
The configuration file is per project, so you can have multiple configuration files for different environments / services.
101+
You can also share the same configuration for different targets by creating different pools on the same server.
102+
A pool represents a hostname or path you want to load balance traffic for.
103+
104+
### Create a new pool
105+
```
106+
continuity pool add <hostname> # hostname and optional path to serve requests for, must contain the schema (e.g. http://my-app.domain.com)
107+
--health-check-interval SECONDS # Seconds between health checks (default: 10s)
108+
--health-check-timeout SECONDS # Health check connection timeout (default: 5s)
109+
--health-check-initial-delay SECONDS # Initial delay on new server registration before starting health checks (default: 20s)
110+
--health-fail NUM_KO_RESPONSES_THRESHOLD # Number of failed health checks before marking server as down (default: 3)
111+
--health-ok NUM_OK_RESPONSES_THRESHOLD # Number of successful health checks before marking server as healthy (default: 2)
112+
[--sticky-sessions true/false] # Enable sticky sessions (default: false)
113+
[--sticky-method [IP|AppCookie|LBCookie] ] # Sticky session method (default, if sticky sessions enabled: IP)
114+
[--cookie-name NAME] # Name of the application cookie to use for sticky sessions (required if sticky-method is AppCookie)
115+
```
116+
See the help (-h) for the full list of options and shorts.
117+
Example:
118+
```bash
119+
continuity pool add http://my-app.domain.com -i 30 -t 10 -d 35 --health-ok 1 --health-fail 3
120+
```
121+
122+
### Add a server to the pool
123+
```
124+
125+
```
126+
127+
### Add a server with a routing condition to the pool
128+
### Add a server and remove an old server transactionally (zero downtime deployments)
129+
### View current configuration
130+
### Json output
131+
### Server statistics
132+
### Remove a server from a pool
133+
### Update a pool
134+
### Delete a pool
135+
136+
## Server Usage
137+
138+
### Start the server
139+
### Configuration file auto update
140+
### View server logs

0 commit comments

Comments
 (0)