Skip to main content

Docker Compose

We maintain example Compose files in the Hub repository. The production example runs Hub, Keycloak, and PostgreSQL behind a Traefik reverse proxy that obtains a TLS certificate from Let's Encrypt.

Prerequisites​

  • Docker with Docker Compose 2.23.1 or newer (docker compose version).
  • Ports 80 and 443 of the host reachable from the internet (Let's Encrypt HTTP challenge) and from your users.
  • DNS records for the Hub and Keycloak hostnames pointing to the host.

Deploy​

Download the production example into an empty directory:

curl -fsSLO https://raw.githubusercontent.com/cryptomator/hub/2.0.0/deploy/compose/prod/compose.yaml

Open compose.yaml and replace every placeholder before starting the stack:

  1. The two public hostnames, in all places they appear (see Configuration).
  2. The email address for Let's Encrypt.
  3. All passwords and secrets: the PostgreSQL admin password, the database passwords of hub and keycloak, the Keycloak bootstrap admin password, the Hub admin password, and the secret of the cryptomatorhub-system client. Generate them, e.g. with openssl rand -hex 32.

Then start everything:

docker compose up -d

Keycloak takes a minute or two on first start to import the realm. Once all services are healthy, open the Hub URL, sign in as admin with the password you chose, and enter your license.

Configuration​

You can find a reference table of all settings alongside the example in the project's GitHub repository.

Never publish service ports

Traefik is the only service in the example with a ports: section. Do not add ports: to hub, keycloak, or postgres, not even "just for testing" or bound to a non-standard port.

Doing so exposes unencrypted logins, tokens, and the database to the network. Traefik reaches the services over the internal Compose network; if you need to inspect a service, use docker compose exec or an SSH tunnel instead.

Upgrading​

Back up the database first. Image versions are pinned in compose.yaml; to upgrade, change the tags and run docker compose up -d. Hub applies its database migrations automatically at start. For Keycloak, follow the Keycloak upgrade guide.

PostgreSQL minor updates (e.g. 18.6 → 18.7) are drop-in. A major update (18 → 19) is not: the data directory must be migrated with pg_upgrade or a dump and restore, see the PostgreSQL upgrade notes.