Home - seadogger-tech/seadogger-homelab GitHub Wiki
Production-Ready Kubernetes Homelab on Raspberry Pi 5 Cluster
A modern, enterprise-grade homelab deployment featuring K3s, ArgoCD, Rook-Ceph, and AI-powered applications running on ARM64 hardware.
New to this project? Start here:
- 01-Overview - Understanding the Seadogger Homelab architecture
- 03-Hardware-and-Network - Hardware requirements and network setup
- 04-Bootstrap-and-Cold-Start - Deploy from scratch in 30 minutes
- 09-Apps - Explore available applications
Upgrading or troubleshooting?
- 12-Troubleshooting - Common issues and solutions
- 17-Runbooks - Operational procedures
- 19-Refactoring-Roadmap - Current development priorities
Get started and understand the fundamentals.
| Document | Description |
|---|---|
| 01-Overview | Project vision, features, and architecture overview |
| 02-Architecture | System architecture and design decisions |
Core infrastructure components and deployment.
| Document | Description |
|---|---|
| 03-Hardware-and-Network | Raspberry Pi 5 cluster hardware and network topology |
| 04-Bootstrap-and-Cold-Start | Complete deployment guide with Ansible automation |
| 05-GitOps-and-IaC | GitOps workflow with ArgoCD and Infrastructure as Code |
Infrastructure services powering the homelab.
| Document | Description |
|---|---|
| 06-Storage-Rook-Ceph | Distributed storage with Rook-Ceph erasure coding |
| 07-Networking-and-Ingress | MetalLB, Traefik ingress, and internal routing |
| 08-Security-and-Certificates | Internal PKI, cert-manager, and TLS certificates |
| 09-Apps | Applications: Nextcloud, Jellyfin, OpenWebUI, N8N, PiHole |
| 20-HDHomeRun-Guide | HDHomeRun integration for live TV streaming |
| 16-Pro-Overlays-and-SSO | Pro features: Portal and Single Sign-On |
Configuration guides for specific applications.
| Document | Description |
|---|---|
| 18-Setting-Up-n8n-Connections | Configure N8N workflow automation connections |
Monitor, maintain, and troubleshoot your homelab.
| Document | Description |
|---|---|
| 10-Benchmarking | Performance benchmarks and testing |
| 12-Troubleshooting | Common problems and debugging procedures |
| 15-CI-CD-and-GitHub-Actions | Continuous integration and deployment |
| 17-Runbooks | Operational runbooks and procedures |
Deep dives, design decisions, and planning.
| Document | Description |
|---|---|
| 13-ADR-Index | Architecture Decision Records (ADRs) |
| 14-Design-Deep-Dives | Technical deep dives into complex topics |
| 19-Refactoring-Roadmap | Development priorities and improvement roadmap |
| 21-Deployment-Dependencies | Dependency analysis and GitOps conversion plan |
- Disaster Recovery - S3 Glacier backup for 4TB+ production data (#24)
- Staging Environment - Safe ARM64 testing without production risk (#47)
-
Deployment Dependencies Refactor - Pure GitOps with ArgoCD + Kustomize (#48)
- Move all infrastructure to ArgoCD (#50)
See 19-Refactoring-Roadmap for complete roadmap and GitHub Issues for tracking.
Platform:
- Compute: 4× Raspberry Pi 5 (8GB) - 1 control plane (500GB NVMe) + 3 workers (4TB NVMe each)
- OS: Raspberry Pi OS (Bookworm, ARM64)
- Kubernetes: K3s (lightweight Kubernetes)
Infrastructure:
- GitOps: ArgoCD for declarative deployments
- Storage: Rook-Ceph with erasure coding (3-node cluster)
- Load Balancer: MetalLB (bare-metal LoadBalancer)
- Ingress: Traefik with automatic TLS
- Certificates: cert-manager with internal PKI
Applications:
- File Sharing: Nextcloud (personal cloud storage)
- Media Server: Jellyfin (movies, music, live TV via HDHomeRun)
- DNS/Ad Blocking: PiHole (network-wide ad blocking)
- AI Assistant: OpenWebUI + AWS Bedrock (Claude, Sonnet models)
- Workflow Automation: N8N (automation and integrations)
- Dashboard: Custom portal with SSO (Pro feature)
New to Kubernetes?
New to GitOps?
Ansible Automation:
This is a personal homelab project, but contributions are welcome!
- Found a bug? Open an issue
- Have a suggestion? Start a discussion
- Want to contribute? Fork the repo and submit a pull request
Current Version: Production (September 2025) Cluster Uptime: Running 24/7 with active users Data Under Management: ~4TB (Nextcloud, Jellyfin, media) Active Development: See 19-Refactoring-Roadmap for current priorities
Built with ❤️ using Raspberry Pi, Kubernetes, and Open Source