Upgrading

Semantic versioning: minor and patch releases are backward-compatible. A major release may break things; its Changelog entry says what.

Standard upgrade procedure

# Back up first: a rollback needs it
$ docker compose exec db pg_dump -U openwhistle openwhistle > backup.sql

# The compose file and nginx config change between releases
$ git pull

# Set OPENWHISTLE_VERSION in .env to the new version, then
$ docker compose pull
$ docker compose up -d

# Migrations run at startup; the version is in the health check
$ curl -sk https://localhost/health

Before upgrading

• Read the Changelog for the target version.
• v2.0.0 adds ENCRYPTION_KEY, a key for encryption separate from SECRET_KEY: see Rotating the encryption key.

Upgrading to 2.0.0 with Docker Compose

• git pull is required, not only docker compose pull: the stack needs the new nginx/snippets/ and the tls-init service.
• A customised nginx/nginx.conf makes git pull conflict: replace it with the shipped one (git checkout -- nginx/nginx.conf).
• Certificates move from the old ./nginx/certs:/etc/nginx/certs mount to nginx/certs/ as fullchain.pem and privkey.pem, copied, not symlinked. Without them, a self-signed certificate is served.
• Port 80 now only redirects to 443. Behind an external TLS terminator, see Behind a TLS-terminating proxy.
• nginx also publishes 127.0.0.1:8080 (the onion listener). If another service on the host uses 8080, up fails: free the port first.

Rollback

The previous image refuses to start on a migrated database. Two ways back:

• Restore the backup into an empty database and pin the old OPENWHISTLE_VERSION.
• From 2.0.0 to 1.5.x: downgrade the schema with the 2.0.0 image first, then pin the old version:

$ docker compose run --rm app alembic downgrade 7d4e2b9c1a05
# then set OPENWHISTLE_VERSION=1.5.0 in .env
$ docker compose up -d

The downgrade decrypts the TOTP secrets again and needs the same encryption keys. Migration 006 rounded whistleblower times to the day; the downgrade keeps them rounded, the exact times are gone by design.