docs: document versioned web image releases

gildesmarais · gildesmarais · commit 4efb3053d181 · 2026-05-01T10:53:41.000+02:00
diff --git a/examples/deployment/docker-compose.yml b/examples/deployment/docker-compose.yml
@@ -1,6 +1,6 @@
 services:
   html2rss-web:
-    image: html2rss/web:latest
+    image: html2rss/web:1
     restart: unless-stopped
     env_file:
       - path: .env
diff --git a/src/components/docs/DockerComposeSnippet.astro b/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:-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:-}
@@ -64,8 +62,6 @@ 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:-}
@@ -92,8 +88,6 @@ 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:-}
diff --git a/src/content/docs/web-application/how-to/automatic-updates.mdx b/src/content/docs/web-application/how-to/automatic-updates.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Automatic Updates"
-description: "Learn how to set up automatic updates for html2rss-web using watchtower. Keep your Docker containers updated automatically with the latest features."
+description: "Use Watchtower to keep html2rss-web updated within the Docker tag you selected."
 sidebar:
   order: 10
 ---
@@ -9,7 +9,9 @@ import { Code } from "@astrojs/starlight/components";
 
 import DockerComposeSnippet from "../../../../components/docs/DockerComposeSnippet.astro";
 
-Use [watchtower](https://containrrr.dev/watchtower/) to periodically pull and restart containers when newer images are available.
+Use [Watchtower](https://containrrr.dev/watchtower/) to pull newer images and restart the selected containers.
+
+Updates follow the tag in your Compose file. With the documented `html2rss/web:1` image, Watchtower stays on major version `1`.
 
 Add this service to your existing `docker-compose.yml`:
 
@@ -19,9 +21,9 @@ Then restart the stack:
 
 <Code code={`docker compose up -d`} lang="bash" />
 
-Operational note:
+Operational notes:
 
 - 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.
+- The shown command scopes updates to `html2rss-web`, `browserless`, and `caddy`; change the service names if your stack differs.
 - 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
@@ -7,11 +7,9 @@ import { Code } from "@astrojs/starlight/components";
 
 import DockerComposeSnippet from "../../../../components/docs/DockerComposeSnippet.astro";
 
-html2rss-web ships on Docker Hub, so you can launch this self-hosted service wherever Docker runs. Start with the official [`docker-compose.yml`](https://github.com/html2rss/html2rss-web/blob/main/docker-compose.yml) as your baseline, and treat the [Getting Started guide](/web-application/getting-started) as the required first proof that your instance can already serve included feeds locally.
+html2rss-web ships on Docker Hub. Start with the [Getting Started guide](/web-application/getting-started), then add the production pieces below.
 
-If you have not yet created a local instance, complete the [Getting Started guide](/web-application/getting-started) first. It walks through the one-time project directory setup, creating a minimal compose file, and confirming the application locally, which gives you the right baseline before exposing a self-hosted instance publicly.
-
-Already running html2rss-web on your workstation? The sections below focus on what changes when you take that setup to production.
+The examples use `html2rss/web:1`, the recommended major-version tag. Pin an exact release if your deployment process requires it.
 
 ## Choose Your Production Scope First
 
@@ -40,54 +38,37 @@ If you plan to enable automatic feed generation, also prepare:
 
 ### Why a Reverse Proxy?
 
-A reverse proxy accepts public HTTPS traffic, terminates TLS, and forwards requests to html2rss-web running on your private network.
+A reverse proxy terminates public HTTPS traffic and forwards requests to html2rss-web on your private Docker network.
 
 ### Option A: Caddy (Automatic HTTPS)
 
-Caddy handles certificates and redirects with almost no configuration.
+Caddy handles certificates and redirects.
 
 <DockerComposeSnippet variant="productionCaddy" />
 
-- Create a `.env` file beside your compose file with the following variables:
-
-      <Code
-      code={`
-      # Required for reverse proxy and application
-      CADDY_HOST=yourdomain.com
-
-      # Generate with: openssl rand -hex 32
-
-      HTML2RSS_SECRET_KEY=
-
-      # Required by the documented Compose stack
+Create a `.env` file beside your compose file:
 
-      HEALTH_CHECK_TOKEN=
-
-      # Required by the default compose stack
-
-      BROWSERLESS_IO_API_TOKEN=
-
-      # Recommended for production traceability (compose defaults to local)
+<Code
+  code={`
+  CADDY_HOST=yourdomain.com
+  HTML2RSS_SECRET_KEY=<openssl rand -hex 32>
+  HEALTH_CHECK_TOKEN=<strong bearer token>
+  BROWSERLESS_IO_API_TOKEN=<browserless token>
+`}
+  lang="dotenv"
+/>
 
-      BUILD_TAG=
+Before starting the stack:
 
-      # Recommended for production traceability (compose defaults to local)
+- Set `CADDY_HOST` for your domain.
+- Generate `HTML2RSS_SECRET_KEY` with `openssl rand -hex 32`.
+- Set a strong `HEALTH_CHECK_TOKEN` when you use authenticated `GET /api/v1/health`; liveness/readiness probes can use `/api/v1/health/live` and `/api/v1/health/ready` without it.
+- Leave `BUILD_TAG` and `GIT_SHA` unset unless you intentionally override image metadata in logs.
+- 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.
 
-      GIT_SHA=
+After `docker compose up -d`, run `docker compose logs caddy --tail 20`; look for `certificate obtained`.
 
-  `}
-  lang="dotenv"
-  />
-
-- 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`.
-  - Set a strong `HEALTH_CHECK_TOKEN` when you use authenticated `GET /api/v1/health`; liveness/readiness probes can use `/api/v1/health/live` and `/api/v1/health/ready` without it.
-  - 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.
+Re-test after DNS changes with [SSL Labs](https://www.ssllabs.com/ssltest/).
 
 ## Secure Your Instance
 
@@ -107,22 +88,22 @@ Keep the instance healthy once it is in production:
 
 - Monitor `https://yourdomain.com/api/v1/health` with the configured bearer token for authenticated health checks
 - Review `docker compose logs` regularly for feed errors or certificate renewals
-- Enable automatic image updates so security patches roll out quickly
+- Enable automatic image updates for the Docker tag you selected
 - Right-size CPU and memory to avoid starvation when parsing large feeds
 
 ### Auto-update with Watchtower
 
 <DockerComposeSnippet variant="watchtower" />
 
-This Watchtower shape scopes updates to `html2rss-web`, `browserless`, and `caddy`; replace service names if your stack differs.
+This Watchtower shape scopes updates to `html2rss-web`, `browserless`, and `caddy`; change the service names if your stack differs.
 
 Check `docker compose logs watchtower` occasionally to confirm updates are applied.
 
 ### Resource Guardrails
 
 <DockerComposeSnippet variant="resourceGuardrails" />
 
-Adjust the limits to match your host capacity. Increase memory if you process many large feeds.
+Adjust limits to match host capacity. Increase memory for large feeds.
 
 ## Share & Support
 
diff --git a/src/content/docs/web-application/reference/env-variables.mdx b/src/content/docs/web-application/reference/env-variables.mdx
@@ -9,8 +9,8 @@ description: "Configuration reference for html2rss-web environment variables."
 | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `HTML2RSS_SECRET_KEY`             | required in production; development/test gets a temporary default                                                                                                                                         |
 | `HEALTH_CHECK_TOKEN`              | bearer token for authenticated `GET /api/v1/health`; optional unless you use that endpoint (the documented Compose stack includes it); `/api/v1/health/live` and `/api/v1/health/ready` do not require 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                                                                                                                |
+| `BUILD_TAG`                       | release metadata used in logs; published Docker images set this to the release version                                                                                                                    |
+| `GIT_SHA`                         | deployed commit metadata used in logs; published Docker images set this to the released commit                                                                                                            |
 | `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                                                                                 |
diff --git a/src/content/docs/web-application/reference/versioning-and-releases.mdx b/src/content/docs/web-application/reference/versioning-and-releases.mdx
@@ -5,11 +5,19 @@ description: Learn about versioning and release strategy for html2rss-web
 
 import { dockerHubRepository, dockerHubUrl } from "../../../../data/docker";
 
-This web application is distributed in a [rolling release](https://en.wikipedia.org/wiki/Rolling_release) fashion from the `main` branch.
+html2rss-web publishes versioned Docker images to <a href={dockerHubUrl}>Docker Hub: <code>{dockerHubRepository}</code></a>.
 
-For the latest commit passing GitHub CI/CD on the main branch, an updated Docker image will be pushed to <a href={dockerHubUrl}>Docker Hub: <code>{dockerHubRepository}</code></a>.
-The [SBOM](https://en.wikipedia.org/wiki/Software_supply_chain) is embedded in the Docker image.
+For release `1.2.3`, Docker publish pushes:
 
-GitHub's @dependabot is enabled for dependency updates and they are automatically merged to the `main` branch when the CI gives the green light.
+- `html2rss/web:1.2.3`: exact release
+- `html2rss/web:1`: latest release in major version `1`
+- `html2rss/web:latest`: newest published release
+- `html2rss/web:<git-sha>`: release image pinned by source commit
 
-If you use Docker, you should update to the latest image automatically by [setting up _watchtower_ as described](/web-application/how-to/automatic-updates).
+Use `html2rss/web:1` for normal deployments. It receives newer releases for major version `1` without moving across a future major release.
+
+Use an exact version tag when you need fully pinned deploys. Use `latest` only when you intentionally want the newest published release. Use the commit SHA tag when you need to trace or reproduce one released build.
+
+Release images include SBOM and provenance metadata. The image build also sets `BUILD_TAG` to the release version and `GIT_SHA` to the released commit.
+
+If you use Docker Compose, [set up Watchtower](/web-application/how-to/automatic-updates) to pull updates for the tag you selected.
diff --git a/src/data/docker.ts b/src/data/docker.ts
@@ -1,6 +1,6 @@
 export const dockerHubRepository = 'html2rss/web';
 export const dockerHubUrl = `https://hub.docker.com/r/${dockerHubRepository}`;
-export const webImage = `${dockerHubRepository}:latest`;
+export const webImage = `${dockerHubRepository}:1`;
 export const browserlessImage = 'ghcr.io/browserless/chromium';
 export const caddyImage = 'caddy:2-alpine';
 export const watchtowerImage = 'containrrr/watchtower';
