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

Getting Started

Run html2rss-web locally with Docker, confirm one generated feed works, then move to the real operator setup.

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
  • successful feed generated from your own page URL
  • a clear handoff from the demo stack to the real deployment setup
  • a generated feed URL from your own page URL
  • a clear fallback path when direct generation is not the right fit

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”
Terminal window
mkdir html2rss-web && cd html2rss-web

Step 2: Copy docker-compose.yml

Section titled “Step 2: Copy docker-compose.yml”

Use the quickstart stack from docker-compose.quickstart.yml.

Create your local docker-compose.yml from that file:

services:
  html2rss-web:
    image: html2rss/web:1
    ports:
      - "127.0.0.1:4000:4000"
    environment:
      RACK_ENV: development
      HTML2RSS_ACCESS_TOKEN: CHANGE_ME_ADMIN_TOKEN
      BOTASAURUS_SCRAPER_URL: http://botasaurus:4010


  botasaurus:
    image: html2rss/botasaurus-scrape-api:latest

This first-run stack keeps the path narrow:

  • html2rss-web
  • botasaurus
  • automatic feed generation enabled
  • RACK_ENV=development

Step 3: Start the Stack

Section titled “Step 3: Start the Stack”
Terminal window
docker compose up -d

First Success Check

Section titled “First Success Check”
  1. Open http://localhost:4000
  2. Paste your own page URL into Page URL
  3. Start with a listing, newsroom, changelog, releases, or updates page instead of a homepage
  4. Enter CHANGE_ME_ADMIN_TOKEN when prompted
  5. Open the generated feed URL

If that works, the demo stack is behaving correctly.

Move To Real Setup Next

Section titled “Move To Real Setup Next”

After the demo works, continue with the real operator setup.

  1. Deployment & Production: convert the demo into a stable, production-ready setup
  2. Use automatic feed generation: understand the page-URL flow in more detail
  3. Monitoring: choose readiness or authenticated health checks for your deployment

If The First URL Is Poor

Section titled “If The First URL Is Poor”

Automatic mode works best when the input URL is already a page that lists updates.

Higher-success inputs:

  • newsroom or press pages
  • changelog or release pages
  • category, tag, archive, or listing pages

Lower-success inputs:

  • generic homepages
  • search pages
  • entry pages

When output quality is poor, change the input URL first before assuming setup is broken.

Fallback Path

Section titled “Fallback Path”

If the site you want is already in the feed directory, or you want a fast sample before creating another generated feed, use the feed directory on your own instance.

Next Steps

Section titled “Next Steps”
  1. Deployment & Production: convert the demo into a real operator setup
  2. Create Custom Feeds: write your own config when you need reviewable extraction rules
  3. Need help?: troubleshoot startup and extraction problems