Deploy with Docker Compose

One machine runs all of BostonIvy: PostgreSQL, the server and BostonIvy Web, described in deploy/compose.yaml of the bostonivy-os repository. This is the quickest way to start, and it is enough for a family or a small team.

Before you start

Docker with Compose v2 (docker compose version prints v2.x).
The deploy files: the deploy folder of bostonivy-os, with compose.yaml, https.yaml and .env.example.
Access to the images. They are private packages on GitHub Container Registry. Sign in once with a GitHub token that has the read:packages scope:

echo "$GITHUB_TOKEN" | docker login ghcr.io -u <your GitHub username> --password-stdin

Start BostonIvy

Create your settings from the example:
```
cd deploy
cp .env.example .env
```
Generate the server secret, and paste it into .env as BOSTONIVY_AUTH_SECRET:
```
docker compose run --rm --no-deps bostonivy keygen
```
Start everything:
```
docker compose up -d
```
Open http://localhost:8080 and create an account. On a new database the first account becomes the administrator. Whether other people can sign up afterwards is up to auth.open_registration and the setting in the admin panel.

docker compose ps should show all three services as healthy. The server migrates the database every time it starts, so there is nothing else to run.

The example .env sets BOSTONIVY_COOKIE_SECURE=false, which only works on plain http://localhost. Before anyone else uses the server, set up HTTPS (below) and change it to true.

Settings

All settings are in deploy/.env:

Variable	Meaning
`BOSTONIVY_AUTH_SECRET`	Required. Every signing and encryption key is derived from it. If you lose it, everyone has to sign in again, and the stored TOTP and webhook secrets can no longer be decrypted. Back it up
`BOSTONIVY_URL`	The address people open. Links in mail and share links use it
`BOSTONIVY_PORT`	The port on this machine, `8080` by default
`BOSTONIVY_COOKIE_SECURE`	`true` in production, which requires HTTPS. `false` only for trying it out on `http://localhost`, otherwise sign-in does not survive a page reload
`BOSTONIVY_SMTP_URL`, `BOSTONIVY_MAIL_FROM`	Mail. For example `smtps://user:password@smtp.example.com` and `BostonIvy <noreply@example.com>`. Empty sends no mail; `log` writes mail to the server log, which is handy for a trial
`POSTGRES_PASSWORD`	The database password
`BOSTONIVY_VERSION`	The image tag; `latest` follows the newest release
`BOSTONIVY_SITE`	Caddy's site address; see HTTPS below

Every other server setting (rate limits, Redis, webhooks, object storage, the grace period for deleting an account, and so on) can be set as an environment variable named BOSTONIVY_<SECTION>__<KEY>, for example BOSTONIVY_STORAGE__KIND=s3. Add it under bostonivy.environment in compose.yaml. bostonivy.example.toml in bostonivy-os lists them all.

HTTPS

Choose one:

Let Caddy get a certificate. Point your domain at this machine, then set these in .env:
```
BOSTONIVY_SITE=tasks.example.com
BOSTONIVY_URL=https://tasks.example.com
BOSTONIVY_COOKIE_SECURE=true
```
and start with the HTTPS override, which opens ports 80 and 443:
```
docker compose -f compose.yaml -f https.yaml up -d
```
Caddy requests and renews the certificate by itself and keeps it in the caddy volume.
Behind a reverse proxy you already run. Keep BOSTONIVY_SITE=:80, point the proxy at BOSTONIVY_PORT, and make sure it forwards WebSocket connections on /api/v1/realtime, which carry live updates.

Back up and upgrade

Back up three things:

The database:

docker compose exec postgres pg_dump -U bostonivy bostonivy > backup.sql

Attachments and avatars: the files volume (or your bucket, if you moved them to S3).
The secret: BOSTONIVY_AUTH_SECRET in .env.

To upgrade, pull the new images and restart:

docker compose pull && docker compose up -d

The new version migrates the database when it starts. Migrations only add, never remove, so together with a backup you can go back to the previous version.

Command line

docker compose exec bostonivy bostonivy admin promote <username>   # make someone an administrator
echo "new password" | docker compose exec -T bostonivy bostonivy admin set-password <username>
docker compose exec bostonivy bostonivy health                     # health check

Build the images yourself

Check out bostonivy-web next to bostonivy-os, or point BOSTONIVY_WEB_SOURCE in .env at it. The web app uses the private BostonIvy design package, so the build needs a token that can read IvyLabsApp's private repositories. It is used only as a build secret and never ends up in the image:

cd deploy
GITHUB_TOKEN=$(gh auth token) docker compose build
docker compose up -d