Skip to content

Commit 5ed81b2

Browse files
gildesmaraisgildesmarais
authored
docs: simplify self-hosted web onboarding (#1101)
1 parent bd9e5e8 commit 5ed81b2

13 files changed

Lines changed: 287 additions & 255 deletions

‎examples/deployment/docker-compose.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
services:
2+
html2rss:
3+
image: html2rss/web:latest
4+
env_file: .env
5+
6+
caddy:
7+
image: caddy:2-alpine
8+
depends_on:
9+
- html2rss
10+
command:
11+
- caddy
12+
- reverse-proxy
13+
- --from
14+
- ${CADDY_HOST}
15+
- --to
16+
- html2rss:3000
17+
ports:
18+
- "80:80"
19+
- "443:443"
20+
volumes:
21+
- caddy_data:/data
22+
23+
watchtower:
24+
image: containrrr/watchtower
25+
depends_on:
26+
- html2rss
27+
- caddy
28+
command:
29+
- --cleanup
30+
- --interval
31+
- "300"
32+
- html2rss
33+
- caddy
34+
volumes:
35+
- /var/run/docker.sock:/var/run/docker.sock:ro
36+
restart: unless-stopped
37+
38+
volumes:
39+
caddy_data:

‎src/components/docs/AutoGenerationOptional.astro‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
import { Aside } from "@astrojs/starlight/components";
33
---
44

5-
<Aside type="note" title="Automatic generation is optional">
6-
The "paste a website URL and generate a feed" workflow is not enabled by default. If you want it, continue
7-
with <a href="/web-application/how-to/use-automatic-feed-generation/">Use automatic feed generation</a>.
5+
<Aside type="note" title="Automatic generation may be disabled">
6+
The direct `Create a feed` workflow is not enabled on every deployment. If you want that path, continue with
7+
<a href="/web-application/how-to/use-automatic-feed-generation/">Use automatic feed generation</a>.
88
</Aside>

‎src/components/docs/DockerComposeSnippet.astro‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
import Code from "astro/components/Code.astro";
3+
import { browserlessImage, caddyImage, watchtowerImage, webImage } from "../../data/docker";
4+
5+
interface Props {
6+
variant: "minimal" | "productionCaddy" | "secure" | "watchtower" | "resourceGuardrails";
7+
}
8+
9+
const { variant } = Astro.props;
10+
11+
const snippets: Record<Props["variant"], string> = {
12+
minimal: `services:
13+
html2rss-web:
14+
image: ${webImage}
15+
restart: unless-stopped
16+
ports:
17+
- "127.0.0.1:4000:4000"
18+
environment:
19+
RACK_ENV: production
20+
PORT: 4000
21+
HTML2RSS_SECRET_KEY: your-generated-secret-key
22+
HEALTH_CHECK_TOKEN: your-health-check-token
23+
BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:4002
24+
BROWSERLESS_IO_API_TOKEN: your-browserless-token
25+
26+
browserless:
27+
image: "${browserlessImage}"
28+
restart: unless-stopped
29+
ports:
30+
- "127.0.0.1:4002:4002"
31+
environment:
32+
PORT: 4002
33+
CONCURRENT: 10
34+
TOKEN: your-browserless-token`,
35+
productionCaddy: `services:
36+
caddy:
37+
image: ${caddyImage}
38+
ports:
39+
- "80:80"
40+
- "443:443"
41+
volumes:
42+
- caddy_data:/data
43+
command:
44+
- caddy
45+
- reverse-proxy
46+
- --from
47+
- \${CADDY_HOST}
48+
- --to
49+
- html2rss:3000
50+
html2rss:
51+
image: ${webImage}
52+
env_file: .env
53+
54+
volumes:
55+
caddy_data:`,
56+
secure: `services:
57+
html2rss:
58+
image: ${webImage}
59+
environment:
60+
RACK_ENV: production
61+
LOG_LEVEL: warn
62+
HEALTH_CHECK_USERNAME: your-secure-username
63+
HEALTH_CHECK_PASSWORD: your-very-secure-password
64+
BASE_URL: https://yourdomain.com`,
65+
watchtower: `services:
66+
watchtower:
67+
image: ${watchtowerImage}
68+
depends_on:
69+
- html2rss
70+
- caddy
71+
command:
72+
- --cleanup
73+
- --interval
74+
- "300"
75+
- html2rss
76+
- caddy
77+
volumes:
78+
- /var/run/docker.sock:/var/run/docker.sock:ro
79+
restart: unless-stopped`,
80+
resourceGuardrails: `services:
81+
html2rss:
82+
image: ${webImage}
83+
deploy:
84+
resources:
85+
limits:
86+
memory: 512M
87+
cpus: "0.5"
88+
reservations:
89+
memory: 256M
90+
cpus: "0.25"`,
91+
};
92+
93+
const code = snippets[variant];
94+
---
95+
96+
<Code code={code} lang="yaml" />

‎src/components/docs/MinimalDockerCompose.astro‎

Lines changed: 2 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,5 @@
11
---
2-
import Code from "astro/components/Code.astro";
3-
4-
const code = `services:
5-
html2rss-web:
6-
image: gilcreator/html2rss-web
7-
restart: unless-stopped
8-
ports:
9-
- "127.0.0.1:3000:3000"
10-
volumes:
11-
- type: bind
12-
source: ./feeds.yml
13-
target: /app/config/feeds.yml
14-
read_only: true
15-
environment:
16-
RACK_ENV: production
17-
HEALTH_CHECK_USERNAME: health
18-
HEALTH_CHECK_PASSWORD: CHANGE_THIS_PASSWORD_BEFORE_USE
19-
BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:3001
20-
BROWSERLESS_IO_API_TOKEN: 6R0W53R135510
21-
22-
browserless:
23-
image: "ghcr.io/browserless/chromium"
24-
restart: unless-stopped
25-
ports:
26-
- "127.0.0.1:3001:3001"
27-
environment:
28-
PORT: 3001
29-
CONCURRENT: 10
30-
TOKEN: 6R0W53R135510`;
2+
import DockerComposeSnippet from "./DockerComposeSnippet.astro";
313
---
324

33-
<Code code={code} lang="yaml" />
5+
<DockerComposeSnippet variant="minimal" />

‎src/content/docs/getting-started.mdx‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: "Getting Started"
3-
description: "Learn how to get RSS feeds from any website. Start with existing feeds or create your own in minutes."
3+
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."
44
sidebar:
55
order: 1
66
---
@@ -16,15 +16,17 @@ If you want the recommended path, go to [Run html2rss-web with Docker](/web-appl
1616
That guide is the canonical setup flow for:
1717

1818
- running `html2rss-web` locally
19-
- confirming your first successful feed
20-
- deciding when to use included feeds, automatic generation, or custom configs
19+
- confirming the interface is working
20+
- opening a first included feed URL
21+
- deciding when to use automatic generation or custom configs
2122

2223
## Quick Shortcuts
2324

24-
- **[Run html2rss-web with Docker](/web-application/getting-started)** - Recommended first step
25-
- **[Browse working feed examples](/feed-directory/)** - See what success looks like
26-
- **[Create Custom Feeds](/creating-custom-feeds)** - Write configs when you need more control
27-
- **[Troubleshooting Guide](/troubleshooting/troubleshooting)** - Fix startup or extraction problems
25+
- **[Run html2rss-web with Docker](/web-application/getting-started)**: recommended first step
26+
- **[Browse working feed examples](/feed-directory/)**: see what successful outputs look like
27+
- **[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
28+
- **[Create Custom Feeds](/creating-custom-feeds)**: write configs when you need more control
29+
- **[Troubleshooting Guide](/troubleshooting/troubleshooting)**: fix startup or extraction problems
2830

2931
## Using the Ruby CLI
3032

‎src/content/docs/index.mdx‎

Lines changed: 38 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -1,101 +1,69 @@
11
---
2-
title: "Turn Any Website Into an RSS Feed - Never Miss Updates Again"
3-
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."
2+
title: "Turn Any Website Into an RSS Feed"
3+
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."
44
---
55

6-
Run `html2rss-web` with Docker, start with included feeds, and add custom configs only when you need more control.
6+
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.
77

8-
## 🚀 Get Started in 30 Seconds
8+
## Start Here
99

10-
**Start here:** [Run html2rss-web with Docker](/web-application/getting-started) | [Browse working feed examples](/feed-directory/)
10+
**Recommended path:** [Run html2rss-web with Docker](/web-application/getting-started)
1111

12-
Need more control? [Write a custom feed config](/creating-custom-feeds)
12+
That guide is the canonical onboarding flow for:
1313

14-
---
14+
- starting a local instance
15+
- verifying the web interface
16+
- opening a first included feed URL
17+
- deciding when to consciously enable automatic generation or move to custom configs
1518

1619
## How It Works
1720

1821
1. **Run your own local instance** with Docker
19-
2. **Use included feeds or add your own** website targets
20-
3. **Subscribe from your RSS reader** using stable feed URLs
21-
22-
---
23-
24-
## Why RSS Still Matters Today
25-
26-
**Real examples of what you can do:**
27-
28-
- Follow your favorite blogs without social media algorithms
29-
- Get notified when your local news site posts about your neighborhood
30-
- Track job postings from multiple company websites
31-
- Monitor product updates from software vendors
32-
- Follow academic papers from your field
33-
34-
**RSS vs Social Media:**
35-
36-
- ✅ **No algorithms** deciding what you see
37-
- ✅ **No ads** or sponsored content
38-
- ✅ **Works with any feed reader** you choose
39-
- ✅ **Your data stays private**
40-
- ✅ **Never miss updates** - automatic notifications
41-
- ✅ **Save time** - no more manual checking
42-
43-
---
22+
2. **Open a built-in feed URL** from your own instance
23+
3. **Copy the feed URL into your reader**
4424

4525
## What is html2rss?
4626

47-
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.
27+
html2rss is a toolkit for turning websites into feeds.
4828

49-
**Most people should start with the web application:**
29+
Most people should start with the web application:
5030

51-
- **🌐 html2rss-web** - The easiest way to run your own feed server with Docker
52-
- **⚙️ html2rss gem** - The underlying engine, CLI, and developer interface
31+
- **`html2rss-web`**: the self-hosted web interface and feed server
32+
- **`html2rss` gem**: the Ruby engine, CLI, and lower-level config workflow
5333

54-
---
55-
56-
## 🎯 Choose Your Path
34+
## Choose Your Path
5735

5836
### I want a working instance first
5937

60-
1. **[Run html2rss-web with Docker](/web-application/getting-started)** - Recommended starting path
61-
2. **[Browse working feed examples](/feed-directory/)** - See what success looks like
62-
3. **[Use the included configs](/web-application/how-to/use-included-configs/)** - Start with ready-made feeds
38+
1. **[Run html2rss-web with Docker](/web-application/getting-started)**: recommended starting path
39+
2. **[Use the included configs](/web-application/how-to/use-included-configs/)**: use real embedded feeds from your own instance
40+
3. **[Browse working feed examples](/feed-directory/)**: see what working outputs look like
6341

6442
### I need more control
6543

66-
1. **[Creating Custom Feeds](/creating-custom-feeds)** - Write and test your own configs
67-
2. **[Selectors Reference](/ruby-gem/reference/selectors/)** - Learn the matching rules
68-
3. **[Strategy Reference](/ruby-gem/reference/strategy/)** - Use `browserless` for JS-heavy sites
44+
1. **[Creating Custom Feeds](/creating-custom-feeds)**: write and test your own configs
45+
2. **[Selectors Reference](/ruby-gem/reference/selectors/)**: learn the matching rules
46+
3. **[Strategy Reference](/ruby-gem/reference/strategy/)**: decide when `browserless` is justified
6947

7048
### I'm building or integrating
7149

72-
1. **[Ruby Gem Reference](/ruby-gem/)** - Full API documentation
73-
2. **[Advanced Features](/ruby-gem/how-to/advanced-features/)** - Custom HTTP requests, etc.
74-
3. **[Contribute to Core](/get-involved/contributing/)** - Help improve the engine
75-
76-
---
77-
78-
## 🌟 What People Are Using html2rss For
79-
80-
- **News & Blogs:** Follow your favorite writers without social media
81-
- **Job Hunting:** Track job postings from multiple company sites
82-
- **Product Updates:** Get notified when software you use gets updated
83-
- **Academic Research:** Follow new papers in your field
84-
- **Local News:** Stay updated on your neighborhood and city
85-
- **Hobby Communities:** Follow forums and communities you care about
86-
87-
[Browse all examples in our Feed Directory →](/feed-directory/)
88-
89-
---
90-
91-
## 🔧 Common Issues?
50+
1. **[Ruby Gem Reference](/ruby-gem/)**: full API documentation
51+
2. **[Advanced Features](/ruby-gem/how-to/advanced-features/)**: custom HTTP requests and advanced extraction
52+
3. **[Contribute to Core](/get-involved/contributing/)**: help improve the engine
9253

93-
**Start with Docker, not a public instance.** That gives you the most reliable path and the newest integrated behavior.
54+
## What People Use It For
9455

95-
**Feed not working?** Check our [troubleshooting guide](/troubleshooting/troubleshooting)
56+
- follow blogs and news sites without social media algorithms
57+
- track product updates and release notes
58+
- monitor job postings from company websites
59+
- subscribe to forums and communities that do not publish feeds
60+
- follow local news without repeated manual checking
9661

97-
**Need custom control?** Continue to [Creating Custom Feeds](/creating-custom-feeds)
62+
## Practical Notes
9863

99-
**Need help?** Join our [community discussions](https://github.com/orgs/html2rss/discussions)
64+
- Start with Docker, not a public instance.
65+
- Use an included feed to verify the deployment first.
66+
- Enable automatic generation only when you want the direct page-URL workflow and are ready to allow it on your self-hosted instance.
67+
- Move to custom configs when you need a stable, reviewable setup.
10068

101-
**Found a bug?** [Report it on GitHub](https://github.com/html2rss/html2rss/issues)
69+
**Need help?** Continue to the [troubleshooting guide](/troubleshooting/troubleshooting) or join [GitHub Discussions](https://github.com/orgs/html2rss/discussions).

0 commit comments

Comments
 (0)