Getting Started

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

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 token-gated feed generation or custom configs

Installation Guide

This guide walks you through a local Docker setup that gives you the most reliable starting point.

What You’ll Need

• Docker
• About 10 minutes

If you do not already have Docker, install it first.

Step 1: Create a Folder

Create a new folder for html2rss-web:

mkdir html2rss-web && cd html2rss-web

Step 2: Create a Minimal Configuration File

Create a file called docker-compose.yml in that folder and start with the minimal local stack:

services:
  html2rss-web:
    image: html2rss/web:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:4000:4000"
    env_file:
      - path: .env
        required: false
    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:-}
      BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:4002
      BROWSERLESS_IO_API_TOKEN: ${BROWSERLESS_IO_API_TOKEN:?set BROWSERLESS_IO_API_TOKEN}

  browserless:
    image: "ghcr.io/browserless/chromium"
    restart: unless-stopped
    ports:
      - "127.0.0.1:4002:4002"
    environment:
      PORT: 4002
      CONCURRENT: 10
      TOKEN: ${BROWSERLESS_IO_API_TOKEN:?set BROWSERLESS_IO_API_TOKEN}

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

Create a .env file in the same folder (minimum required values for this stack):

cat > .env <<EOF
HTML2RSS_SECRET_KEY=$(openssl rand -hex 32)
HEALTH_CHECK_TOKEN=$(openssl rand -hex 24)
BROWSERLESS_IO_API_TOKEN=trial-browserless-token
EOF

Then run:

docker compose up -d

First Success Check

At this point, html2rss-web should be running.

1. Open http://localhost:4000
2. Confirm the web interface loads
3. Open one of the included feed URLs from your own instance:
   • http://localhost:4000/microsoft.com/azure-products.rss
   • http://localhost:4000/phys.org/weekly.rss
   • http://localhost:4000/softwareleadweekly.com/issues.rss
4. Confirm the feed opens
5. Copy that feed URL into your reader

If that works, the deployment, included-config path, and reader subscription path are working together.

What To Do First

Start with an included config from your own instance:

1. open a known included feed URL
2. copy that feed URL into your reader
3. confirm your reader can subscribe successfully

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.

Automatic generation may be disabled

The direct `Create a feed` workflow is not enabled on every deployment. If you want that path, continue with Use automatic feed generation.

Next Steps

1. Use the included configs: understand how built-in feed paths work
2. Use automatic feed generation: enable direct feed creation from page URLs when you want that workflow
3. Create Custom Feeds: write your own configs when you need reviewable extraction rules
4. Need help?: troubleshoot startup and extraction problems