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

Deployment & Production

html2rss-web ships on Docker Hub, so you can launch this self-hosted service wherever Docker runs. Start with the official docker-compose.yml from the Installation Guide as your baseline.

If you have not yet created a local instance, complete the Getting Started guide first. It walks through the one-time project directory setup, creating a minimal compose file, and confirming the application locally, which gives you the right baseline before exposing a self-hosted instance publicly.

Already running html2rss-web on your workstation? Great! The sections below focus on what changes when you take that setup to production.

Prepare for Production

Section titled “Prepare for Production”

Before exposing html2rss-web, ensure:

  • Your domain (for example yourdomain.com) resolves to the host running Docker
  • Inbound TCP ports 80 and 443 reach the host (check firewalls and cloud security groups)
  • You are ready to watch the first deployment logs for certificate issuance

Why a Reverse Proxy?

Section titled “Why a Reverse Proxy?”

A reverse proxy accepts public HTTPS traffic, terminates TLS, and forwards requests to html2rss-web running on your private network.

Option A: Caddy (Automatic HTTPS)

Section titled “Option A: Caddy (Automatic HTTPS)”

Caddy handles certificates and redirects with almost no configuration.

services:
  caddy:
    image: caddy:2-alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - caddy_data:/data
    command:
      - caddy
      - reverse-proxy
      - --from
      - ${CADDY_HOST}
      - --to
      - html2rss:3000
  html2rss:
    image: html2rss/web:latest
    env_file: .env

volumes:
  caddy_data:

  • Create a .env file beside your compose file with the following variables:

    # Required for reverse proxy and application
    CADDY_HOST=yourdomain.com
    BASE_URL=https://yourdomain.com
    HTML2RSS_SECRET_KEY= # Generate with: openssl rand -hex 32
    HEALTHCHECK_USER= # Set a strong username
    HEALTHCHECK_PASS= # Set a strong password
    # Optional: see [environment reference](/web-application/reference/env-variables)

  • Update your .env before starting the stack:

    • Set CADDY_HOST and BASE_URL for your domain (for example yourdomain.com / https://yourdomain.com).
    • Generate a production secret (openssl rand -hex 32) and assign it to HTML2RSS_SECRET_KEY.
    • Replace the sample health-check credentials with strong values.
    • Adjust optional knobs (auto source, Sentry, worker counts) as needed and refer to the environment reference for details.

  • After docker compose up -d, run docker compose logs caddy --tail 20; look for certificate obtained.

  • Re-test after DNS changes with SSL Labs.

  • Want automatic updates? Add the Watchtower service shown below.

Secure Your Instance

Section titled “Secure Your Instance”

Harden the application before inviting other users:

  • Set strong credentials for health checks and any protected feeds
  • Configure BASE_URL with the final HTTPS domain before the first public run
  • Prefer environment files (.env) stored outside version control for secrets
  • Keep admin-only routes behind basic auth or IP restrictions in your proxy
services:
  html2rss:
    image: html2rss/web:latest
    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

Store these variables in a .env file and reference it with env_file: as demonstrated in the Caddy example.

Operate & Monitor

Section titled “Operate & Monitor”

Keep the instance healthy once it is in production:

  • Monitor https://yourdomain.com/health_check.txt from your uptime tool
  • Review docker compose logs regularly for feed errors or certificate renewals
  • Enable automatic image updates so security patches roll out quickly
  • Right-size CPU and memory to avoid starvation when parsing large feeds

Auto-update with Watchtower

Section titled “Auto-update with Watchtower”
services:
  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

Check docker compose logs watchtower occasionally to confirm updates are applied.

Resource Guardrails

Section titled “Resource Guardrails”
services:
  html2rss:
    image: html2rss/web:latest
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "0.5"
        reservations:
          memory: 256M
          cpus: "0.25"

Adjust the limits to match your host capacity. Increase memory if you process many large feeds.

Share & Support

Section titled “Share & Support”