Skip to content

Commit

Permalink
chore(docs): Add missing proxy configuration info to the docs (#623)
Browse files Browse the repository at this point in the history
  • Loading branch information
@alco
alco authored Nov 2, 2023
1 parent 14e6436 commit d6c169d
Show file tree
Hide file tree
Showing 5 changed files with 22 additions and 8 deletions.
4 changes: 2 additions & 2 deletions components/electric/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -88,10 +88,10 @@ The Electric application is configured using environment variables. Everything t
| `ELECTRIC_USE_IPV6` | `false` | Set to `yes` or `true` to make Electric listen on `::` instead of `0.0.0.0`. On Linux this allows inbound connections over both IPv6 and IPv4. On Windows and some BSD systems inbound connections will only be accepted over IPv6 when this setting is enabled. |
| `LOGICAL_PUBLISHER_HOST` | | Host of this electric instance for the reverse connection from Postgres. It has to be accessible from the Postgres instance that is running at `DATABASE_URL`. |
| `LOGICAL_PUBLISHER_PORT` | `5433` | Port number to use for reverse connections from Postgres. |
| `HTTP_PORT` | `5133` | Port for HTTP connections. Includes client websocket connections on `/ws`, and other functions on `/api` |
| `HTTP_PORT` | `5133` | Port for HTTP connections. Includes client websocket connections on `/ws`, and other functions on `/api`. |
| | | |
| `PG_PROXY_PORT` | `65432` | Port number for connections to the [Postgres migration proxy](https://electric-sql.com/docs/usage/data-modelling/migrations). |
| `PG_PROXY_PASSWORD` | | Password to use when connecting to the Postgres proxy via `psql` or via some postgresql adapter |
| `PG_PROXY_PASSWORD` | | Password to use when connecting to the Postgres proxy via `psql` or any other Postgres client. |
| | | |
| `AUTH_MODE` | `"secure"` | Authentication mode to use to authenticate Satellite clients. See below. |
| `AUTH_JWT_ALG` | | <p>The algorithm to use for JWT verification. Electric supports the following algorithms:</p><ul><li>`HS256`, `HS384`, `HS512`: HMAC-based cryptographic signature that relies on the SHA-2 family of hash functions.</li><li>`RS256`, `RS384`, `RS512`: RSA-based algorithms for digital signature.</li><li>`ES256`, `ES384`, `ES512`: ECC-based algorithms for digital signature.</li></ul> |
Expand Down
5 changes: 4 additions & 1 deletion docs/api/service.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ The standard way to start Electric sync service is using the official Docker ima
docker run \
-e "DATABASE_URL=postgresql://..." \
-e "LOGICAL_PUBLISHER_HOST=..." \
-e "PG_PROXY_PASSWORD=..." \
-e "AUTH_JWT_ALG=HS512" \
-e "AUTH_JWT_KEY=..." \
-p 5133:5133 \
Expand All @@ -38,7 +39,9 @@ Everything in the table below that doesn't have a default value is required to r
| `ELECTRIC_USE_IPV6`<p>&nbsp;&nbsp;(`false`)</p> | Set to `yes` or `true` to make Electric listen on `::` instead of `0.0.0.0`. On Linux this allows inbound connections over both IPv6 and IPv4. On Windows and some BSD systems inbound connections will only be accepted over IPv6 when this setting is enabled. |
| `LOGICAL_PUBLISHER_HOST` | Host of this electric instance for the reverse connection from Postgres. It has to be accessible from the Postgres instance that is running at `DATABASE_URL`. |
| `LOGICAL_PUBLISHER_PORT`<p>&nbsp;&nbsp;(`5433`)</p> | Port number to use for reverse connections from Postgres. |
| `HTTP_PORT`<p>&nbsp;&nbsp;(`5133`)</p> | Port for HTTP connections. Includes client websocket connections on `/ws`, and other functions on `/api` |
| `HTTP_PORT`<p>&nbsp;&nbsp;(`5133`)</p> | Port for HTTP connections. Includes client websocket connections on `/ws`, and other functions on `/api`. |
| `PG_PROXY_PORT`<p>&nbsp;&nbsp;(`65432`)</p> | Port number for connections to the [Postgres migration proxy](https://electric-sql.com/docs/usage/data-modelling/migrations). |
| `PG_PROXY_PASSWORD` | Password to use when connecting to the Postgres proxy via `psql` or any other Postgres client. |

### Authentication

Expand Down
2 changes: 1 addition & 1 deletion docs/examples/basic.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,4 +62,4 @@ Change into the `web-wa-sqlite` example directory:
cd electric/examples/web-wa-sqlite
```

Follow the instructions in the [README.md](https://github.com/electric-sql/electric/blob/main/examples/web-wa-sqlite/README.md) and see the page here on [running the examples](./notes/running.md).
Follow the instructions in the [README.md](https://github.com/electric-sql/electric/blob/main/examples/web-wa-sqlite/README.md) and see the page here on [running the examples](./notes/running).
2 changes: 1 addition & 1 deletion docs/examples/linear-lite.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,4 +66,4 @@ Change into the `linearlite` example directory:
cd electric/examples/linearlite
```

Follow the instructions in the [README.md](https://github.com/electric-sql/electric/blob/main/examples/linearlite/README.md) and see the page here on [running the examples](./notes/running.md).
Follow the instructions in the [README.md](https://github.com/electric-sql/electric/blob/main/examples/linearlite/README.md) and see the page here on [running the examples](./notes/running).
17 changes: 14 additions & 3 deletions docs/usage/installation/service.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,16 @@ You can run the [pre-packaged Docker images](#images) published on Docker Hub, o

## Configuration

The Electric sync service is configured using environment variables. The two required variables are:
The Electric sync service is configured using environment variables. The three required variables are:

- `DATABASE_URL` in the format of a Postgres [Connection URI](https://www.postgresql.org/docs/current/libpq-connect.html#id-1.7.3.8.3.6)
- `LOGICAL_PUBLISHER_HOST` that the sync service is running on (must be accessible from the Postgres instance to establish an inbound replication subscription)
- `PG_PROXY_PASSWORD` to safe-guard access to the [Migrations proxy](../data-modelling/migrations.md#migrations-proxy)

```shell
DATABASE_URL="postgresql://user:password@localhost:5432/electric"
LOGICAL_PUBLISHER_HOST="localhost"
PG_PROXY_PASSWORD="..."
```

See <DocPageLink path="api/service" /> for the full list of configuration options.
Expand All @@ -30,10 +32,11 @@ See <DocPageLink path="api/service" /> for the full list of configuration option
Pre-packaged images are available on Docker Hub at [electricsql/electric](https://hub.docker.com/r/electricsql/electric). Run using e.g.:

```shell
docker pull electricsql/electric:latest
docker pull electricsql/electric:latest
docker run \
-e "DATABASE_URL=postgresql://..." \
-e "LOGICAL_PUBLISHER_HOST=..." \
-e "PG_PROXY_PASSWORD=..." \
-e "AUTH_MODE=insecure" \
-p 5133:5133 \
-p 5433:5433 \
Expand All @@ -42,7 +45,7 @@ docker run \

### Compose

You can deploy the sync service together with [a Postgres database](./postgres.md) in a Docker Compose file. For example:
You can deploy the sync service together with [a Postgres database](./postgres.md) in a Docker Compose file. For example, save below contents to a file named `compose.yaml`:

```yaml
version: '3.1'
Expand All @@ -65,12 +68,19 @@ services:
environment:
DATABASE_URL: postgresql://postgres:pwd@pg
LOGICAL_PUBLISHER_HOST: electric
PG_PROXY_PASSWORD: proxy_password
AUTH_MODE: insecure
ports:
- 5133:5133
restart: always
```
Then start the services:
```shell
docker compose -f compose.yaml up
```

### Build

See the [Makefile](https://github.com/electric-sql/electric/blob/main/components/electric/Makefile) for more details but e.g.:
Expand All @@ -85,6 +95,7 @@ Then run:
docker run \
-e "DATABASE_URL=postgresql://..." \
-e "LOGICAL_PUBLISHER_HOST=..." \
-e "PG_PROXY_PASSWORD=..." \
-e "AUTH_MODE=insecure" \
-p 5133:5133 \
-p 5433:5433 \
Expand Down

0 comments on commit d6c169d

Please sign in to comment.