README.md
Rama main · réplica de lectura del repositorio original.
# Home Lab
My personal homelab setup. Nothing fancy but it gets the job done 😎. Reliable, secure, and easy to maintain.
For more details on my hardware specifications see [here](#my-current-hardware-specifications).
## Architecture Overview
The infrastructure is built around Docker containers orchestrated using Docker Compose.
All services are exposed with Traefik as a reverse proxy, providing SSL termination and automatic service discovery via Docker container labels.
The homelab uses two main Docker networks:
- `reverse-proxy` - For services exposed through Traefik reverse proxy
- `prometheus` - For services integrating with Prometheus for monitoring and metrics collection
Web services are organized with hostname-based routing (*.lucascott.com). They are automatically discovered by Traefik using Docker labels. Internal-only services are protected with the `internalOnly@file` middleware which restricts access to the local network and Tailscale IP range.
In addition, public internet-facing services are protected by Cloudflare's WAF and DDoS protection.
All web services exposed via Traefik use the same wildcard Let's Encrypt certificate with DNS-01 challenge via Cloudflare.
This allows secure access to all public and internal only services without needing to manage individual certificates.
### Third-Party Services
* [Cloudflare](https://www.cloudflare.com/en-gb/) for domain registration and public DNS hosting. Cloudflare's free tier provides sufficient features for my needs.
* [Tailscale](https://tailscale.com/) for secure remote access to internal services when away from home.
* GitHub + Github Actions to host all my code and automate deployment of my personal website.
* [Srenity.online](https://www.srenity.online/) to find serenity in this self-hosting journey!
## Quick Start
1. **Initial Setup**
```bash
./setup.sh
```
This creates the required Docker networks (`reverse-proxy` and `prometheus`).
2. **Service Configuration**
Each service directory contains its own `compose.yaml` and configuration files. Navigate to the specific service directory and run:
```bash
docker compose up -d
```
## Services
### Public Services
| Service | Description | Directory |
|--------------------------------------------------------|---------------------|------------------------------|
| [**www.lucascott.com**](https://www.lucascott.com) | My personal website | [`lucascott/`](./lucascott/) |
| [**mixes.lucascott.com**](https://mixes.lucascott.com) | My DJ mixes archive | [`waves/`](./waves/) |
### Infrastructure & Core Services
| Service | Description | Directory |
|----------------------------------------------------------------|--------------------------------------------------------------------|--------------------------|
| [**Traefik**](https://github.com/traefik/traefik) | Reverse proxy with automatic SSL and service discovery | [`traefik/`](./traefik/) |
| [**AdGuard Home**](https://github.com/AdguardTeam/AdGuardHome) | DNS server for ad and tracker blocking and internal domain routing | [`adguard/`](./adguard/) |
### Monitoring & Observability
| Service | Description | Directory |
|---------------------------------------------------------------|-------------------------------------|--------------------------------|
| [**Prometheus**](https://prometheus.io/) | Metrics collection and storage | [`prometheus/`](./prometheus/) |
| [**Grafana**](https://grafana.com/oss/grafana/) | Metrics visualization dashboard | [`grafana/`](./grafana/) |
| [**What's Up Docker (WUD)**](https://getwud.github.io/wud/#/) | Container update monitoring service | [`wud/`](./wud/) |
| [**Dockge**](https://github.com/louislam/dockge) | Docker Compose stack manager | [`dockge/`](./dockge/) |
| [**Portainer**](https://github.com/portainer/portainer) | Docker container management UI | [`portainer/`](./portainer/) |
### Identity, Security & Privacy
| Service | Description | Directory |
|---------------------------------------------------------------|----------------------------------------|----------------------------------|
| [**Vaultwarden**](https://github.com/dani-garcia/vaultwarden) | Self-hosted Bitwarden password manager | [`vaultwarden/`](./vaultwarden/) |
| [**Pocket ID**](https://github.com/pocket-id/pocket-id) | OpenID Connect identity provider | [`pocket-id/`](./pocket-id/) |
### Media & Personal Services
| Service | Description | Directory |
|-------------------------------------------------------------|-------------------------------------|------------------------------------|
| [**Homepage**](https://gethomepage.dev/) | Homepage dashboard for services | [`homepage/`](./homepage/) |
| [**Immich**](https://immich.app/) | Self-hosted photo and video backup | [`immich/`](./immich/) |
| [**SilverBullet**](https://silverbullet.md/) | Personal knowledge management | [`silverbullet/`](./silverbullet/) |
| [**Navidrome**](https://github.com/navidrome/navidrome) | Self-hosted music streaming server | [`navidrome/`](./navidrome/) |
| [**Picard**](https://picard.musicbrainz.org/) | Music tagging and organization tool | [`picard/`](./picard/) |
| [**Telewaves**](https://github.com/lucascott/telewaves) | Telegram bot for music downloads | [`telewaves/`](./telewaves/) |
| [**YourSpotify**](https://github.com/Yooooomi/your_spotify) | Spotify listening statistics | [`yourspotify/`](./yourspotify/) |
### Smart Home & IoT
| Service | Description | Directory |
|------------------------------------|-------------------------------------------|--------------------------|
| [**ESPHome**](https://esphome.io/) | ESP32 home environment monitoring station | [`esphome/`](./esphome/) |
## Security Considerations
- **Internal Services**: All services not meant to be publicly exposed are configured with IP whitelisting via Traefik's `internalOnly@file` middleware. This restricts access to the local network and Tailscale IP range only.
- **SSL/TLS**: All web services are exposed via Traefik and use a Let's Encrypt wildcard certificate managed by Traefik.
- **Firewall**: The host machine runs a firewall allowing only necessary incoming ports (80, 443, 53 if using AdGuard Home).
- **User Permissions**: Docker containers run with least privilege, avoiding root user where possible.
- **Regular Updates**: Services are monitored for updates using WUD, and updates are applied regularly to ensure security patches are in place.
- **Strong Passwords**: Services requiring authentication (e.g., Vaultwarden, Portainer) are secured with strong, unique passwords.
- **Secrets Management**: Sensitive data stored in Docker secrets files (e.g., Cloudflare API tokens) in the host machine with restricted user permissions.
- **Network Isolation**: Services use dedicated networks (created automatically by Docker Compose) for secure internal communication. When necessary, individual services are connected to both `reverse-proxy` and `prometheus` networks.
## Reliability & Backups
- **Data Persistence**: Critical services use Docker volumes for data persistence in the host filesystem.
- **Backups**: Regular backups of important data are performed using custom scripts (not included in this repository) and stored offsite.
- **Uptime monitoring**: Uptime Kuma (not included in this repository yet) monitors public and internal services for availability and sends alerts via Telegram.
- **Failure recovery**: In case of a service failure, the service is automatically restarted based on Docker Compose `restart` policy.
## Updates
The What's Up Docker (WUD) service monitors for container updates.
Update notifications are sent to me by a personal Telegram bot integrated with WUD.
Most services are configured with:
- `wud.watch.digest=true` - Monitor for image updates
- `wud.tag.include/exclude` - Control which tags to monitor
- `wud.link.template` - Direct links to release pages
Updates can be applied via WUD UI's Docker trigger button, via Dockge UI, or manually by navigating to the service directory and running:
```bash
cd <service-directory>
docker compose pull && docker compose up -d --remove-orphans
```
## Monitoring
- **Prometheus**: Collects metrics from cAdvisor and other exporters
- **Grafana**: Visualizes system and application metrics
- **Logs**: Container logs available via `docker compose logs`
## Contributing
When adding new services:
1. Create a new directory with descriptive name
2. Include `compose.yaml` with proper network configuration
3. Add Traefik labels for automatic routing
4. Create service-specific README with setup instructions
5. Update this main README with service information
## Future Improvements
- Include missing services in this repository:
- Uptime Kuma configuration for service uptime monitoring
- Backup scripts/configuration and documentation
## My current hardware specifications
### Main Server
**HP EliteDesk 800 65W G3 Mini**
- **Host OS**: Debian GNU/Linux 12 (bookworm) on bare metal
- **CPU**: Intel(R) Core(TM) i5-7500 CPU @ 3.40GHz (4 cores / 4 threads)
- **RAM**: 16GB
- **Storage**:
- 256GB NVMe SSD for OS and Docker containers
- 500GB SSD for Docker volumes and persistent data
### Secondary Servers
**Raspberry Pi 3b+**
- **Host OS**: Raspberry Pi OS Lite 64-bit - Debian 12 (bookworm)
- **Storage**: 32GB microSD card
- **Purpose**: Dedicated AdGuard Home DNS server for Tailscale clients
**Raspberry Pi 3b+**
- **Host OS**: Raspberry Pi OS Lite 64-bit - Debian 12 (bookworm)
- **Storage**:
- 32GB microSD card
- External 1TB USB SSD for media storage backup
- **Purpose**: Offsite backup server and uptime monitoring server
## License
This is a personal homelab configuration. Use at your own discretion.