docs(web): align deployment and operator guidance

Author: gildesmarais

src/components/docs/DockerComposeSnippet.astro

@@ -15,13 +15,19 @@ const snippets: Record<Props["variant"], string> = {
     restart: unless-stopped
     ports:
       - "127.0.0.1:4000:4000"
+    env_file:
+      - path: .env
+        required: false
     environment:
       RACK_ENV: production
       PORT: 4000
-      HTML2RSS_SECRET_KEY: your-generated-secret-key
-      HEALTH_CHECK_TOKEN: your-health-check-token
+      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:-}
       BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:4002
-      BROWSERLESS_IO_API_TOKEN: your-browserless-token
+      BROWSERLESS_IO_API_TOKEN: \${BROWSERLESS_IO_API_TOKEN:?set BROWSERLESS_IO_API_TOKEN}
 
   browserless:
     image: "${browserlessImage}"
@@ -35,6 +41,7 @@ const snippets: Record<Props["variant"], string> = {
   productionCaddy: `services:
   caddy:
     image: ${caddyImage}
+    restart: unless-stopped
     ports:
       - "80:80"
       - "443:443"
@@ -46,39 +53,70 @@ const snippets: Record<Props["variant"], string> = {
       - --from
       - \${CADDY_HOST}
       - --to
-      - html2rss:3000
-  html2rss:
+      - html2rss-web:4000
+
+  html2rss-web:
     image: ${webImage}
-    env_file: .env
+    restart: unless-stopped
+    env_file:
+      - path: .env
+        required: false
+    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:-}
+      BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:4002
+      BROWSERLESS_IO_API_TOKEN: \${BROWSERLESS_IO_API_TOKEN:?set BROWSERLESS_IO_API_TOKEN}
+
+  browserless:
+    image: "${browserlessImage}"
+    restart: unless-stopped
+    environment:
+      PORT: 4002
+      CONCURRENT: 10
+      TOKEN: \${BROWSERLESS_IO_API_TOKEN:?set BROWSERLESS_IO_API_TOKEN}
 
 volumes:
   caddy_data:`,
   secure: `services:
-  html2rss:
+  html2rss-web:
     image: ${webImage}
+    restart: unless-stopped
+    env_file:
+      - path: .env
+        required: false
     environment:
       RACK_ENV: production
-      LOG_LEVEL: warn
-      HEALTH_CHECK_USERNAME: your-secure-username
-      HEALTH_CHECK_PASSWORD: your-very-secure-password
-      BASE_URL: https://yourdomain.com`,
+      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:-}
+      BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:4002
+      BROWSERLESS_IO_API_TOKEN: \${BROWSERLESS_IO_API_TOKEN:?set BROWSERLESS_IO_API_TOKEN}
+
+  browserless:
+    image: "${browserlessImage}"
+    restart: unless-stopped
+    environment:
+      PORT: 4002
+      CONCURRENT: 10
+      TOKEN: \${BROWSERLESS_IO_API_TOKEN:?set BROWSERLESS_IO_API_TOKEN}`,
   watchtower: `services:
   watchtower:
     image: ${watchtowerImage}
-    depends_on:
-      - html2rss
-      - caddy
-    command:
-      - --cleanup
-      - --interval
-      - "300"
-      - html2rss
-      - caddy
+    restart: unless-stopped
     volumes:
-      - /var/run/docker.sock:/var/run/docker.sock:ro
-    restart: unless-stopped`,
+      - /var/run/docker.sock:/var/run/docker.sock
+      - "\${HOME}/.docker/config.json:/config.json"
+    command: --cleanup --interval 7200`,
   resourceGuardrails: `services:
-  html2rss:
+  html2rss-web:
     image: ${webImage}
     deploy:
       resources:

src/content/docs/get-involved/self-hosting.mdx

@@ -1,54 +1,28 @@
 ---
 title: "Self-Host Your Own Instance"
-description: "Take control of your information diet. Host your own html2rss instance and join the decentralized web movement."
+description: "Start self-hosting with the current html2rss-web setup and deployment docs."
 sidebar:
   order: 3
 ---
 
-Turn any website into an RSS feed. Self-host your own instance to take back control of your information diet and help the html2rss ecosystem grow for everyone.
+This page is the short routing point for self-hosting. The current setup and deployment instructions live under the `html2rss-web` docs so the Docker, token, and Browserless guidance only exists in one place.
 
-## Before You Begin
+## Recommended Path
 
-This guide walks you through running a production-ready instance that friends, teams, or communities can rely on. You'll need:
+1. **[Run html2rss-web locally](/web-application/getting-started/)** to verify your own instance with an included feed first.
+2. **[Deploy html2rss-web to production](/web-application/how-to/deployment/)** when you are ready to expose or operate it.
+3. **[Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/)** only if you want the token-gated page-URL workflow.
 
-- A server you control (a VPS, home lab, or cloud instance) with Docker support.
-- Comfort running a few terminal commands and editing configuration files.
+## What To Expect
 
-If that feels new, start with the [Getting Started guide](/web-application/getting-started/) for a friendly local install. It introduces the same concepts at a slower pace. When you're ready to go live, come back here and review the full [Deployment & Production guide](/web-application/how-to/deployment) for sizing tips, proxy examples, and hardening advice.
-
-Before you deploy, double-check this quick checklist:
-
-- Docker Engine and Docker Compose Plugin are installed on the host.
-- Ports 80/443 (or the ports used by your TLS terminator) are open to the internet if you plan to serve other users.
-- You can publish DNS for your chosen domain.
-
-## Deployment Overview
-
-1. Generate your `docker-compose.yml` and `config/feeds.yml` by following [Step 2 of the Getting Started guide](/web-application/getting-started/#step-2-create-the-configuration-file), then copy the resulting files into your deployment directory.
-2. Create an `.env` file with production credentials and the values documented in the [environment reference](/web-application/reference/env-variables). Generate new secrets (`openssl rand -hex 32`) and avoid reusing the samples from local testing.
-3. Adjust the compose file to match your host (volumes, proxy service, watchtower, resource limits). The [deployment guide](/web-application/how-to/deployment) shows complete examples for Caddy, health-check protection, and automatic updates.
-4. Start the stack with `docker compose up -d` and verify the application is reachable at your chosen domain or internal endpoint.
-
-For extra reliability, integrate the instance with your existing reverse proxy, DNS, or platform tooling rather than running it ad hoc on a laptop. Treat it like any other production service so readers can trust it.
-
-## Harden & Secure
-
-- Follow the [Secure Your Instance](/web-application/how-to/deployment#secure-your-instance) checklist to lock down credentials, TLS, and network access.
-- Enforce HTTPS by configuring a reverse proxy (see [Option A: Caddy](/web-application/how-to/deployment#option-a-caddy-automatic-https)) or your preferred terminator. If you manage certificates separately, document the renewal procedure alongside your deployment scripts.
-- Review the [production preparation guidelines](/web-application/how-to/deployment#prepare-for-production) and keep secrets outside of version control.
-
-## Monitor & Maintain
-
-- Point your uptime monitor at `/health_check.txt` and review container logs regularly. The [Operate & Monitor](/web-application/how-to/deployment#operate--monitor) section outlines suggested thresholds.
-- Automate updates with Watchtower (a Docker container that updates running containers) or your container management platform to receive the latest html2rss-web releases quickly.
-- Track storage usage for feed cache volumes and prune unused images. Schedule periodic configuration reviews so feeds and credentials remain accurate.
+- `html2rss-web` is the recommended self-hosted product surface.
+- Included feeds are the lowest-maintenance way to prove a deployment.
+- Automatic feed generation is disabled by default in production.
+- The generated API contract is published as OpenAPI at `/openapi.yaml`.
+- Custom config work belongs in the core `html2rss` docs and JSON Schema.
 
 ## Share Your Instance
 
 Running a reliable deployment benefits the broader community. Share your server with the broader community by adding it to the [community instance list](https://github.com/html2rss/html2rss-web/wiki/Instances) once it is stable and you are ready for other readers. Include details such as uptime expectations, moderation policy, and contact information so people know what to expect.
 
 Thanks for investing the time to share html2rss with others. Each new instance expands the open web and helps readers stay in control of the stories they follow.
-
-## License
-
-[MIT](https://github.com/html2rss/html2rss/blob/main/LICENSE)

src/content/docs/ruby-gem/index.mdx

@@ -7,6 +7,12 @@ sidebar:
 
 This section provides comprehensive documentation for the `html2rss` Ruby gem.
 
+If you are looking for the stable machine-readable contract for config authoring, use the JSON Schema exported by the core repo:
+
+- Repository file: [`schema/html2rss-config.schema.json`](https://github.com/html2rss/html2rss/blob/master/schema/html2rss-config.schema.json)
+- CLI export: `html2rss schema`
+- Runtime validation: `html2rss validate config.yml`
+
 ## Getting Started
 
 If you are getting started with `html2rss`, we recommend starting with the [tutorials](/ruby-gem/tutorials).

src/content/docs/troubleshooting/troubleshooting.mdx

@@ -70,14 +70,15 @@ If you are getting a "command not found" error, try the following:
   ```bash
   docker compose logs
   ```
-- Ensure the port (default: 3000) isn’t already in use:
+- Ensure the app port (default compose binding: 4000) isn’t already in use:
   ```bash
-  netstat -tulpn | grep :3000
+  lsof -i :4000
   ```
+- If the app exits immediately in production, check that `HTML2RSS_SECRET_KEY`, `BUILD_TAG`, and `GIT_SHA` are set.
 
 ### Can’t Access the Web Interface
 
-- Confirm your firewall allows traffic on port 3000 (or the port you configured)
+- Confirm your firewall allows traffic on port 4000 or your reverse-proxy ports
 - Try accessing via the server’s IP instead of a domain name
 - Double-check that containers are running:
   ```bash
@@ -86,10 +87,10 @@ If you are getting a "command not found" error, try the following:
 
 ### Authentication Errors
 
-- **401 Unauthorized:** Check your `AUTO_SOURCE_USERNAME` and `AUTO_SOURCE_PASSWORD` environment variables.
-- **403 Forbidden:** The URL is not in the `AUTO_SOURCE_ALLOWED_URLS` list, or the origin is not in `AUTO_SOURCE_ALLOWED_ORIGINS`.
+- **401 Unauthorized when creating feeds:** The create-feed API expects a bearer token. Re-enter a valid access token in the UI or send `Authorization: Bearer ...` to `POST /api/v1/feeds`.
+- **403 Forbidden when creating feeds:** Automatic feed generation may be disabled (`AUTO_SOURCE_ENABLED=false`) or the requested URL may not be allowed for the authenticated account.
 - **500 Internal Server Error:** Check the application logs for detailed error information.
-- **Health check failures:** Use the `/health_check.txt` endpoint to identify which specific feed configurations are broken.
+- **Health endpoint failures:** Use `GET /api/v1/health/live`, `GET /api/v1/health/ready`, or authenticated `GET /api/v1/health` depending on which probe you are testing.
 
 ### Feed Problems
 

src/content/docs/web-application/getting-started.mdx

@@ -8,7 +8,7 @@ sidebar:
 import AutoGenerationOptional from "../../../components/docs/AutoGenerationOptional.astro";
 import MinimalDockerCompose from "../../../components/docs/MinimalDockerCompose.astro";
 
-Run `html2rss-web` locally with Docker, open the web interface, and verify that your instance can serve a working included feed.
+Run `html2rss-web` locally with Docker, open the web interface, and verify that your instance can serve a working included feed before you enable direct feed generation.
 
 ## What You Will Have When This Works
 
@@ -17,7 +17,7 @@ After this guide, you should have:
 - `html2rss-web` running at `http://localhost:4000`
 - the web interface loading correctly
 - a first included feed URL you can copy into your reader
-- a clear path to either custom configs or more advanced setup
+- a clear path to either token-gated feed generation or custom configs
 
 ## Installation Guide
 
@@ -45,7 +45,7 @@ Create a file called `docker-compose.yml` in that folder and start with the mini
 
 <MinimalDockerCompose />
 
-Add update automation later, after the first run works.
+This minimal stack intentionally proves the included-feed path first. Add automatic updates, reverse proxying, or your own config file only after this first run works.
 
 ### Step 3: Start html2rss-web
 
@@ -68,7 +68,7 @@ At this point, `html2rss-web` should be running.
 4. Confirm the feed opens
 5. Copy that feed URL into your reader
 
-If that works, the deployment, static feed path, and reader subscription path are working together.
+If that works, the deployment, included-config path, and reader subscription path are working together.
 
 ## What To Do First
 
@@ -78,7 +78,18 @@ Start with an included config from your own instance:
 2. copy that feed URL into your reader
 3. confirm your reader can subscribe successfully
 
-That proves the core path before you invest in automatic generation or custom configs.
+That proves the lowest-friction path before you invest in automatic generation or custom configs.
+
+## What Changes If You Enable Feed Generation
+
+Automatic feed generation is off by default in production. When you enable it later:
+
+- the web app creates feeds through `POST /api/v1/feeds`
+- that API requires a bearer token
+- the UI starts with `faraday` and automatically retries once with `browserless` when appropriate
+- Browserless still needs to be configured for JavaScript-heavy pages
+
+If you are integrating this flow programmatically, the generated OpenAPI is available at `/openapi.yaml`.
 
 <AutoGenerationOptional />