shorten deployment example READMEs

Author: overheadhunter

deploy/README.md

@@ -1,12 +1,12 @@
-# Deploying Cryptomator Hub
+# Cryptomator Hub Deployment Examples
 
 Hub consists of three services: the Hub application itself, [Keycloak](https://www.keycloak.org/) as identity provider and a PostgreSQL database shared by both. The guides below are **examples** for common scenarios — each one is a complete, tested walkthrough, but by no means the only way to run Hub. Every option they use is a regular chart value or compose setting, so mix and match as your environment requires (see [`values.yaml`](../chart/values.yaml) for everything the chart can do). Pick the scenario closest to yours:
 
 | I want to… | Go to |
 |---|---|
 | Try Hub on my machine with a single `docker compose up` | [`compose/local/`](compose/local/README.md) |
+| Run Hub in production on a single Docker host | [`compose/prod/`](compose/prod/README.md) |
 | Run Hub in production on Kubernetes | [`helm/prod/`](helm/prod/README.md) |
 | Connect Hub to a Keycloak I already operate | [`helm/existing-keycloak/`](helm/existing-keycloak/README.md) |
-| Install Hub through the Rancher UI | [`helm/prod/`](helm/prod/README.md#rancher) |
 | Develop Hub and run a locally built image against the dev realm | [`compose/dev/`](compose/dev/README.md) |
 | Develop the Helm chart or test a locally built image on Kubernetes | [`helm/dev/`](helm/dev/README.md) |

deploy/compose/dev/README.md

@@ -1,35 +1,19 @@
 # Development stack with Docker Compose
 
-Runs a **locally built** Hub image together with Keycloak and PostgreSQL, wired up exactly like the Quarkus dev services that `./mvnw quarkus:dev` starts. Use it to test a container build of Hub (e.g. the native image) end-to-end before pushing, or to poke at memory settings of the native binary.
+Runs a **locally built** Hub image together with Keycloak and PostgreSQL, wired up like the Quarkus dev services that `./mvnw quarkus:dev` starts. Use it to test a container build of Hub end-to-end, or to poke at memory settings of the native binary. If you just want to try Hub, use [`../local/`](../local/README.md) instead.
 
-If you just want to try Hub, use [`../local/`](../local/README.md) instead — it needs nothing from this repository.
+Prerequisites:
 
-## Prerequisites
+- A checkout of this repository; all commands below run from its root. [`compose.yaml`](compose.yaml) bind-mounts the dev realm from `backend/src/main/resources/cryptomator-realm.json`.
+- Docker Compose ≥ 2.23.1, `pnpm`.
 
-- A checkout of this repository: [`compose.yaml`](compose.yaml) bind-mounts the dev realm from `backend/src/main/resources/cryptomator-realm.json`.
-- A locally built Hub image tagged `ghcr.io/cryptomator/hub:native`. The Dockerfile only copies `backend/src`, so the frontend has to be built into `backend/src/main/resources/META-INF/resources` first. From the repository root:
+1. Build the frontend, then the backend as a native image (the Dockerfile only copies `backend/src`, so the frontend must be built into it first):
 
-  ```bash
-  (cd frontend && pnpm install && pnpm dist)
-  docker build -f backend/src/main/docker/Dockerfile.native -t ghcr.io/cryptomator/hub:native backend
-  ```
+   ```bash
+   (cd frontend && pnpm install && pnpm dist)
+   docker build -f backend/src/main/docker/Dockerfile.native -t ghcr.io/cryptomator/hub:native backend
+   ```
+2. `docker compose -f deploy/compose/dev/compose.yaml up`
+3. Wait until all services are `healthy`, then open Hub at <http://localhost:8080> (`admin` / `admin`, `alice` / `asd`, `bob` / `asd`, … from the dev realm) or the Keycloak admin console at <http://localhost:8180> (`admin` / `admin`).
 
-## Usage
-
-```bash
-docker compose up
-```
-
-Paths in `compose.yaml` are resolved relative to this directory, so the command works from anywhere via `docker compose -f deploy/compose/dev/compose.yaml up`.
-
-| URL | Credentials |
-|---|---|
-| Hub: <http://localhost:8080> | `admin` / `admin`, `alice` / `asd`, `bob` / `asd`, … (see the dev realm) |
-| Keycloak admin console: <http://localhost:8180> | `admin` / `admin` |
-
-The dev realm is imported on Keycloak's first boot only; run `docker compose down -v` to reset the database and re-import it.
-
-## Differences to the local stack
-
-- Hub runs from the `:native` tag you built, with a 48 MiB memory limit and `-XX:MaximumHeapSizePercent` / `MALLOC_ARENA_MAX` overrides for measuring the native image's footprint. Adjust or drop these when you're not interested in memory behaviour.
-- The realm comes from `backend/src/main/resources/cryptomator-realm.json` and contains the well-known dev users, the `cryptomatorhub-cli` client and `localhost:3000` (Vite dev server) as an allowed redirect URI.
+The `hub` service runs with a 48 MiB memory limit and `-XX:MaximumHeapSizePercent` / `MALLOC_ARENA_MAX` overrides for measuring the native image's footprint; adjust or drop them in `compose.yaml` when you're not interested in memory behaviour. The realm is imported on Keycloak's first boot only — `docker compose -f deploy/compose/dev/compose.yaml down -v` to start over.

deploy/compose/local/README.md

@@ -2,50 +2,12 @@
 
 A self-contained Cryptomator Hub stack with pinned image versions for trying Hub on your machine. [`compose.yaml`](compose.yaml) is the only file you need; it does not reference anything else in this repository.
 
-Requirements: Docker Compose ≥ 2.23.1 (inline `configs.content`).
+Requirements: Docker Compose ≥ 2.23.1.
 
-## Quick start
+1. Download [`compose.yaml`](compose.yaml) into an empty directory.
+2. `docker compose up`
+3. Wait until all services are `healthy` (Keycloak imports the realm on first start), then open Hub at <http://localhost:8080> or the Keycloak admin console at <http://localhost:8180>, both `admin` / `admin`.
 
-Download [`compose.yaml`](compose.yaml) (or copy it from this directory) and start the stack:
+Everything runs on plain HTTP with well-known passwords — for evaluation only. To change ports or hostnames, follow the comments in `compose.yaml`; the realm is imported on Keycloak's first boot only, so `docker compose down -v` to start over after changing URLs.
 
-```bash
-docker compose up
-```
-
-Wait until all three services report `healthy` (about a minute on first start, Keycloak imports the realm), then open:
-
-| URL | Credentials |
-|---|---|
-| Hub: <http://localhost:8080> | `admin` / `admin` |
-| Keycloak admin console: <http://localhost:8180> | `admin` / `admin` |
-
-On first login Hub asks for a license. Any Hub license works for testing; see <https://cryptomator.org/hub/> on how to obtain one. Afterwards, add users and groups in Keycloak (realm `cryptomator`) — Hub syncs them every minute. To connect a Cryptomator desktop or mobile app, create a vault in Hub and follow the instructions shown there.
-
-## What the stack contains
-
-- `postgres` with two databases (`hub`, `keycloak`), persisted in the named volume `postgres-data`.
-- `ghcr.io/cryptomator/keycloak` — the stock Keycloak image plus the Cryptomator login theme and `curl` for the health check. A minimal `cryptomator` realm (one admin user, the OIDC clients `cryptomatorhub`, `cryptomator` and `cryptomatorhub-system`) is embedded in the compose file and imported on first boot. It matches what the Helm chart renders in `chart/templates/_realm.tpl`.
-- `ghcr.io/cryptomator/hub` — the Hub application, configured through environment variables; the same settings the Helm chart uses.
-
-## Changing ports or hostnames
-
-The two published ports (`8080` for Hub, `8180` for Keycloak) appear in several places that must stay consistent: the `ports` mappings, `KC_HOSTNAME`, `HUB_KEYCLOAK_PUBLIC_URL`, `QUARKUS_OIDC_TOKEN_ISSUER`, the `connect-src` entry of the Content Security Policy, and the `redirectUris` / `frame-ancestors` of the embedded realm. Update all of them together.
-
-> [!TIP]
-> Keycloak imports the realm **only on first boot** — `--import-realm` never overwrites an existing realm. If you change URLs after the first start, Keycloak keeps the old redirect URIs and login fails with `Invalid parameter: redirect_uri`. Either edit the `cryptomatorhub` client in the Keycloak admin console, or reset everything with `docker compose down -v` (this deletes the database, including all vaults).
-
-## Not for production
-
-This file is meant for evaluation only:
-
-- All passwords (`admin`, `hub`, `keycloak`, `top-secret`) are well-known defaults.
-- Everything runs on plain HTTP on `localhost`; no TLS is configured. Hub's crypto happens in the browser and requires a secure context, which browsers grant to `localhost` but not to other plain-HTTP hosts.
-- No backups, resource limits or upgrade strategy.
-
-For real deployments use the Helm chart, see [`../../helm/prod/`](../../helm/prod/README.md) — it generates secrets, supports external PostgreSQL/Keycloak and terminates TLS at the ingress.
-
-## Upgrading
-
-Image versions are pinned in `compose.yaml`. To upgrade, change the tags and run `docker compose up -d`. Hub applies database migrations automatically at start; Keycloak upgrades follow the [Keycloak upgrade guide](https://www.keycloak.org/docs/latest/upgrading/). Always back up the `postgres-data` volume first.
-
-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/restore, see the [PostgreSQL upgrade notes](https://www.postgresql.org/docs/current/upgrading.html). The same applies to a `postgres-data` volume created by an earlier version of this stack that still ran PostgreSQL 17 — either dump it before switching images, or start fresh with `docker compose down -v`.
+For real deployments see [`../prod/`](../prod/README.md) or [`../../helm/prod/`](../../helm/prod/README.md); for everything else — license, user management, connecting Cryptomator apps — see <https://docs.cryptomator.org/hub/>.

deploy/compose/local/compose.yaml

@@ -6,6 +6,10 @@
 # Keycloak: http://localhost:8180  (bootstrap admin `admin` / `admin`)
 #
 # NOT FOR PRODUCTION: well-known passwords, plain HTTP, all services on localhost. See README.md in this directory for details.
+#
+# To change ports or hostnames, update all of these together: the `ports` mappings, `KC_HOSTNAME`, `HUB_KEYCLOAK_PUBLIC_URL`, `QUARKUS_OIDC_TOKEN_ISSUER`,
+# the `connect-src` entry of Hub's Content Security Policy, and the `redirectUris` / `frame-ancestors` of the embedded realm. Note that browsers grant a secure
+# context (required by Hub's client-side crypto) to `localhost` only — any other hostname needs TLS, see ../prod/compose.yaml.
 services:
 
   postgres:

deploy/compose/prod/README.md

@@ -0,0 +1,24 @@
+# Docker Compose in production
+
+Runs Cryptomator Hub with bundled Keycloak and PostgreSQL on a single Docker host, behind [Traefik](https://traefik.io/) with Let's Encrypt certificates. [`compose.yaml`](compose.yaml) is the only file you need; the comments in it explain what to change and how to swap in an existing proxy, PostgreSQL or Keycloak.
+
+Requirements: Docker Compose ≥ 2.23.1, a host reachable from the internet on ports 80 and 443, DNS records for the two hostnames.
+
+1. Replace all occurrences of the following placeholders in `compose.yaml`:
+
+   | Placeholder | Meaning | Used in |
+   |---|---|---|
+   | `hub.example.com` | Public hostname of Hub | Traefik router, realm redirect URI, realm `frame-ancestors` |
+   | `kc.example.com` | Public hostname of Keycloak | Traefik router, `KC_HOSTNAME`, `HUB_KEYCLOAK_PUBLIC_URL`, `QUARKUS_OIDC_TOKEN_ISSUER`, Hub's CSP `connect-src` |
+   | `admin@example.com` | Contact address for Let's Encrypt | Traefik ACME resolver |
+   | `CHANGE-ME-HUB-ADMIN-PASSWORD` | Initial password of Hub's `admin` user; must be changed on first login | realm |
+   | `CHANGE-ME-KEYCLOAK-ADMIN-PASSWORD` | Password of Keycloak's bootstrap admin `admin` | `KC_BOOTSTRAP_ADMIN_PASSWORD` |
+   | `CHANGE-ME-SYSTEM-CLIENT-SECRET` | Secret of the `cryptomatorhub-system` client, used by Hub to sync users and groups | `HUB_KEYCLOAK_SYSTEM_CLIENT_SECRET`, realm |
+   | `CHANGE-ME-HUB-DB-PASSWORD` | Password of the `hub` database user | `POSTGRES_PASSWORD`, `QUARKUS_DATASOURCE_PASSWORD` |
+   | `CHANGE-ME-KEYCLOAK-DB-PASSWORD` | Password of the `keycloak` database user | `KC_DB_PASSWORD`, `create-keycloak-db` config |
+
+   Generate secrets with `openssl rand -hex 32`. Use search & replace — most values occur more than once and all occurrences must be identical.
+2. `docker compose up -d`
+3. Wait until `docker compose ps` shows all services as `healthy`, then open `https://hub.example.com` and sign in as `admin`.
+
+For everything else — license, user management, backups, upgrades — see <https://docs.cryptomator.org/hub/>.