From d8f09c9ac5d92eb7f814f81dc684955ba89ad51f Mon Sep 17 00:00:00 2001 From: Gil Desmarais Date: Sat, 8 Nov 2025 10:21:41 +0100 Subject: [PATCH 1/9] Refocus self-hosting guide on production deployment --- .../docs/get-involved/self-hosting.mdx | 59 +++++++++++-------- 1 file changed, 33 insertions(+), 26 deletions(-) diff --git a/src/content/docs/get-involved/self-hosting.mdx b/src/content/docs/get-involved/self-hosting.mdx index d1298e30..8cbb1631 100644 --- a/src/content/docs/get-involved/self-hosting.mdx +++ b/src/content/docs/get-involved/self-hosting.mdx @@ -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. + +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. Copy the reference [`docker-compose.yml`](https://github.com/html2rss/html2rss-web/blob/master/docker-compose.yml) and [`config/feeds.yml`](https://github.com/html2rss/html2rss-web/blob/master/config/feeds.yml) from the project repository to 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. + +## 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 From 6dd650044c8779b6980dffc77d0cbc0d1473ff1e Mon Sep 17 00:00:00 2001 From: Gil Desmarais Date: Sat, 8 Nov 2025 10:36:13 +0100 Subject: [PATCH 2/9] Clarify compose file creation in self-hosting guide --- src/content/docs/get-involved/self-hosting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/get-involved/self-hosting.mdx b/src/content/docs/get-involved/self-hosting.mdx index 8cbb1631..bb52929d 100644 --- a/src/content/docs/get-involved/self-hosting.mdx +++ b/src/content/docs/get-involved/self-hosting.mdx @@ -19,7 +19,7 @@ At a minimum, ensure: ## Deployment Overview -1. Copy the reference [`docker-compose.yml`](https://github.com/html2rss/html2rss-web/blob/master/docker-compose.yml) and [`config/feeds.yml`](https://github.com/html2rss/html2rss-web/blob/master/config/feeds.yml) from the project repository to your deployment directory. +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. From eeae053ac3289fe82a9c3e45a46ba474f3f3c8f4 Mon Sep 17 00:00:00 2001 From: Gil Desmarais Date: Sat, 8 Nov 2025 10:39:00 +0100 Subject: [PATCH 3/9] Clarify self-hosting prerequisites --- src/content/docs/get-involved/self-hosting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/get-involved/self-hosting.mdx b/src/content/docs/get-involved/self-hosting.mdx index bb52929d..bd03611a 100644 --- a/src/content/docs/get-involved/self-hosting.mdx +++ b/src/content/docs/get-involved/self-hosting.mdx @@ -9,7 +9,7 @@ Turn any website into an RSS feed. Self-host your own instance and take back con ## 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. +This guide is designed for people 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](/web-application/getting-started/) for a simpler local setup first. When you're ready to go live, 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: From e4580a0baa9873fdb5da1f70b79f951dd621c324 Mon Sep 17 00:00:00 2001 From: Gil Desmarais Date: Sat, 8 Nov 2025 10:47:52 +0100 Subject: [PATCH 4/9] Polish self-hosting guide tone --- src/content/docs/get-involved/self-hosting.mdx | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/src/content/docs/get-involved/self-hosting.mdx b/src/content/docs/get-involved/self-hosting.mdx index bd03611a..f150e10e 100644 --- a/src/content/docs/get-involved/self-hosting.mdx +++ b/src/content/docs/get-involved/self-hosting.mdx @@ -5,13 +5,18 @@ sidebar: order: 3 --- -Turn any website into an RSS feed. Self-host your own instance and take back control of your information diet. +Turn any website into an RSS feed. Self-host your own instance and take back control of your information diet while helping the html2rss ecosystem grow. ## Before You Begin -This guide is designed for people 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](/web-application/getting-started/) for a simpler local setup first. When you're ready to go live, review the full [Deployment & Production guide](/web-application/how-to/deployment) for environment sizing, proxy patterns, and step-by-step production hardening. +This guide walks you through running a production-ready instance that friends, teams, or communities can rely on. You'll need: -At a minimum, ensure: +- 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. + +Before you deploy, double-check this quick checklist: - 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. @@ -24,7 +29,7 @@ At a minimum, ensure: 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. +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 so readers can trust it. ## Harden & Secure @@ -42,6 +47,8 @@ Need extra reliability? Integrate the instance with your existing reverse proxy, 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. +Thanks for investing the time to share html2rss with others. Each new instance expands the open web and helps readers stay in control of the stories they follow. + ## License [MIT](https://github.com/html2rss/html2rss/blob/main/LICENSE) From b2cfca0cb0e480b822f5fb138da207e7ba136dad Mon Sep 17 00:00:00 2001 From: Gil Desmarais Date: Sat, 8 Nov 2025 10:57:25 +0100 Subject: [PATCH 5/9] Polish self-hosting copy --- src/content/docs/get-involved/self-hosting.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/get-involved/self-hosting.mdx b/src/content/docs/get-involved/self-hosting.mdx index f150e10e..b17fb9cd 100644 --- a/src/content/docs/get-involved/self-hosting.mdx +++ b/src/content/docs/get-involved/self-hosting.mdx @@ -5,7 +5,7 @@ sidebar: order: 3 --- -Turn any website into an RSS feed. Self-host your own instance and take back control of your information diet while helping the html2rss ecosystem grow. +Turn any website into an RSS feed. Self-host your own instance to take back control of your information diet and help the html2rss ecosystem grow for everyone. ## Before You Begin @@ -19,17 +19,17 @@ If that feels new, start with the [Getting Started guide](/web-application/getti Before you deploy, double-check this quick checklist: - 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. +- 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. +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 so readers can trust it. +For 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 so readers can trust it. ## Harden & Secure From 2b28e5a894475fecab089d696fc3d6454c0866b2 Mon Sep 17 00:00:00 2001 From: Gil Desmarais Date: Sat, 8 Nov 2025 11:08:39 +0100 Subject: [PATCH 6/9] Update src/content/docs/get-involved/self-hosting.mdx --- src/content/docs/get-involved/self-hosting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/get-involved/self-hosting.mdx b/src/content/docs/get-involved/self-hosting.mdx index b17fb9cd..1857830f 100644 --- a/src/content/docs/get-involved/self-hosting.mdx +++ b/src/content/docs/get-involved/self-hosting.mdx @@ -45,7 +45,7 @@ For extra reliability, integrate the instance with your existing reverse proxy, ## 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. +Running a reliable deployment benefits the broader community. Share your server with the broader community by adding it 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. Thanks for investing the time to share html2rss with others. Each new instance expands the open web and helps readers stay in control of the stories they follow. From bb36cb9a7c28e4c214959a8cce76de4d5dd4eb0b Mon Sep 17 00:00:00 2001 From: Gil Desmarais Date: Sat, 8 Nov 2025 11:09:23 +0100 Subject: [PATCH 7/9] Update src/content/docs/get-involved/self-hosting.mdx --- src/content/docs/get-involved/self-hosting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/get-involved/self-hosting.mdx b/src/content/docs/get-involved/self-hosting.mdx index 1857830f..ea58a04d 100644 --- a/src/content/docs/get-involved/self-hosting.mdx +++ b/src/content/docs/get-involved/self-hosting.mdx @@ -40,7 +40,7 @@ For extra reliability, integrate the instance with your existing reverse proxy, ## 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. +- Automate updates with Watchtower (a Docker container that updates running containers) or your container management platform 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 From ebc8b4c78b4b71e08cd7db58b995f874e60b78c5 Mon Sep 17 00:00:00 2001 From: Gil Desmarais Date: Sat, 8 Nov 2025 11:09:36 +0100 Subject: [PATCH 8/9] Update src/content/docs/get-involved/self-hosting.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/content/docs/get-involved/self-hosting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/get-involved/self-hosting.mdx b/src/content/docs/get-involved/self-hosting.mdx index ea58a04d..12f45819 100644 --- a/src/content/docs/get-involved/self-hosting.mdx +++ b/src/content/docs/get-involved/self-hosting.mdx @@ -35,7 +35,7 @@ For extra reliability, integrate the instance with your existing reverse proxy, - 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. +- Review the [production preparation guidelines](/web-application/how-to/deployment#prepare-for-production) and keep secrets outside of version control. ## Monitor & Maintain From 20e3a379eeb0e25140d57cee5e4ee80d7f9d5b08 Mon Sep 17 00:00:00 2001 From: Gil Desmarais Date: Sat, 8 Nov 2025 11:39:55 +0100 Subject: [PATCH 9/9] Update src/content/docs/get-involved/self-hosting.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/content/docs/get-involved/self-hosting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/get-involved/self-hosting.mdx b/src/content/docs/get-involved/self-hosting.mdx index 12f45819..ea519ddd 100644 --- a/src/content/docs/get-involved/self-hosting.mdx +++ b/src/content/docs/get-involved/self-hosting.mdx @@ -39,7 +39,7 @@ For extra reliability, integrate the instance with your existing reverse proxy, ## 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. +- 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 (a Docker container that updates running containers) or your container management platform 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.