Skip to content

feat: refocus self-hosting guide on production deployment #995

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Nov 8, 2025
Merged

feat: refocus self-hosting guide on production deployment #995

Changes from 2 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
d8f09c9
Refocus self-hosting guide on production deployment
gildesmarais Nov 8, 2025
6dd6500
Clarify compose file creation in self-hosting guide
gildesmarais Nov 8, 2025
eeae053
Clarify self-hosting prerequisites
gildesmarais Nov 8, 2025
e4580a0
Polish self-hosting guide tone
gildesmarais Nov 8, 2025
b2cfca0
Polish self-hosting copy
gildesmarais Nov 8, 2025
2b28e5a
Update src/content/docs/get-involved/self-hosting.mdx
gildesmarais Nov 8, 2025
bb36cb9
Update src/content/docs/get-involved/self-hosting.mdx
gildesmarais Nov 8, 2025
ebc8b4c
Update src/content/docs/get-involved/self-hosting.mdx
gildesmarais Nov 8, 2025
20e3a37
Update src/content/docs/get-involved/self-hosting.mdx
gildesmarais Nov 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 33 additions & 26 deletions src/content/docs/get-involved/self-hosting.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,33 +7,40 @@ sidebar:

Turn any website into an RSS feed. Self-host your own instance and take back control of your information diet.

## Quick Start

1. Install [Docker](https://docs.docker.com/get-docker/).
2. Create a directory for html2rss:
```bash
mkdir html2rss-web && cd html2rss-web
```
3. Download the configuration:
```bash
curl -O https://raw.githubusercontent.com/html2rss/html2rss-web/master/docker-compose.yml
curl -O https://raw.githubusercontent.com/html2rss/html2rss-web/master/config/feeds.yml
```
4. Start the instance:
```bash
docker compose up -d
```
5. Visit [http://localhost:3000](http://localhost:3000)
You should see the html2rss-web interface.

## Next Steps

- [Secure your instance](/web-application/how-to/deployment#secure-your-instance)
- [Enable HTTPS](/web-application/how-to/deployment#option-a-caddy-automatic-https)
- [Troubleshoot issues](/troubleshooting/troubleshooting)
- [Join the community](https://github.com/orgs/html2rss/discussions)
## Before You Begin

---
This guide assumes you already manage a Docker-capable host (VPS, home lab, or Kubernetes node) and are comfortable deploying containers. If you have not yet provisioned a server, complete that prerequisite before proceeding. Review the full [Deployment & Production guide](/web-application/how-to/deployment) for environment sizing, proxy patterns, and step-by-step production hardening.
Copy link

Copilot AI Nov 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "Before You Begin" section assumes users already have a Docker-capable host and are comfortable deploying containers, which may not align with the "get-involved" context. According to the coding guidelines, content should be written clearly for users who are not fully fluent in technology. This section creates a barrier to entry that contradicts the AIDA model principle of engaging readers.

Consider softening the prerequisites to be more inclusive, such as: "This guide is designed for users who want to run their own production instance. You'll need basic familiarity with Docker and access to a server (VPS, home lab, or cloud instance). If you're new to self-hosting, start with the Getting Started guide for a simpler local setup first."

Copilot generated this review using guidance from repository custom instructions.

At a minimum, ensure:

- Docker Engine and Docker Compose Plugin are installed on the host.
- Ports 80/443 (or the ports used by your TLS terminator) are open to the Internet if you plan to serve other users.
- You can publish DNS for your chosen domain.

## Deployment Overview

1. Generate your `docker-compose.yml` and `config/feeds.yml` by following [Step 2 of the getting started guide](/web-application/getting-started/#step-2-create-the-configuration-file), then copy the resulting files into your deployment directory.
Copy link

Copilot AI Nov 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This instruction is overly technical and lacks user-friendly guidance. The phrase "Copy the reference... from the project repository to your deployment directory" assumes readers understand git workflows and deployment directory structures. According to the coding guidelines, content should be clear and understandable for users who are not fully fluent in technology.

Consider providing more explicit instructions: "Download the reference docker-compose.yml and config/feeds.yml files to a directory on your server where you'll run html2rss-web."

Copilot generated this review using guidance from repository custom instructions.
2. Create an `.env` file with production credentials and the values documented in the [environment reference](/web-application/reference/env-variables). Generate new secrets (`openssl rand -hex 32`) and avoid reusing the samples from local testing.
Copy link

Copilot AI Nov 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The phrase "avoid reusing the samples from local testing" is negative framing and lacks clarity. According to the coding guidelines, content should use active voice and be clear and concise.

Consider positive, actionable language: "Generate new secrets (openssl rand -hex 32) specifically for production—never use example values from documentation or local testing."

Copilot generated this review using guidance from repository custom instructions.
3. Adjust the compose file to match your host (volumes, proxy service, watchtower, resource limits). The [deployment guide](/web-application/how-to/deployment) shows complete examples for Caddy, health-check protection, and automatic updates.
4. Start the stack with `docker compose up -d` and verify the application is reachable at your chosen domain or internal endpoint.
Comment on lines 25 to 30
Copy link

Copilot AI Nov 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading "Deployment Overview" contradicts the page structure and AIDA principles. This page is titled "Self-Host Your Own Instance" in the "Get Involved" section, yet it immediately jumps to deployment specifics without engaging the reader or explaining the value proposition.

According to the coding guidelines, you should follow the AIDA model (Attention, Interest, Desire, Action) to ensure content is engaging. The original "Quick Start" section followed this pattern better by providing immediate action steps.

Consider restructuring to include:

  1. A compelling introduction explaining why self-hosting matters
  2. Clear pathways for different user levels (beginner local setup vs. production deployment)
  3. Action-oriented steps that build confidence rather than listing prerequisites

Copilot generated this review using guidance from repository custom instructions.

Need extra reliability? Integrate the instance with your existing reverse proxy, DNS, or platform tooling rather than running it ad hoc on a laptop. Treat it like any other production service.
Copy link

Copilot AI Nov 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The phrase "running it ad hoc on a laptop" uses jargon ("ad hoc") that may not be clear to all readers. According to the coding guidelines, content should be written clearly for users who are not fully fluent in technology.

Consider simplifying to: "Need extra reliability? Integrate the instance with your existing reverse proxy, DNS, or platform tooling rather than running it temporarily on a laptop. Treat it like any other production service."

Copilot generated this review using guidance from repository custom instructions.
Copy link

Copilot AI Nov 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new content substantially increases technical complexity and adds barriers that conflict with the "get-involved" context. According to the coding guidelines, you should prevent adding "technical clutter" content and ensure the site navigation is assembled in a logical and user-friendly manner.

The original "Quick Start" section provided an accessible onboarding experience for community members wanting to self-host. The new version immediately requires VPS/home lab knowledge, Docker Compose Plugin understanding, and production-grade security concerns. This transformation makes the page less suitable for the "Get Involved" section, which should lower barriers to participation.

Consider either:

  1. Restoring the simple Quick Start for getting involved, and moving production-focused content to /web-application/how-to/production-deployment, or
  2. Adding a beginner-friendly "Try It First" section before diving into production prerequisites, directing users to the Getting Started guide for a simpler local installation.

Copilot generated this review using guidance from repository custom instructions.

## Harden & Secure

- Follow the [Secure Your Instance](/web-application/how-to/deployment#secure-your-instance) checklist to lock down credentials, TLS, and network access.
- Enforce HTTPS by configuring a reverse proxy (see [Option A: Caddy](/web-application/how-to/deployment#option-a-caddy-automatic-https)) or your preferred terminator. If you manage certificates separately, document the renewal procedure alongside your deployment scripts.
- Review the [security best practices](/web-application/how-to/deployment#prepare-for-production) and keep secrets outside of version control.

## Monitor & Maintain

- Point your uptime monitor at `/health_check.txt` and review container logs regularly. The [Operate & Monitor](/web-application/how-to/deployment#operate-monitor) section outlines suggested thresholds.
- Automate updates with Watchtower or your orchestration tooling to receive the latest html2rss-web releases quickly.
- Track storage usage for feed cache volumes and prune unused images. Schedule periodic configuration reviews so feeds and credentials remain accurate.

## Share Your Instance

Running a reliable deployment benefits the broader community. Add your server to the [community instance list](https://github.com/html2rss/html2rss-web/wiki/Instances) once it is stable and you are ready for other readers. Include details such as uptime expectations, moderation policy, and contact information so people know what to expect.

## License

Expand Down