html2rss · gildesmarais · Mar 21, 2026 · Mar 21, 2026
diff --git a/examples/deployment/docker-compose.yml b/examples/deployment/docker-compose.yml
@@ -0,0 +1,39 @@
+services:
+  html2rss:
+    image: html2rss/web:latest
+    env_file: .env
+
+  caddy:
+    image: caddy:2-alpine
+    depends_on:
+      - html2rss
+    command:
+      - caddy
+      - reverse-proxy
+      - --from
+      - ${CADDY_HOST}
+      - --to
+      - html2rss:3000
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - caddy_data:/data
+
+  watchtower:
+    image: containrrr/watchtower
+    depends_on:
+      - html2rss
+      - caddy
+    command:
+      - --cleanup
+      - --interval
+      - "300"
+      - html2rss
+      - caddy
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    restart: unless-stopped
+
+volumes:
+  caddy_data:
diff --git a/src/components/docs/AutoGenerationOptional.astro b/src/components/docs/AutoGenerationOptional.astro
@@ -2,7 +2,7 @@
 import { Aside } from "@astrojs/starlight/components";
 ---
 
-<Aside type="note" title="Automatic generation is optional">
-  The "paste a website URL and generate a feed" workflow is not enabled by default. If you want it, continue
-  with <a href="/web-application/how-to/use-automatic-feed-generation/">Use automatic feed generation</a>.
+<Aside type="note" title="Automatic generation may be disabled">
+  The direct `Create a feed` workflow is not enabled on every deployment. If you want that path, continue with
+  <a href="/web-application/how-to/use-automatic-feed-generation/">Use automatic feed generation</a>.
 </Aside>
diff --git a/src/components/docs/DockerComposeSnippet.astro b/src/components/docs/DockerComposeSnippet.astro
@@ -0,0 +1,96 @@
+---
+import Code from "astro/components/Code.astro";
+import { browserlessImage, caddyImage, watchtowerImage, webImage } from "../../data/docker";
+
+interface Props {
+  variant: "minimal" | "productionCaddy" | "secure" | "watchtower" | "resourceGuardrails";
+}
+
+const { variant } = Astro.props;
+
+const snippets: Record<Props["variant"], string> = {
+  minimal: `services:
+  html2rss-web:
+    image: ${webImage}
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:4000:4000"
+    environment:
+      RACK_ENV: production
+      PORT: 4000
+      HTML2RSS_SECRET_KEY: your-generated-secret-key
+      HEALTH_CHECK_TOKEN: your-health-check-token
+      BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:4002
+      BROWSERLESS_IO_API_TOKEN: your-browserless-token
+
+  browserless:
+    image: "${browserlessImage}"
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:4002:4002"
+    environment:
+      PORT: 4002
+      CONCURRENT: 10
+      TOKEN: your-browserless-token`,
+  productionCaddy: `services:
+  caddy:
+    image: ${caddyImage}
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - caddy_data:/data
+    command:
+      - caddy
+      - reverse-proxy
+      - --from
+      - \${CADDY_HOST}
+      - --to
+      - html2rss:3000
+  html2rss:
+    image: ${webImage}
+    env_file: .env
+
+volumes:
+  caddy_data:`,
+  secure: `services:
+  html2rss:
+    image: ${webImage}
+    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`,
+  watchtower: `services:
+  watchtower:
+    image: ${watchtowerImage}
+    depends_on:
+      - html2rss
+      - caddy
+    command:
+      - --cleanup
+      - --interval
+      - "300"
+      - html2rss
+      - caddy
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    restart: unless-stopped`,
+  resourceGuardrails: `services:
+  html2rss:
+    image: ${webImage}
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+          cpus: "0.5"
+        reservations:
+          memory: 256M
+          cpus: "0.25"`,
+};
+
+const code = snippets[variant];
+---
+
+<Code code={code} lang="yaml" />
diff --git a/src/components/docs/MinimalDockerCompose.astro b/src/components/docs/MinimalDockerCompose.astro
@@ -1,33 +1,5 @@
 ---
-import Code from "astro/components/Code.astro";
-
-const code = `services:
-  html2rss-web:
-    image: gilcreator/html2rss-web
-    restart: unless-stopped
-    ports:
-      - "127.0.0.1:3000:3000"
-    volumes:
-      - type: bind
-        source: ./feeds.yml
-        target: /app/config/feeds.yml
-        read_only: true
-    environment:
-      RACK_ENV: production
-      HEALTH_CHECK_USERNAME: health
-      HEALTH_CHECK_PASSWORD: CHANGE_THIS_PASSWORD_BEFORE_USE
-      BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:3001
-      BROWSERLESS_IO_API_TOKEN: 6R0W53R135510
-
-  browserless:
-    image: "ghcr.io/browserless/chromium"
-    restart: unless-stopped
-    ports:
-      - "127.0.0.1:3001:3001"
-    environment:
-      PORT: 3001
-      CONCURRENT: 10
-      TOKEN: 6R0W53R135510`;
+import DockerComposeSnippet from "./DockerComposeSnippet.astro";
 ---
 
-<Code code={code} lang="yaml" />
+<DockerComposeSnippet variant="minimal" />
diff --git a/src/content/docs/getting-started.mdx b/src/content/docs/getting-started.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Getting Started"
-description: "Learn how to get RSS feeds from any website. Start with existing feeds or create your own in minutes."
+description: "Start html2rss-web locally, verify a working included feed from your self-hosted instance, and decide when to enable automatic generation or move to custom configs."
 sidebar:
   order: 1
 ---
@@ -16,15 +16,17 @@ If you want the recommended path, go to [Run html2rss-web with Docker](/web-appl
 That guide is the canonical setup flow for:
 
 - running `html2rss-web` locally
-- confirming your first successful feed
-- deciding when to use included feeds, automatic generation, or custom configs
+- confirming the interface is working
+- opening a first included feed URL
+- deciding when to use automatic generation or custom configs
 
 ## Quick Shortcuts
 
-- **[Run html2rss-web with Docker](/web-application/getting-started)** - Recommended first step
-- **[Browse working feed examples](/feed-directory/)** - See what success looks like
-- **[Create Custom Feeds](/creating-custom-feeds)** - Write configs when you need more control
-- **[Troubleshooting Guide](/troubleshooting/troubleshooting)** - Fix startup or extraction problems
+- **[Run html2rss-web with Docker](/web-application/getting-started)**: recommended first step
+- **[Browse working feed examples](/feed-directory/)**: see what successful outputs look like
+- **[Use automatic feed generation](/web-application/how-to/use-automatic-feed-generation/)**: enable direct feed creation from a page URL when you want that workflow
+- **[Create Custom Feeds](/creating-custom-feeds)**: write configs when you need more control
+- **[Troubleshooting Guide](/troubleshooting/troubleshooting)**: fix startup or extraction problems
 
 ## Using the Ruby CLI
 

diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx
@@ -1,101 +1,69 @@
 ---
-title: "Turn Any Website Into an RSS Feed - Never Miss Updates Again"
-description: "Create RSS feeds from any website - no coding required. Turn blogs, news sites, and forums into RSS feeds you can follow in your favorite reader. Free, open source, and easy to use."
+title: "Turn Any Website Into an RSS Feed"
+description: "Run html2rss-web with Docker, verify a working included feed from your self-hosted instance, then consciously enable automatic generation or move to custom configs when you need more control."
 ---
 
-Run `html2rss-web` with Docker, start with included feeds, and add custom configs only when you need more control.
+Run `html2rss-web` with Docker, verify a working included feed from your self-hosted instance, and only then decide whether to enable automatic generation or move to custom configs.
 
-## 🚀 Get Started in 30 Seconds
+## Start Here
 
-**Start here:** [Run html2rss-web with Docker](/web-application/getting-started) | [Browse working feed examples](/feed-directory/)
+**Recommended path:** [Run html2rss-web with Docker](/web-application/getting-started)
 
-Need more control? [Write a custom feed config](/creating-custom-feeds)
+That guide is the canonical onboarding flow for:
 
----
+- starting a local instance
+- verifying the web interface
+- opening a first included feed URL
+- deciding when to consciously enable automatic generation or move to custom configs
 
 ## How It Works
 
 1. **Run your own local instance** with Docker
-2. **Use included feeds or add your own** website targets
-3. **Subscribe from your RSS reader** using stable feed URLs
-
----
-
-## Why RSS Still Matters Today
-
-**Real examples of what you can do:**
-
-- Follow your favorite blogs without social media algorithms
-- Get notified when your local news site posts about your neighborhood
-- Track job postings from multiple company websites
-- Monitor product updates from software vendors
-- Follow academic papers from your field
-
-**RSS vs Social Media:**
-
-- ✅ **No algorithms** deciding what you see
-- ✅ **No ads** or sponsored content
-- ✅ **Works with any feed reader** you choose
-- ✅ **Your data stays private**
-- ✅ **Never miss updates** - automatic notifications
-- ✅ **Save time** - no more manual checking
-
----
+2. **Open a built-in feed URL** from your own instance
+3. **Copy the feed URL into your reader**
 
 ## What is html2rss?
 
-html2rss is a toolkit for turning websites into RSS feeds. Think of it as a translator that converts website content into a format your feed reader can understand.
+html2rss is a toolkit for turning websites into feeds.
 
-**Most people should start with the web application:**
+Most people should start with the web application:
 
-- **🌐 html2rss-web** - The easiest way to run your own feed server with Docker
-- **⚙️ html2rss gem** - The underlying engine, CLI, and developer interface
+- **`html2rss-web`**: the self-hosted web interface and feed server
+- **`html2rss` gem**: the Ruby engine, CLI, and lower-level config workflow
 
----
-
-## 🎯 Choose Your Path
+## Choose Your Path
 
 ### I want a working instance first
 
-1. **[Run html2rss-web with Docker](/web-application/getting-started)** - Recommended starting path
-2. **[Browse working feed examples](/feed-directory/)** - See what success looks like
-3. **[Use the included configs](/web-application/how-to/use-included-configs/)** - Start with ready-made feeds
+1. **[Run html2rss-web with Docker](/web-application/getting-started)**: recommended starting path
+2. **[Use the included configs](/web-application/how-to/use-included-configs/)**: use real embedded feeds from your own instance
+3. **[Browse working feed examples](/feed-directory/)**: see what working outputs look like
 
 ### I need more control
 
-1. **[Creating Custom Feeds](/creating-custom-feeds)** - Write and test your own configs
-2. **[Selectors Reference](/ruby-gem/reference/selectors/)** - Learn the matching rules
-3. **[Strategy Reference](/ruby-gem/reference/strategy/)** - Use `browserless` for JS-heavy sites
+1. **[Creating Custom Feeds](/creating-custom-feeds)**: write and test your own configs
+2. **[Selectors Reference](/ruby-gem/reference/selectors/)**: learn the matching rules
+3. **[Strategy Reference](/ruby-gem/reference/strategy/)**: decide when `browserless` is justified
 
 ### I'm building or integrating
 
-1. **[Ruby Gem Reference](/ruby-gem/)** - Full API documentation
-2. **[Advanced Features](/ruby-gem/how-to/advanced-features/)** - Custom HTTP requests, etc.
-3. **[Contribute to Core](/get-involved/contributing/)** - Help improve the engine
-
----
-
-## 🌟 What People Are Using html2rss For
-
-- **News & Blogs:** Follow your favorite writers without social media
-- **Job Hunting:** Track job postings from multiple company sites
-- **Product Updates:** Get notified when software you use gets updated
-- **Academic Research:** Follow new papers in your field
-- **Local News:** Stay updated on your neighborhood and city
-- **Hobby Communities:** Follow forums and communities you care about
-
-[Browse all examples in our Feed Directory →](/feed-directory/)
-
----
-
-## 🔧 Common Issues?
+1. **[Ruby Gem Reference](/ruby-gem/)**: full API documentation
+2. **[Advanced Features](/ruby-gem/how-to/advanced-features/)**: custom HTTP requests and advanced extraction
+3. **[Contribute to Core](/get-involved/contributing/)**: help improve the engine
 
-**Start with Docker, not a public instance.** That gives you the most reliable path and the newest integrated behavior.
+## What People Use It For
 
-**Feed not working?** Check our [troubleshooting guide](/troubleshooting/troubleshooting)
+- follow blogs and news sites without social media algorithms
+- track product updates and release notes
+- monitor job postings from company websites
+- subscribe to forums and communities that do not publish feeds
+- follow local news without repeated manual checking
 
-**Need custom control?** Continue to [Creating Custom Feeds](/creating-custom-feeds)
+## Practical Notes
 
-**Need help?** Join our [community discussions](https://github.com/orgs/html2rss/discussions)
+- Start with Docker, not a public instance.
+- Use an included feed to verify the deployment first.
+- Enable automatic generation only when you want the direct page-URL workflow and are ready to allow it on your self-hosted instance.
+- Move to custom configs when you need a stable, reviewable setup.
 
-**Found a bug?** [Report it on GitHub](https://github.com/html2rss/html2rss/issues)
+**Need help?** Continue to the [troubleshooting guide](/troubleshooting/troubleshooting) or join [GitHub Discussions](https://github.com/orgs/html2rss/discussions).