docs: resolve PR feedback on deployment and snippet correctness

gildesmarais · gildesmarais · commit 0f702916e5ef · 2026-03-28T14:45:00.000+01:00
diff --git a/examples/deployment/docker-compose.yml b/examples/deployment/docker-compose.yml
@@ -2,9 +2,7 @@ services:
   html2rss-web:
     image: html2rss/web:latest
     restart: unless-stopped
-    env_file:
-      - path: .env
-        required: false
+    env_file: .env
     environment:
       PORT: 4000
 
diff --git a/src/components/docs/DockerComposeSnippet.astro b/src/components/docs/DockerComposeSnippet.astro
@@ -15,9 +15,7 @@ const snippets: Record<Props["variant"], string> = {
     restart: unless-stopped
     ports:
       - "127.0.0.1:4000:4000"
-    env_file:
-      - path: .env
-        required: false
+    env_file: .env
     environment:
       RACK_ENV: production
       PORT: 4000
@@ -58,9 +56,7 @@ const snippets: Record<Props["variant"], string> = {
   html2rss-web:
     image: ${webImage}
     restart: unless-stopped
-    env_file:
-      - path: .env
-        required: false
+    env_file: .env
     environment:
       RACK_ENV: production
       PORT: 4000
@@ -86,9 +82,7 @@ volumes:
   html2rss-web:
     image: ${webImage}
     restart: unless-stopped
-    env_file:
-      - path: .env
-        required: false
+    env_file: .env
     environment:
       RACK_ENV: production
       PORT: 4000
@@ -115,7 +109,7 @@ volumes:
       - /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`,
+    command: --cleanup --interval 7200 html2rss-web browserless caddy`,
   resourceGuardrails: `services:
   html2rss-web:
     image: ${webImage}
diff --git a/src/content/docs/ruby-gem/how-to/advanced-features.mdx b/src/content/docs/ruby-gem/how-to/advanced-features.mdx
@@ -85,9 +85,15 @@ Optimize requests with appropriate headers:
 
 ### Web Application Health Checks
 
-Use the health check endpoint to monitor feed generation:
+Use the authenticated health endpoint to monitor the web application, or use liveness/readiness endpoints when you do not use an auth token:
 
-<Code code={`curl -u username:password http://localhost:4000/health_check.txt`} lang="bash" />
+<Code
+  code={`
+  curl -H "Authorization: Bearer YOUR_HEALTH_CHECK_TOKEN" \
+    http://localhost:4000/api/v1/health
+  `}
+  lang="bash"
+/>
 
 ## Article Validation
 
diff --git a/src/content/docs/ruby-gem/how-to/custom-http-requests.mdx b/src/content/docs/ruby-gem/how-to/custom-http-requests.mdx
@@ -204,7 +204,8 @@ Test your configuration to ensure headers work correctly:
 
 <Code
   code={`
-  curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/posts && \
+  curl -H "Authorization: Bearer YOUR_TOKEN" \
+    https://api.example.com/posts && \
   html2rss feed your-config.yml
 `}
   lang="bash"
diff --git a/src/content/docs/ruby-gem/how-to/scraping-json.mdx b/src/content/docs/ruby-gem/how-to/scraping-json.mdx
@@ -29,7 +29,7 @@ is converted to this XML structure:
 
 <Code
   code={`
-    <object>
+  <object>
     <data>
       <array>
         <object>
@@ -38,7 +38,7 @@ is converted to this XML structure:
         </object>
       </array>
     </data>
-      </object>
+  </object>
 `}
   lang="xml"
 />
@@ -55,12 +55,12 @@ is converted to this XML structure:
 
 <Code
   code={`
-    <array>
+  <array>
     <object>
       <title>Headline</title>
       <url>https://example.com</url>
     </object>
-      </array>
+  </array>
 `}
   lang="xml"
 />
@@ -73,7 +73,7 @@ You would use `array > object` as your `items` selector.
 
 <Code
   code={`
-    Html2rss.feed(
+  Html2rss.feed(
     headers: {
       Accept: 'application/json'
     },
@@ -85,7 +85,7 @@ You would use `array > object` as your `items` selector.
       title: { selector: 'title' },
       url: { selector: 'url' }
     }
-      )
+  )
 `}
   lang="ruby"
 />
@@ -94,17 +94,17 @@ You would use `array > object` as your `items` selector.
 
 <Code
   code={`
-    headers:
+  headers:
     Accept: application/json
-      channel:
+  channel:
     url: "https://domainname.tld/whatever.json"
-      selectors:
+  selectors:
     items:
       selector: "array > object"
     title:
-      selector: ".title"
+      selector: "title"
     url:
       selector: "url"
-    `}
+  `}
   lang="yml"
 />
diff --git a/src/content/docs/ruby-gem/reference/cli-reference.mdx b/src/content/docs/ruby-gem/reference/cli-reference.mdx
@@ -69,12 +69,24 @@ Known anti-bot interstitial responses (for example Cloudflare challenge pages) a
 
 <Code
   code={`
-  docker run --rm -p 3000:3000 -e "CONCURRENT=10" -e "TOKEN=6R0W53R135510" ghcr.io/browserless/chromium && \
-  BROWSERLESS_IO_WEBSOCKET_URL="ws://127.0.0.1:3000" \
-  BROWSERLESS_IO_API_TOKEN="6R0W53R135510" \
-  html2rss auto https://example.com/updates --strategy browserless
+  # 1) Start Browserless in the background
+  docker run -d --rm --name html2rss-browserless \
+    -p 3000:3000 \
+    -e "CONCURRENT=10" \
+    -e "TOKEN=6R0W53R135510" \
+    ghcr.io/browserless/chromium
+
+# 2) Run html2rss against Browserless
+
+BROWSERLESS_IO_WEBSOCKET_URL="ws://127.0.0.1:3000" \
+ BROWSERLESS_IO_API_TOKEN="6R0W53R135510" \
+ html2rss auto https://example.com/updates --strategy browserless
+
+# 3) Stop Browserless when done
+
+docker stop html2rss-browserless
 `}
-  lang="bash"
+lang="bash"
 />
 
 If you see `Browserless connection failed`, check:
diff --git a/src/content/docs/web-application/how-to/deployment.mdx b/src/content/docs/web-application/how-to/deployment.mdx
@@ -30,7 +30,7 @@ Before exposing html2rss-web, ensure:
 - 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 a value ready for `HTML2RSS_SECRET_KEY`
-- You have a value ready for `HEALTH_CHECK_TOKEN` (required by the documented Compose stack)
+- You have a value ready for `HEALTH_CHECK_TOKEN` if you plan to monitor authenticated `GET /api/v1/health` (the documented Compose stack uses it; `/api/v1/health/live` and `/api/v1/health/ready` do not require it)
 
 If you plan to enable automatic feed generation, also prepare:
 
@@ -82,7 +82,7 @@ Caddy handles certificates and redirects with almost no configuration.
 - 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` (required by the documented Compose stack).
+  - 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`.
@@ -94,6 +94,7 @@ Caddy handles certificates and redirects with almost no configuration.
 Harden the application before inviting other users:
 
 - Set a strong `HEALTH_CHECK_TOKEN` for authenticated `GET /api/v1/health`, and strong credentials for any protected feeds
+- Set a strong `HEALTH_CHECK_TOKEN` for authenticated `GET /api/v1/health`, and separate strong bearer tokens 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
 
@@ -114,7 +115,7 @@ 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`).
+This Watchtower shape scopes updates to `html2rss-web`, `browserless`, and `caddy`; replace service names if your stack differs.
 
 Check `docker compose logs watchtower` occasionally to confirm updates are applied.
 
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 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`                                                                                                                                                   |
+| 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`; 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                                                                                                                |
+| `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/main/docs/README.md).
