docs: reconcile deployment env guidance

gildesmarais · gildesmarais · commit 64d112923f0c · 2026-03-28T13:49:46.000+01:00
diff --git a/examples/deployment/.env b/examples/deployment/.env
@@ -0,0 +1,26 @@
+# Domain & routing
+CADDY_HOST=example.com
+
+# Core runtime
+RACK_ENV=production
+
+# Security
+# Generate with: openssl rand -hex 32
+HTML2RSS_SECRET_KEY=replace-with-64-hex-characters-generated-by-openssl-rand-hex-32
+
+# Authenticated health endpoint token
+# Required by the documented Compose stack.
+# If you build a custom stack and probe only /api/v1/health/live and /api/v1/health/ready,
+# you can omit this value.
+HEALTH_CHECK_TOKEN=replace-with-strong-health-token
+
+# Auto source (optional; keep false unless you need automatic feed generation)
+AUTO_SOURCE_ENABLED=false
+
+# Observability (optional)
+#SENTRY_DSN=
+
+# Performance tuning (override defaults only when needed)
+WEB_CONCURRENCY=2
+WEB_MAX_THREADS=5
+RACK_TIMEOUT_SERVICE_TIMEOUT=15
diff --git a/examples/deployment/docker-compose.yml b/examples/deployment/docker-compose.yml
@@ -1,7 +1,12 @@
 services:
   html2rss-web:
     image: html2rss/web:latest
-    env_file: .env
+    restart: unless-stopped
+    env_file:
+      - path: .env
+        required: false
+    environment:
+      PORT: 4000
 
   caddy:
     image: caddy:2-alpine
@@ -28,9 +33,7 @@ services:
     command:
       - --cleanup
       - --interval
-      - "300"
-      - html2rss-web
-      - caddy
+      - "7200"
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock:ro
     restart: unless-stopped
diff --git a/src/components/docs/DockerComposeSnippet.astro b/src/components/docs/DockerComposeSnippet.astro
@@ -21,6 +21,8 @@ const snippets: Record<Props["variant"], string> = {
     environment:
       RACK_ENV: production
       PORT: 4000
+      BUILD_TAG: \${BUILD_TAG:-local}
+      GIT_SHA: \${GIT_SHA:-local}
       HTML2RSS_SECRET_KEY: \${HTML2RSS_SECRET_KEY:?set HTML2RSS_SECRET_KEY}
       HEALTH_CHECK_TOKEN: \${HEALTH_CHECK_TOKEN:?set HEALTH_CHECK_TOKEN}
       SENTRY_DSN: \${SENTRY_DSN:-}
@@ -35,7 +37,7 @@ const snippets: Record<Props["variant"], string> = {
     environment:
       PORT: 4002
       CONCURRENT: 10
-      TOKEN: your-browserless-token`,
+      TOKEN: \${BROWSERLESS_IO_API_TOKEN:?set BROWSERLESS_IO_API_TOKEN}`,
   productionCaddy: `services:
   caddy:
     image: ${caddyImage}
@@ -62,6 +64,8 @@ const snippets: Record<Props["variant"], string> = {
     environment:
       RACK_ENV: production
       PORT: 4000
+      BUILD_TAG: \${BUILD_TAG:-local}
+      GIT_SHA: \${GIT_SHA:-local}
       HTML2RSS_SECRET_KEY: \${HTML2RSS_SECRET_KEY:?set HTML2RSS_SECRET_KEY}
       HEALTH_CHECK_TOKEN: \${HEALTH_CHECK_TOKEN:?set HEALTH_CHECK_TOKEN}
       SENTRY_DSN: \${SENTRY_DSN:-}
@@ -88,6 +92,8 @@ volumes:
     environment:
       RACK_ENV: production
       PORT: 4000
+      BUILD_TAG: \${BUILD_TAG:-local}
+      GIT_SHA: \${GIT_SHA:-local}
       HTML2RSS_SECRET_KEY: \${HTML2RSS_SECRET_KEY:?set HTML2RSS_SECRET_KEY}
       HEALTH_CHECK_TOKEN: \${HEALTH_CHECK_TOKEN:?set HEALTH_CHECK_TOKEN}
       SENTRY_DSN: \${SENTRY_DSN:-}
@@ -106,7 +112,7 @@ volumes:
     image: ${watchtowerImage}
     restart: unless-stopped
     volumes:
-      - /var/run/docker.sock:/var/run/docker.sock
+      - /var/run/docker.sock:/var/run/docker.sock:ro
       # Optional for private registries only:
       # - "\${HOME}/.docker/config.json:/config.json:ro"
     command: --cleanup --interval 7200`,
diff --git a/src/content/docs/web-application/how-to/automatic-updates.mdx b/src/content/docs/web-application/how-to/automatic-updates.mdx
@@ -5,6 +5,23 @@ sidebar:
   order: 10
 ---
 
-The [watchtower](https://containrrr.dev/watchtower/) service automatically pulls running Docker images and checks for updates. If an update is available, it will automatically start the updated image with the same configuration as the running one. Please read its manual.
+import DockerComposeSnippet from "../../../../components/docs/DockerComposeSnippet.astro";
 
-The `docker-compose.yml` in the [Installation Guide](/web-application/getting-started#installation-guide) contains a service description for watchtower.
+Use [watchtower](https://containrrr.dev/watchtower/) to periodically pull and restart containers when newer images are available.
+
+Add this service to your existing `docker-compose.yml`:
+
+<DockerComposeSnippet variant="watchtower" />
+
+Then restart the stack:
+
+```bash
+docker compose up -d
+```
+
+Operational note:
+
+- Keep the Docker socket mount (read-only in this example).
+- Add the optional Docker config mount only if you pull private images that require registry auth.
+- The shown Watchtower command updates all running containers by default.
+- Check `docker compose logs watchtower` to confirm scans and update runs.
diff --git a/src/content/docs/web-application/how-to/deployment.mdx b/src/content/docs/web-application/how-to/deployment.mdx
@@ -27,7 +27,8 @@ Before exposing html2rss-web, ensure:
 - Your domain (for example `yourdomain.com`) resolves to the host running Docker
 - Inbound TCP ports 80 and 443 reach the host (check firewalls and cloud security groups)
 - You are ready to watch the first deployment logs for certificate issuance
-- You have values ready for `HTML2RSS_SECRET_KEY` and `HEALTH_CHECK_TOKEN`
+- You have a value ready for `HTML2RSS_SECRET_KEY`
+- You have a value ready for `HEALTH_CHECK_TOKEN` (required by the documented Compose stack)
 
 If you plan to enable automatic feed generation, also prepare:
 
@@ -47,20 +48,27 @@ Caddy handles certificates and redirects with almost no configuration.
 
 - Create a `.env` file beside your compose file with the following variables:
 
-  ```bash
+  ```env
   # Required for reverse proxy and application
   CADDY_HOST=yourdomain.com
-  HTML2RSS_SECRET_KEY= # Generate with: openssl rand -hex 32
-  HEALTH_CHECK_TOKEN= # Generate a strong token for /api/v1/health
-  BROWSERLESS_IO_API_TOKEN= # Required by the default compose stack
-  # Optional: see [environment reference](/web-application/reference/env-variables)
+  # Generate with: openssl rand -hex 32
+  HTML2RSS_SECRET_KEY=
+  # Required by the documented Compose stack
+  HEALTH_CHECK_TOKEN=
+  # Required by the default compose stack
+  BROWSERLESS_IO_API_TOKEN=
+  # Recommended for production traceability (compose defaults to local)
+  BUILD_TAG=
+  # Recommended for production traceability (compose defaults to local)
+  GIT_SHA=
   ```
 
 - Update your `.env` before starting the stack:
   - Set `CADDY_HOST` for your domain.
   - Generate a production secret (`openssl rand -hex 32`) and assign it to `HTML2RSS_SECRET_KEY`.
-  - Generate a strong `HEALTH_CHECK_TOKEN` for `/api/v1/health`.
-  - Adjust optional knobs such as `AUTO_SOURCE_ENABLED`, `SENTRY_DSN`, `BUILD_TAG`, and `GIT_SHA` as needed; refer to the [environment reference](/web-application/reference/env-variables) for details.
+  - Set a strong `HEALTH_CHECK_TOKEN` (required by the documented Compose stack).
+  - Set `BUILD_TAG` and `GIT_SHA` to real release metadata for production.
+  - Adjust optional knobs such as `AUTO_SOURCE_ENABLED` and `SENTRY_DSN` as needed; refer to the [environment reference](/web-application/reference/env-variables) for details.
 - After `docker compose up -d`, run `docker compose logs caddy --tail 20`; look for `certificate obtained`.
 - Re-test after DNS changes with [SSL Labs](https://www.ssllabs.com/ssltest/).
 - Want automatic updates? Add the Watchtower service shown below.
@@ -69,7 +77,7 @@ Caddy handles certificates and redirects with almost no configuration.
 
 Harden the application before inviting other users:
 
-- Set strong credentials for health checks and any protected feeds
+- Set a strong `HEALTH_CHECK_TOKEN` for authenticated `GET /api/v1/health`, and strong credentials for any protected feeds
 - Prefer environment files (`.env`) stored outside version control for secrets
 - Keep any operator-only token distribution flow outside public docs and outside version control
 
@@ -90,6 +98,8 @@ Keep the instance healthy once it is in production:
 
 <DockerComposeSnippet variant="watchtower" />
 
+This Watchtower shape updates all containers in the Docker host by default (not only `html2rss-web`).
+
 Check `docker compose logs watchtower` occasionally to confirm updates are applied.
 
 ### Resource Guardrails
diff --git a/src/content/docs/web-application/reference/env-variables.mdx b/src/content/docs/web-application/reference/env-variables.mdx
@@ -5,19 +5,19 @@ description: "Configuration reference for html2rss-web environment variables."
 
 ## Supported ENV variables
 
-| Name                              | Description                                                                                                   |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `HTML2RSS_SECRET_KEY`             | required in production; development/test gets a temporary default                                             |
-| `HEALTH_CHECK_TOKEN`              | bearer token for `GET /api/v1/health`; optional but recommended                                               |
-| `BUILD_TAG`                       | optional build metadata (typically set by CI image builds)                                                    |
-| `GIT_SHA`                         | optional commit metadata (typically set by CI image builds)                                                   |
-| `SENTRY_DSN`                      | optional; enables Sentry errors/logs when set                                                                 |
-| `BROWSERLESS_IO_WEBSOCKET_URL`    | optional; Browserless websocket endpoint for `browserless` strategy                                           |
-| `BROWSERLESS_IO_API_TOKEN`        | optional for local default endpoint; required when `BROWSERLESS_IO_WEBSOCKET_URL` points to a custom endpoint |
-| `AUTO_SOURCE_ENABLED`             | `true` by default in development/test, `false` otherwise                                                      |
-| `ASYNC_FEED_REFRESH_ENABLED`      | optional boolean; default `false`                                                                             |
-| `ASYNC_FEED_REFRESH_STALE_FACTOR` | optional integer `>= 1`; default `3`                                                                          |
-| `PORT`                            | app listen port; compose uses `4000`                                                                          |
-| `RACK_ENV`                        | Rack environment; compose uses `production`                                                                   |
+| Name                              | Description                                                                                                                                                                                   |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `HTML2RSS_SECRET_KEY`             | required in production; development/test gets a temporary default                                                                                                                             |
+| `HEALTH_CHECK_TOKEN`              | bearer token for authenticated `GET /api/v1/health`; required by the documented Compose stack, but custom stacks that probe only `/api/v1/health/live` and `/api/v1/health/ready` can omit it |
+| `BUILD_TAG`                       | defaults to `local` in the Compose stack; set release metadata explicitly in production                                                                                                       |
+| `GIT_SHA`                         | defaults to `local` in the Compose stack; set deployed commit SHA explicitly in production                                                                                                    |
+| `SENTRY_DSN`                      | optional; enables Sentry errors/logs when set                                                                                                                                                 |
+| `BROWSERLESS_IO_WEBSOCKET_URL`    | optional; Browserless websocket endpoint for `browserless` strategy                                                                                                                           |
+| `BROWSERLESS_IO_API_TOKEN`        | required by this site's Compose stack and by custom websocket endpoints; standalone `html2rss` local defaults can omit it                                                                     |
+| `AUTO_SOURCE_ENABLED`             | `true` by default in development/test, `false` otherwise                                                                                                                                      |
+| `ASYNC_FEED_REFRESH_ENABLED`      | optional boolean; default `false`                                                                                                                                                             |
+| `ASYNC_FEED_REFRESH_STALE_FACTOR` | optional integer `>= 1`; default `3`                                                                                                                                                          |
+| `PORT`                            | app listen port; compose uses `4000`                                                                                                                                                          |
+| `RACK_ENV`                        | Rack environment; compose uses `production`                                                                                                                                                   |
 
 Older environment-variable examples from previous docs revisions are obsolete. Use only the supported table above and the `Environment & Runtime Flags` table in [`html2rss-web/docs/README.md`](https://github.com/html2rss/html2rss-web/blob/master/docs/README.md).
