v0.2.3

docker/README.md

@@ -2,10 +2,26 @@
 
 Run all commands from the `docker/` directory.
 
-The Compose files use the project name `rustbox` and the examples below additionally pass `-p rustbox`. Using `-p` is intentional: a globally exported `COMPOSE_PROJECT_NAME` has higher priority than the `name: rustbox` field in a Compose file and could otherwise attach RustBox to an unrelated Compose project/network.
+Most Compose files use the project name `rustbox`; the HA/Garage example uses `rustbox-ha`. The examples pass `-p` explicitly so an exported `COMPOSE_PROJECT_NAME` cannot attach RustBox to an unrelated Compose project/network.
 
 ## Quick start
 
+Two RustBox nodes + Envoy + Valkey + PostgreSQL + OpenSearch + Garage S3:
+
+```bash
+PORT=3009 \
+IMAP_HOST=mail.linuxiarz.pl \
+SMTP_HOST=mail.linuxiarz.pl \
+docker compose -p rustbox-ha -f compose-ha-garage.yml up --build
+```
+
+Verify load balancing and the selected backend header:
+
+```bash
+curl -sSI http://localhost:3009/ | grep -i '^x-rustbox-backend:'
+curl -sSI http://localhost:3009/ | grep -i '^x-rustbox-backend:'
+```
+
 PostgreSQL + S3/SILO + OpenSearch:
 
 ```bash
@@ -58,7 +74,7 @@ cp .env.example .env
 | Variable | Default | Used by | Description |
 |---|---|---|---|
 | `HOST` | `0.0.0.0` | all | Address RustBox listens on inside the container. |
-| `PORT` | `3001` | all | RustBox HTTP port. The same value is used for the container listener and host port mapping. Example: `PORT=3009` publishes `3009:3009`. |
+| `PORT` | `3001` | all | Published HTTP port. Single-node examples also use it as the RustBox listener; HA keeps RustBox on `3001` internally and maps `${PORT}` to Envoy `8080`. |
 | `IMAP_HOST` | `mail.example.com` | all | IMAP server hostname used for mailbox access/authentication. Set this for a real mail system. |
 | `IMAP_PORT` | `993` | all | IMAP server port. |
 | `SMTP_HOST` | `mail.example.com` | all | SMTP server hostname used for sending mail. |
@@ -73,6 +89,13 @@ cp .env.example .env
 | `MYSQL_ROOT_PASSWORD` | `rustbox-root-password` | MySQL/NFS | MySQL root password used by the container and health check. |
 | `NFS_SERVER` | none | MySQL/NFS | NFS server address. Required for `compose-mysql-nfs-opensearch.yml`. |
 | `NFS_EXPORT` | `/rustbox` | MySQL/NFS | Export path on the NFS server. |
+| `GARAGE_ACCESS_KEY_ID` | development key | HA/Garage | Garage S3 access key imported by the one-shot initializer. Replace outside local testing. |
+| `GARAGE_SECRET_ACCESS_KEY` | development secret | HA/Garage | Garage S3 secret key. Replace outside local testing. |
+| `GARAGE_CAPACITY` | `10G` | HA/Garage | Capacity assigned to the single Garage node for layout balancing. |
+| `SIEVE_ENABLED` | `false` | HA/Garage | Enables ManageSieve routes/UI on both RustBox nodes. |
+| `DIAGNOSTICS_ENABLED` | `true` | HA/Garage | Enables diagnostics routes/UI. |
+| `ABOUT_ENABLED` | `true` | HA/Garage | Enables the About panel; keyboard shortcuts stay available independently. |
+| `SECURITY_HEADERS_ENABLED` | `false` | HA/Garage | Enables RustBox browser security headers. |
 | `COMPOSE_PROJECT_NAME` | `rustbox` in `.env.example` | Compose | Compose project name. A value exported in the shell overrides the file's `name:`. The documented commands use `-p rustbox`, which has the highest priority. |
 
 `RUSTBOX_CONFIG` and `DATABASE_URL` are set by the Compose files themselves and normally should not be supplied from the shell for these bundled topologies.
@@ -100,6 +123,14 @@ docker compose -p rustbox -f compose-postgres-s3-opensearch.yml \
 
 ## Topologies
 
+### `compose-ha-garage.yml`
+
+Runs two RustBox application containers behind Envoy round-robin load balancing. PostgreSQL stores account/application state, Valkey stores shared sessions, OpenSearch provides the shared search index, and Garage provides S3-compatible blob storage. Only Envoy publishes a host port; the application nodes stay internal.
+
+Envoy adds `X-RustBox-Backend` with the selected upstream address to every proxied response. WebSocket upgrades are enabled and Envoy health-checks `/api/health` on both nodes. The example uses a fixed Docker subnet because Garage advertises its RPC address; change `172.28.80.0/24` in both the Compose file and `configs/ha-garage.toml` if it conflicts with your network.
+
+Garage is a single storage node in this local example. The application tier is redundant, but the backing services are not an HA production cluster by themselves.
+
 ### `compose-single-sqlite.yml`
 
 Single RustBox node with SQLite, filesystem blob storage and local Tantivy search. Persistent application data is stored in the `rustbox-data` Docker volume.
@@ -120,7 +151,7 @@ Replace all example passwords, S3 credentials and `SESSION_ENCRYPTION_KEY` befor
 
 The OpenSearch examples disable its security plugin to keep the local Compose topology self-contained. Production should use TLS/authentication and HTTPS URLs in `search.urls`.
 
-The two cluster-ready examples intentionally start one RustBox application container so they can run directly on a single Docker host. For multiple RustBox application nodes, put them behind an external load balancer and do not publish the same host port from every node; SQL, blob storage and OpenSearch must remain shared between the nodes.
+The PostgreSQL/SILO and MySQL/NFS examples intentionally start one RustBox application container. `compose-ha-garage.yml` demonstrates two application nodes sharing SQL, sessions, blob storage and search behind Envoy. For production, make the backing PostgreSQL/Valkey/OpenSearch/Garage services appropriately redundant and terminate TLS before or at the load balancer.
 
 ## Sessions and HTTP/HTTPS
 
@@ -132,6 +163,12 @@ For a production deployment behind HTTPS set:
 ENVIRONMENT=production docker compose -p rustbox -f compose-postgres-s3-opensearch.yml up -d --build
 ```
 
+For the HA example, expose Envoy only behind HTTPS/TLS termination and use:
+
+```bash
+ENVIRONMENT=production docker compose -p rustbox-ha -f compose-ha-garage.yml up -d --build
+```
+
 In `production`, RustBox intentionally marks authentication cookies as `Secure`. Opening the application directly over plain HTTP in that mode causes the browser not to send the session cookie and protected requests return `Invalid or expired session`.
 
 After changing from production/HTTP to development/HTTP, log in again. If the browser still has stale RustBox state, clear cookies/site data for the RustBox origin once and reload.
@@ -164,4 +201,4 @@ docker compose -p rustbox -f compose-postgres-s3-opensearch.yml exec opensearch
   -d '{"index.blocks.read_only_allow_delete":null}'
 ```
 
-RustBox 0.2.2 backs off its OpenSearch outbox worker after these 429/flood-stage responses, so a full disk no longer produces one warning per queued event.
+RustBox 0.2.3 retains the OpenSearch outbox backoff introduced in 0.2.2, so these 429/flood-stage responses no longer produce one warning per queued event on a full disk.