docs: rewrite READMEs to reflect Kubernetes migration
This commit is contained in:
150
README.md
150
README.md
@@ -1,81 +1,115 @@
|
||||
# Homelab Infrastructure
|
||||
|
||||
A collection of self-hosted services running on Docker containers, orchestrated through Portainer and exposed via Traefik reverse proxy.
|
||||
Self-hosted services running on a single-node Talos Kubernetes cluster, provisioned via Terraform on Proxmox and managed through Flux CD GitOps.
|
||||
|
||||
## Architecture
|
||||
|
||||
This homelab uses a stack-based approach where each service is containerized and deployed as a complete stack with its dependencies. All services integrate with a centralized Traefik instance for SSL termination and domain routing.
|
||||
|
||||
### Stack Structure
|
||||
```
|
||||
docker/stacks/<service>/
|
||||
- docker-compose.yaml # Service definition
|
||||
- stack.env # Environment template (tracked)
|
||||
- stack.env.real # Actual values with secrets (gitignored)
|
||||
Proxmox (hypervisor)
|
||||
└── Talos Linux VM (Kubernetes node)
|
||||
└── Flux CD (GitOps)
|
||||
├── config → cluster-wide variables & secrets
|
||||
├── infrastructure → Traefik, cert-manager, Authelia, MetalLB, NFS, ...
|
||||
└── apps → application workloads
|
||||
```
|
||||
|
||||
### Repository Layout
|
||||
|
||||
```
|
||||
homelab-v2/
|
||||
├── terraform/ # Proxmox VM + Talos cluster provisioning
|
||||
└── kubernetes/ # Flux CD manifests (Kustomize + Helm)
|
||||
├── config/
|
||||
├── flux-system/
|
||||
├── infrastructure/
|
||||
│ ├── controllers/ # Traefik, cert-manager, Authelia, MetalLB, ...
|
||||
│ └── configs/ # ClusterIssuer, MetalLB config
|
||||
├── app/
|
||||
│ ├── archmirror/
|
||||
│ ├── external/ # External service vars (e.g. Home Assistant)
|
||||
│ ├── grocy/
|
||||
│ ├── homepage/
|
||||
│ ├── immich/
|
||||
│ ├── jellyfin/
|
||||
│ ├── lubelogger/
|
||||
│ ├── media/
|
||||
│ ├── paperless/
|
||||
│ ├── pihole/
|
||||
│ └── podsync/
|
||||
└── docs/
|
||||
└── k8s-service-spec.md
|
||||
```
|
||||
|
||||
## Services
|
||||
|
||||
| Service | Description | Purpose |
|
||||
|---------|-------------|---------|
|
||||
| **Immich** | Self-hosted photo and video management | Personal media library with ML features |
|
||||
| **Paperless-ngx** | Document management system with OCR | Digital document archive and search |
|
||||
| **Media Stack** | Sonarr, Radarr, Prowlarr, qBittorrent | Automated media acquisition and management |
|
||||
| **Pi-hole** | DNS sinkhole with ad blocking and dnscrypt-proxy | Network-wide ad blocking and encrypted DNS |
|
||||
| **Arch Mirror** | Local Arch Linux package repository mirror | Local package cache for faster updates |
|
||||
| Service | Description |
|
||||
|---------|-------------|
|
||||
| **Immich** | Photo and video management with face recognition |
|
||||
| **Jellyfin** | Media streaming with Intel GPU hardware transcoding |
|
||||
| **Media Stack** | Sonarr, Radarr, Prowlarr, qBittorrent — automated media acquisition |
|
||||
| **Paperless-ngx** | Document management with OCR |
|
||||
| **Pi-hole** | DNS sinkhole with ad blocking and encrypted DNS via dnscrypt-proxy |
|
||||
| **Grocy** | Pantry and grocery management |
|
||||
| **LubeLogger** | Vehicle maintenance tracker |
|
||||
| **Homepage** | Dashboard aggregator |
|
||||
| **Podsync** | Podcast downloader |
|
||||
| **Archmirror** | Local Arch Linux package repository mirror |
|
||||
|
||||
## Infrastructure Stack
|
||||
|
||||
| Component | Role |
|
||||
|-----------|------|
|
||||
| **Flux CD** | GitOps controller — reconciles this repo to the cluster |
|
||||
| **Traefik** | Ingress controller with Let's Encrypt TLS |
|
||||
| **cert-manager** | TLS certificate provisioning (Cloudflare DNS-01) |
|
||||
| **Authelia** | SSO / OIDC provider for protected services |
|
||||
| **MetalLB** | Bare-metal load balancer |
|
||||
| **NFS Provisioner** | Dynamic PVC provisioning backed by Synology NAS |
|
||||
| **Intel GPU Plugin** | Hardware transcoding device plugin (Jellyfin) |
|
||||
| **SOPS + age** | Secret encryption at rest |
|
||||
|
||||
### Storage
|
||||
|
||||
- **Synology NAS** — primary storage backend for all services
|
||||
- Dynamic NFS PVCs via `nfs-synology-ssd` storage class
|
||||
- Static NFS PVs for media library and document archives
|
||||
- **local-path-provisioner** — node-local storage for SQLite databases
|
||||
|
||||
### Backups
|
||||
|
||||
Unified strategy using **restic + resticprofile**:
|
||||
|
||||
- **Primary**: Synology NAS via `rest-server` container (`${BACKUP_LOCAL_HOST}:8000`)
|
||||
- **Secondary**: Backblaze B2 (offsite), synced via `resticprofile copy`
|
||||
- PostgreSQL: pg_dump init container → restic
|
||||
- SQLite: online backup API → restic
|
||||
- Files/media: NFS mount → restic
|
||||
|
||||
## Deployment
|
||||
|
||||
Services are deployed through **Portainer WebUI**:
|
||||
All changes are deployed by pushing to this repository. Flux CD reconciles on every commit.
|
||||
|
||||
1. Access Portainer dashboard
|
||||
2. Navigate to Stacks section
|
||||
3. Create new stack or update existing
|
||||
4. Copy content from `docker-compose.yaml`
|
||||
5. Configure environment variables from `stack.env.real`
|
||||
6. Deploy stack
|
||||
```sh
|
||||
# Check reconciliation status
|
||||
flux get kustomizations
|
||||
|
||||
### Environment Setup
|
||||
# Force reconciliation
|
||||
flux reconcile source git flux-system
|
||||
|
||||
For each stack:
|
||||
```bash
|
||||
cd docker/stacks/<service>/
|
||||
cp stack.env stack.env.real
|
||||
# Edit stack.env.real with actual values
|
||||
# Check application status
|
||||
kubectl get helmreleases -A
|
||||
kubectl get pods -A
|
||||
```
|
||||
|
||||
## Common Operations
|
||||
|
||||
### Stack Management
|
||||
- Stack status and logs monitored through Portainer WebUI dashboard
|
||||
- Updates performed by pulling new images and recreating containers
|
||||
|
||||
### Backup Operations
|
||||
Each stack includes automated backup services:
|
||||
- **Database backups**: Hourly PostgreSQL dumps using postgres-backup-local
|
||||
- **File backups**: Scheduled Restic backups to AWS S3 backend
|
||||
|
||||
## Network Architecture
|
||||
|
||||
- **traefik** (external): Reverse proxy network for SSL termination and routing
|
||||
- **service-specific**: Internal networks for each stack (immich, paperless, sonarr, radarr)
|
||||
- Services primarily accessed through Traefik with minimal direct port exposure
|
||||
For initial cluster bootstrap, see [`kubernetes/README.md`](kubernetes/README.md).
|
||||
|
||||
## Security
|
||||
|
||||
- All services behind Traefik reverse proxy with Let's Encrypt SSL certificates
|
||||
- Environment variables with secrets stored in `*.env.real` files (gitignored)
|
||||
- API endpoints protected with HTTP basic authentication where applicable
|
||||
- Internal service communication isolated over Docker networks
|
||||
- All ingress through Traefik with Let's Encrypt TLS
|
||||
- Secrets encrypted with SOPS + age (decrypted at runtime by Flux)
|
||||
- SSO via Authelia (OIDC) for user-facing services
|
||||
- Per-namespace NetworkPolicies with default-deny + explicit Traefik ingress allow
|
||||
|
||||
## Requirements
|
||||
## Provisioning
|
||||
|
||||
- Docker and Docker Compose
|
||||
- Portainer CE for stack management
|
||||
- Traefik reverse proxy (external dependency)
|
||||
- Valid domain names for SSL certificate generation
|
||||
|
||||
## Notes
|
||||
|
||||
- This repository contains infrastructure definitions only
|
||||
- Actual deployment and management handled through Portainer WebUI
|
||||
The cluster is provisioned with Terraform (Proxmox + Talos). See [`terraform/README.md`](terraform/README.md).
|
||||
|
||||
Reference in New Issue
Block a user