Skip to content

deployment.mdx

Latest commit

 

History

History
112 lines (75 loc) · 5.04 KB

deployment.mdx

File metadata and controls

112 lines (75 loc) · 5.04 KB
Raw
title Deployment & Production
description Deploy html2rss-web with Docker, keep first success small, then add production pieces after the local token-gated flow works.
sidebar
order
3

import { Code } from "@astrojs/starlight/components";

import DockerComposeSnippet from "../../../components/docs/DockerComposeSnippet.astro";

html2rss-web ships on Docker Hub. Start with the Getting Started guide, which uses docker-compose.quickstart.yml. Make sure the one-file demo works first, then add the production pieces below.

The examples use html2rss/web:1, the recommended major-version tag. Pin an exact release if your deployment process requires it.

Choose Your Production Scope First

There are two materially different deployment modes:

  • Automatic generation enabled: primary self-hosted workflow, requires AUTO_SOURCE_ENABLED=true and HTML2RSS_ACCESS_TOKEN
  • Feed Directory only: lower-maintenance path when the Feed Directory already covers your needs

If you do not need page-URL generation yet, keep AUTO_SOURCE_ENABLED off and ship the fallback mode only.

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
  • You have a value ready for HTML2RSS_SECRET_KEY
  • You have a value ready for HTML2RSS_ACCESS_TOKEN

If you plan to enable automatic feed generation, also prepare:

  • a clear way to give users the same HTML2RSS_ACCESS_TOKEN your instance expects
  • optional advanced-rendering infrastructure only if harder sites later prove they need it

Why a Reverse Proxy?

A reverse proxy terminates public HTTPS traffic and forwards requests to html2rss-web on your private Docker network.

Option A: Caddy (Automatic HTTPS)

Caddy handles certificates and redirects.

Create a .env file beside your compose file:

<Code code={` CADDY_HOST=yourdomain.com HTML2RSS_SECRET_KEY=<openssl rand -hex 32> HTML2RSS_ACCESS_TOKEN=

Optional only if you want authenticated GET /api/v1/health

HEALTH_CHECK_TOKEN=

`} lang="dotenv" />

Before starting the stack:

  • Set CADDY_HOST for your domain.
  • Generate HTML2RSS_SECRET_KEY with openssl rand -hex 32.
  • Set a strong HTML2RSS_ACCESS_TOKEN. This is the token users paste into the web UI.
  • Leave HEALTH_CHECK_TOKEN unset unless you intentionally use authenticated GET /api/v1/health.
  • Leave BUILD_TAG and GIT_SHA unset unless you intentionally override image metadata in logs.
  • Adjust optional knobs such as AUTO_SOURCE_ENABLED and SENTRY_DSN as needed; 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.

Secure Your Instance

Harden the application before inviting other users:

  • Set a strong HTML2RSS_ACCESS_TOKEN and rotate it when needed
  • Prefer environment files (.env) stored outside version control for secrets
  • Keep token sharing/distribution outside public docs and outside version control
  • Give trusted users the same current HTML2RSS_ACCESS_TOKEN through your normal operator channel
  • If you use authenticated GET /api/v1/health, set a strong HEALTH_CHECK_TOKEN; do not leave CHANGE_ME_HEALTH_CHECK_TOKEN anywhere in production

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

Operate & Monitor

Keep the instance healthy once it is in production:

  • Review docker compose logs regularly for feed errors or certificate renewals
  • Pull newer images for the Docker tag you selected on your update cadence
  • Right-size CPU and memory to avoid starvation when parsing large feeds
  • Use GET /api/v1/health/ready for standard readiness checks
  • Add authenticated GET /api/v1/health only when your operator tooling needs it

Resource Guardrails

Adjust limits to match host capacity. Increase memory for large feeds.

Share & Support

  • Test different feed sources before inviting external users
  • Publish /openapi.yaml from the running instance if you expect agents or integrations to call the API directly
  • Add your instance to the community wiki if you want it listed publicly
  • Visit the troubleshooting guide or join the community discussions when you need help
  • Ready to contribute fixes or docs? See the contributing guide