Skip to content

Commit

Permalink
Finish out docs for bastion vs pgAdmin & direct ports
Browse files Browse the repository at this point in the history
  • Loading branch information
mrjones-plip committed Dec 6, 2024
1 parent 34d9da7 commit 43eb426
Showing 1 changed file with 44 additions and 20 deletions.
64 changes: 44 additions & 20 deletions content/en/hosting/analytics/setup-docker-compose.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,54 +32,78 @@ The first time you run the commands from any of the sections below it will need

### Separate CouchDB instance

This setup involves starting couch2pg, PostgreSQL, pgAdmin and dbt. It assumes you have a CouchDB instance running, and you updated the `.env` CouchDB variables accordingly.
This setup involves starting couch2pg, PostgreSQL and dbt. It assumes you have a CouchDB instance running, and you updated the `.env` CouchDB variables accordingly.

Run the Docker containers locally and wait for every container to be up and running:
```sh
docker compose -f docker-compose.postgres.yml -f docker-compose.yml up -d
```

You can verify this command worked by running `docker ps`. It should show 4 containers running including couch2pg, dbt and PostgreSQL.
You can verify this command worked by running `docker ps`. It should show 3 containers running including couch2pg, dbt and PostgreSQL:

#### Postgres access
```shell
docker ps --format "table {{.Image}}\t{{.Status}}\t{{.Names}}" --filter "name=cht-sync*"
IMAGE STATUS NAMES
cht-sync-couch2pg Up 59 seconds cht-sync-couch2pg-1
cht-sync-dbt Up About a minute cht-sync-dbt-1
postgres:16 Up About a minute cht-sync-postgres-1
```

### Separate CouchDB and PostgreSQL instances

This local setup involves starting couch2pg and dbt. It assumes that CouchDB and PostgreSQL instances are run separately from the Docker Compose provided with CHT Sync, and the `.env` variables were updated to match those instances details.

If you need to have remote access to the Postgres instance running in docker you have two options. The first is to run an instance of the `pgadmin` [application](https://www.pgadmin.org/). Be aware that this exposes an administrative interface with no password. Generally this should A) be used with development setups only and B) always be secured immediately after deploying.
Run the Docker containers locally and wait for every container to be up and running:

Run it with the following compose call:
```sh
docker compose -f docker-compose.pgadmin.yml -f docker-compose.postgres.yml -f docker-compose.yml up -d
docker compose -f docker-compose.yml up -d
```

The pgadmin app will be accessible at `http://your-server.com/5050`

The more secure and production ready option is to run a bastion host. First start by copying the `./bastion/authorized_keys.example` file to `./bastion/authorized_keys`. Add the SSH keys in `authorized_keys`, one per line, that you would like to have access to the server via the bastion host.
You can verify this command worked by running `docker ps`. It should show 2 containers running: couch2pg and dbt.

Run it with the following compose call:
```sh
docker compose -f docker-compose.bastion.yml -f docker-compose.postgres.yml -f docker-compose.yml up -d
```shell
docker ps --format "table {{.Image}}\t{{.Status}}\t{{.Names}}" --filter "name=cht-sync*"
IMAGE STATUS NAMES
cht-sync-couch2pg Up 59 seconds cht-sync-couch2pg-1
cht-sync-dbt Up About a minute cht-sync-dbt-1
```

You can then set up an SSH tunnel with the following shell command, being sure to replace `YOUR-SERVER-ADDRESS` with your real server address:
### PostgreSQL access

By default, the PostgreSQL server is only accessible to `dbt` and `couch2pg` via the Docker network. This is an intentional secure by default design. If you need to have remote access to PostgreSQL, you have two options:

1. Development: Run [pgAdmin](https://www.pgadmin.org/) and also expose PostgreSQL ports
2. Production: Run a bastion host and use SSH tunnels

#### PGAdmin + PostgreSQL ports

pgAdmin is a web GUI client for PostgreSQL. Run it with the following compose call:

```sh
ssh -N -L 5432:cht-sync-postgres-1:5432 bastion@YOUR-SERVER-ADDRESS -p 22222
docker compose -f docker-compose.pgadmin.yml -f docker-compose.postgres.yml -f docker-compose.yml up -d
```

The point your Postgres client of choice to `127.0.0.1:5432` to access the database.
Be aware that this exposes an the pgAdmin app with no password. Always secure this immediately after deploying by logging in and it will request you to set a password. The pgadmin app will be accessible at `http://your-server.com:5050`.

Additionally, `docker-compose.pgadmin.yml` file extends the PostgreSQL Docker service to expose it on the standard `5432` port. Using any PostgreSQL client, you can connect using the IP of your server.

### Separate CouchDB and PostgreSQL instances
#### Bastion host

This local setup involves starting couch2pg and dbt. It assumes that CouchDB and PostgreSQL instances are run separately from the Docker Compose provided with CHT Sync, and the `.env` variables were updated to match those instances details.
The more secure and production ready option is to run a bastion host. First start by copying the `./bastion/authorized_keys.example` file to `./bastion/authorized_keys`. Add the SSH keys of users who need access, one per line, in the `authorized_keys` you just created.

Start the bastion host, along with other services, with the following compose call:

Run the Docker containers locally and wait for every container to be up and running:
```sh
docker compose -f docker-compose.yml up -d
docker compose -f docker-compose.bastion.yml -f docker-compose.postgres.yml -f docker-compose.yml up -d
```

You can verify this command worked by running `docker ps`. It should show 2 containers running: couch2pg and dbt.
You can then set up an SSH tunnel with the following shell command, being sure to replace `YOUR-SERVER-ADDRESS` with your real server address:

```sh
ssh -N -L 5432:cht-sync-postgres-1:5432 bastion@YOUR-SERVER-ADDRESS -p 22222
```

Then point your PostgreSQL client of choice to `YOUR-SERVER-ADDRESS:5432` to access the database, again being sure to replace `YOUR-SERVER-ADDRESS` with your real server address.

### Cleanup

Expand Down

0 comments on commit 43eb426

Please sign in to comment.