feat: refocus self-hosting guide on production deployment #995
Conversation
gildesmarais
changed the title
gildesmarais
changed the title
|
Closes #994 |
There was a problem hiding this comment.
Pull Request Overview
This PR completely restructures the self-hosting documentation, replacing the beginner-friendly "Quick Start" approach with production-focused deployment guidance. The change shifts the target audience from community members exploring self-hosting to experienced administrators running production instances.
Key Changes:
- Removed the simple 5-step Quick Start installation guide
- Added production prerequisites section requiring VPS/Kubernetes experience
- Expanded security, monitoring, and maintenance sections with detailed operational guidance
- Restructured content to emphasize production hardening over quick experimentation
| ## 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. |
There was a problem hiding this comment.
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."
| 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. | ||
|
|
||
| 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. |
There was a problem hiding this comment.
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."
| ## 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. | ||
|
|
||
| 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. | ||
| 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. | ||
| 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. | ||
|
|
||
| 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. |
There was a problem hiding this comment.
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:
- Restoring the simple Quick Start for getting involved, and moving production-focused content to
/web-application/how-to/production-deployment, or - 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.
| ## 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. | ||
| 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. | ||
| 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. |
There was a problem hiding this comment.
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:
- A compelling introduction explaining why self-hosting matters
- Clear pathways for different user levels (beginner local setup vs. production deployment)
- Action-oriented steps that build confidence rather than listing prerequisites
| ## 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. | ||
| 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. |
There was a problem hiding this comment.
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."
|
|
||
| ## 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. |
There was a problem hiding this comment.
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."
| - A server you control (a VPS, home lab, or cloud instance) with Docker support. | ||
| - Comfort running a few terminal commands and editing configuration files. | ||
|
|
||
| If that feels new, start with the [Getting Started guide](/web-application/getting-started/) for a friendly local install. It introduces the same concepts at a slower pace. When you're ready to go live, come back here and review the full [Deployment & Production guide](/web-application/how-to/deployment) for sizing tips, proxy examples, and hardening advice. |
There was a problem hiding this comment.
Inconsistent URL formatting: the first link includes a trailing slash /web-application/getting-started/ while the second link omits it /web-application/how-to/deployment. For consistency and to avoid potential duplicate URL issues, either include or omit trailing slashes consistently throughout the document.
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Copilot <[email protected]>
Summary
Testing
Codex Task