Skip to content
html2rss logo - Turn any website into RSS html2rss

Getting Started

Run html2rss-web locally with Docker, open the web interface, and verify that your instance can serve a working included feed.

What You Will Have When This Works

Section titled “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 custom configs or more advanced setup

Installation Guide

Section titled “Installation Guide”

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

What You’ll Need

Section titled “What You’ll Need”
  • Docker
  • About 10 minutes

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

Step 1: Create a Folder

Section titled “Step 1: Create a Folder”

Create a new folder for html2rss-web:

Terminal window
mkdir html2rss-web
cd html2rss-web

Step 2: Create a Minimal Configuration File

Section titled “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"
    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: "ghcr.io/browserless/chromium"
    restart: unless-stopped
    ports:
      - "127.0.0.1:4002:4002"
    environment:
      PORT: 4002
      CONCURRENT: 10
      TOKEN: your-browserless-token

Add update automation later, after the first run works.

Step 3: Start html2rss-web

Section titled “Step 3: Start html2rss-web”

Run:

Terminal window
docker compose up -d

First Success Check

Section titled “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, static feed path, and reader subscription path are working together.

What To Do First

Section titled “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 core path before you invest in automatic generation or custom configs.

Next Steps

Section titled “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