feat: add self-host instructions

Closes #827

Author: gildesmarais

src/content/docs/get-involved/index.mdx

@@ -8,7 +8,8 @@ sidebar:
 Engage with the `html2rss` project. Contribute and connect with the community.
 
 - [**Project Roadmap**](https://github.com/orgs/html2rss/projects/3/views/1): View current work, plans, and priorities.
+- [**Self-Host Your Own Instance**](/get-involved/self-hosting): Take control of your information diet and join the decentralized web movement.
 - [**Report Bugs & Discuss Features**](/get-involved/issues-and-features): Report bugs or propose features.
 - [**Join Community Discussions**](/get-involved/discussions): Connect with users and contributors.
 - [**Contribute to html2rss**](/get-involved/contributing): Contribute code, documentation, or feed configurations.
-- [**Sponsoring**](/get-involved/sponsoring)
+- [**Sponsoring**](/get-involved/sponsoring).

src/content/docs/get-involved/self-hosting.mdx

@@ -0,0 +1,40 @@
+---
+title: "Self-Host Your Own Instance"
+description: "Take control of your information diet. Host your own html2rss instance and join the decentralized web movement."
+sidebar:
+  order: 3
+---
+
+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#security)
+- [Enable HTTPS](/web-application/how-to/deployment#https)
+- [Troubleshoot issues](/troubleshooting/troubleshooting)
+- [Join the community](https://github.com/orgs/html2rss/discussions)
+
+---
+
+## License
+
+[MIT](https://github.com/html2rss/html2rss/blob/main/LICENSE)

src/content/docs/troubleshooting/troubleshooting.mdx

@@ -11,7 +11,9 @@ Your browser's developer tools are essential for troubleshooting. Use them to in
 
 - **To open:** Right-click an element on a webpage and select "Inspect" or "Inspect Element."
 
-## Common Issues
+---
+
+## Common Issues (Ruby Gem / CLI)
 
 ### Empty Feeds
 
@@ -21,7 +23,7 @@ If your feed is empty, check the following:
 - **`items.selector`:** Verify that the `items.selector` matches the elements on the page.
 - **Website Changes:** Websites change their HTML structure frequently. Your selectors may be outdated.
 - **JavaScript Content:** If the content is loaded via JavaScript, use the `browserless` strategy instead of `faraday`.
-- **Authentication:** Some sites require authentication - check if you need to add headers or use a different strategy.
+- **Authentication:** Some sites require authentication — check if you need to add headers or use a different strategy.
 
 ### Configuration Errors
 
@@ -54,21 +56,68 @@ If you are getting a "command not found" error, try the following:
 - **Re-install:** Re-install `html2rss` to ensure it is installed correctly: `gem install html2rss`.
 - **Check `PATH`:** Ensure that the directory where Ruby gems are installed is in your system's `PATH`.
 
-### Web Application Errors
-
-For html2rss-web specific issues:
+---
 
-- **`401 Unauthorized`:** Check your `AUTO_SOURCE_USERNAME` and `AUTO_SOURCE_PASSWORD` environment variables.
-- **`403 Forbidden`:** The URL is not in the `AUTO_SOURCE_ALLOWED_URLS` list, or the origin is not in `AUTO_SOURCE_ALLOWED_ORIGINS`.
-- **`500 Internal Server Error`:** Check the application logs for detailed error information.
+## Web Application Issues (html2rss-web)
+
+### Instance Won’t Start
+
+- Verify Docker is installed and running:
+  ```bash
+  docker --version
+  ```
+- Check logs for errors:
+  ```bash
+  docker compose logs
+  ```
+- Ensure the port (default: 3000) isn’t already in use:
+  ```bash
+  netstat -tulpn | grep :3000
+  ```
+
+### Can’t Access the Web Interface
+
+- Confirm your firewall allows traffic on port 3000 (or the port you configured)
+- Try accessing via the server’s IP instead of a domain name
+- Double-check that containers are running:
+  ```bash
+  docker compose ps
+  ```
+
+### Authentication Errors
+
+- **401 Unauthorized:** Check your `AUTO_SOURCE_USERNAME` and `AUTO_SOURCE_PASSWORD` environment variables.
+- **403 Forbidden:** The URL is not in the `AUTO_SOURCE_ALLOWED_URLS` list, or the origin is not in `AUTO_SOURCE_ALLOWED_ORIGINS`.
+- **500 Internal Server Error:** Check the application logs for detailed error information.
 - **Health check failures:** Use the `/health_check.txt` endpoint to identify which specific feed configurations are broken.
 
+### SSL / HTTPS Issues
+
+- Follow the [nginx reverse proxy guide](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/)
+- Use [Let’s Encrypt with certbot](https://certbot.eff.org/) to obtain valid certificates
+- Verify your reverse proxy forwards requests to the correct internal port
+
+### Feed Problems
+
+- Some sites may require JavaScript rendering; ensure the `browserless` service is running
+- Check the feed configuration in `feeds.yml` for typos or invalid selectors
+- Look for parsing errors in the logs:
+  ```bash
+  docker compose logs html2rss-web
+  ```
+
+---
+
 ## Tips & Tricks
 
 - **Mobile Redirects:** Check that the channel URL does not redirect to a mobile page with a different markup structure.
 - **`curl` and `pup`:** For static sites, use `curl` and `pup` to quickly find selectors: `curl URL | pup`.
 - **CSS Selectors:** For a comprehensive overview of CSS selectors, see the [W3C documentation](https://www.w3.org/TR/selectors-4/#overview).
 
+---
+
 ## Still Stuck?
 
-If you are still having issues, please [open an issue on GitHub](https://github.com/html2rss/html2rss/issues).
+- Join our [community discussions](https://github.com/orgs/html2rss/discussions)
+- [Open an issue on GitHub](https://github.com/html2rss/html2rss/issues)
+- Review the [deployment guide](/web-application/how-to/deployment) for production best practices

src/content/docs/web-application/how-to/deployment.mdx

@@ -3,26 +3,41 @@ title: "Deployment & Production"
 description: "Deploy html2rss-web to production with Docker. Learn best practices for hosting public instances with security, monitoring, and reliability."
 ---
 
-html2rss-web is published on Docker Hub, making it easy to deploy with Docker. The `docker-compose.yml` from our [Installation Guide](/web-application/getting-started) provides a solid foundation for both development and production use.
+html2rss-web is published on Docker Hub, making it easy to deploy with Docker. The [`docker-compose.yml`](https://github.com/html2rss/html2rss-web/blob/master/docker-compose.yml) from our [Installation Guide](/web-application/getting-started) provides a solid foundation for both development and production use.
 
 ## Quick Start
 
-If you've already set up html2rss-web locally, you're ready to deploy it to production. The same Docker configuration works for both environments.
+1. Create a directory for your instance:
+   ```bash
+   mkdir html2rss-web && cd html2rss-web
+   ```
+2. 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
+   ```
+3. Start the instance:
+   ```bash
+   docker compose up -d
+   ```
+4. Open [http://localhost:3000](http://localhost:3000) to verify it’s running.
+
+> 📖 Need Docker? Follow the [Docker installation guide](https://docs.docker.com/get-docker/) and [Docker Compose install](https://docs.docker.com/compose/install/).
 
 ## Production Best Practices
 
 When hosting a **public instance** that others will use, please follow these essential guidelines:
 
 ### Security Essentials
 
-- **Use a reverse proxy** (nginx, Apache, or Cloudflare) to handle SSL termination and rate limiting
-- **Enable HTTPS only** - redirect all HTTP traffic to HTTPS
+- **Use a reverse proxy** ([nginx](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/), Apache, or Cloudflare) to handle SSL termination and rate limiting
+- **Enable HTTPS only** — redirect all HTTP traffic to HTTPS ([certbot guide](https://certbot.eff.org/))
 - **Set strong passwords** for health check and auto-source authentication
 - **Restrict access** to admin endpoints and sensitive configuration
 
 ### Reliability & Monitoring
 
-- **Enable auto-updates** using watchtower or similar tools
+- **Enable auto-updates** using [watchtower](https://containrrr.dev/watchtower/) or similar tools
 - **Monitor the health check endpoint** (`/health_check.txt`) to detect issues early
 - **Set up logging** to track errors and performance
 - **Use environment variables** for configuration instead of hardcoded values
@@ -31,7 +46,7 @@ When hosting a **public instance** that others will use, please follow these ess
 
 - **Configure appropriate resource limits** for your Docker containers
 - **Use a CDN** for static assets if serving many users
-- **Monitor memory usage** - html2rss-web can be memory-intensive with large feeds
+- **Monitor memory usage** — html2rss-web can be memory-intensive with large feeds
 - **Set up caching** for frequently accessed feeds
 
 ## Environment Configuration
@@ -47,6 +62,8 @@ environment:
   BASE_URL: https://your-domain.com
 ```
 
+Use a [password manager](https://bitwarden.com/password-generator/) to generate strong values.
+
 ## Share Your Instance
 
 Once your instance is running smoothly: