docs: relax compose startup env requirements

Author: gildesmarais

src/components/docs/DockerComposeSnippet.astro

@@ -21,8 +21,6 @@ const snippets: Record<Props["variant"], string> = {
     environment:
       RACK_ENV: production
       PORT: 4000
-      BUILD_TAG: \${BUILD_TAG:?set BUILD_TAG}
-      GIT_SHA: \${GIT_SHA:?set GIT_SHA}
       HTML2RSS_SECRET_KEY: \${HTML2RSS_SECRET_KEY:?set HTML2RSS_SECRET_KEY}
       HEALTH_CHECK_TOKEN: \${HEALTH_CHECK_TOKEN:?set HEALTH_CHECK_TOKEN}
       SENTRY_DSN: \${SENTRY_DSN:-}
@@ -64,8 +62,6 @@ const snippets: Record<Props["variant"], string> = {
     environment:
       RACK_ENV: production
       PORT: 4000
-      BUILD_TAG: \${BUILD_TAG:?set BUILD_TAG}
-      GIT_SHA: \${GIT_SHA:?set GIT_SHA}
       HTML2RSS_SECRET_KEY: \${HTML2RSS_SECRET_KEY:?set HTML2RSS_SECRET_KEY}
       HEALTH_CHECK_TOKEN: \${HEALTH_CHECK_TOKEN:?set HEALTH_CHECK_TOKEN}
       SENTRY_DSN: \${SENTRY_DSN:-}
@@ -92,8 +88,6 @@ volumes:
     environment:
       RACK_ENV: production
       PORT: 4000
-      BUILD_TAG: \${BUILD_TAG:?set BUILD_TAG}
-      GIT_SHA: \${GIT_SHA:?set GIT_SHA}
       HTML2RSS_SECRET_KEY: \${HTML2RSS_SECRET_KEY:?set HTML2RSS_SECRET_KEY}
       HEALTH_CHECK_TOKEN: \${HEALTH_CHECK_TOKEN:?set HEALTH_CHECK_TOKEN}
       SENTRY_DSN: \${SENTRY_DSN:-}
@@ -113,7 +107,8 @@ volumes:
     restart: unless-stopped
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock
-      - "\${HOME}/.docker/config.json:/config.json"
+      # Optional for private registries only:
+      # - "\${HOME}/.docker/config.json:/config.json:ro"
     command: --cleanup --interval 7200`,
   resourceGuardrails: `services:
   html2rss-web:

src/content/docs/troubleshooting/troubleshooting.mdx

@@ -129,7 +129,7 @@ If you are getting a "command not found" error, try the following:
   ```bash
   lsof -i :4000
   ```
-- If the app exits immediately in production, check that `HTML2RSS_SECRET_KEY`, `BUILD_TAG`, and `GIT_SHA` are set.
+- If the app exits immediately in production, check that `HTML2RSS_SECRET_KEY` is set.
 
 ### Can’t Access the Web Interface
 

src/content/docs/web-application/how-to/deployment.mdx

@@ -27,7 +27,7 @@ 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`, `HEALTH_CHECK_TOKEN`, `BUILD_TAG`, and `GIT_SHA`
+- You have values ready for `HTML2RSS_SECRET_KEY` and `HEALTH_CHECK_TOKEN`
 
 If you plan to enable automatic feed generation, also prepare:
 
@@ -52,8 +52,6 @@ Caddy handles certificates and redirects with almost no configuration.
   CADDY_HOST=yourdomain.com
   HTML2RSS_SECRET_KEY= # Generate with: openssl rand -hex 32
   HEALTH_CHECK_TOKEN= # Generate a strong token for /api/v1/health
-  BUILD_TAG=2026-03-27
-  GIT_SHA=abcdef0
   BROWSERLESS_IO_API_TOKEN= # Required by the default compose stack
   # Optional: see [environment reference](/web-application/reference/env-variables)
   ```
@@ -62,8 +60,7 @@ Caddy handles certificates and redirects with almost no configuration.
   - 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`.
-  - Set `BUILD_TAG` and `GIT_SHA` so startup logs identify the deployed build.
-  - 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.
+  - 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.
 - 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.

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`                    | required in production |
-| `GIT_SHA`                      | required 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`     | 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 `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`                                                                   |
 
 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).