{"id":49882182,"url":"https://github.com/npozs77/home-server-platform","last_synced_at":"2026-05-15T15:35:07.562Z","repository":{"id":354700231,"uuid":"1141863419","full_name":"npozs77/home-server-platform","owner":"npozs77","description":"Self-hosted home server platform: Docker, Caddy, Wiki.js, Ollama, Immich, Jellyfin, Samba — automated deployment with modular bash scripts","archived":false,"fork":false,"pushed_at":"2026-04-29T16:46:45.000Z","size":677,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-29T18:27:24.594Z","etag":null,"topics":["bash","caddy","docker","docker-compose","home-lab","homeserver","immich","infrastructure-as-code","jellyfin","local-llm","media-server","ollama","open-webui","pihole","privacy","reverse-proxy","samba","self-hosted","ubuntu-server","wiki-js"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/npozs77.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-25T15:07:24.000Z","updated_at":"2026-04-29T16:46:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/npozs77/home-server-platform","commit_stats":null,"previous_names":["npozs77/home-server-platform"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/npozs77/home-server-platform","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npozs77%2Fhome-server-platform","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npozs77%2Fhome-server-platform/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npozs77%2Fhome-server-platform/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npozs77%2Fhome-server-platform/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/npozs77","download_url":"https://codeload.github.com/npozs77/home-server-platform/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npozs77%2Fhome-server-platform/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33071331,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T11:35:32.926Z","status":"ssl_error","status_checked_at":"2026-05-15T11:35:31.362Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","caddy","docker","docker-compose","home-lab","homeserver","immich","infrastructure-as-code","jellyfin","local-llm","media-server","ollama","open-webui","pihole","privacy","reverse-proxy","samba","self-hosted","ubuntu-server","wiki-js"],"created_at":"2026-05-15T15:35:02.619Z","updated_at":"2026-05-15T15:35:07.554Z","avatar_url":"https://github.com/npozs77.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Home Media Server\r\n\r\nPrivate infrastructure-as-code repository for a family home server. Manages the full lifecycle from OS hardening through service deployment using spec-driven development, phased deployment scripts, and property-based testing.\r\n\r\n## What's Running\r\n\r\n| Service | Purpose | URL Pattern |\r\n|---------|---------|-------------|\r\n| Caddy | Reverse proxy, automatic HTTPS | — |\r\n| Pi-hole | Local DNS ad-blocking | `dns.home.mydomain.com` |\r\n| Netdata | Real-time monitoring | `monitor.home.mydomain.com` |\r\n| Jellyfin | Media streaming | `media.home.mydomain.com` |\r\n| Samba | File sharing (SMB) | LAN shares |\r\n| Immich | Photo management | `photos.home.mydomain.com` |\r\n| Wiki.js | Family wiki | `wiki.home.mydomain.com` |\r\n| Open WebUI | AI chat (local LLM) | `chat.home.mydomain.com` |\r\n\r\n## External Services (Free Tier)\r\n\r\n| Service | Purpose |\r\n|---------|---------|\r\n| Cloudflare | Domain registration + DNS management |\r\n| SMTP2Go | Outbound email alerts (msmtp relay) |\r\n\r\n## Stack\r\n\r\n- **OS**: Ubuntu Server LTS 24.04\r\n- **Containers**: Docker / Docker Compose V2\r\n- **Reverse Proxy**: Caddy (automatic HTTPS via internal CA)\r\n- **DNS**: Pi-hole (local resolution + ad-blocking)\r\n- **Monitoring**: Netdata + email alerts (msmtp/SMTP2Go)\r\n- **File Sharing**: Samba (per-user + family shared + media library)\r\n- **Backup**: LUKS-encrypted DAS, nightly cron (configs + Immich pg_dump + Wiki.js pg_dump + Open WebUI data)\r\n- **Automation**: Bash scripts, phased deployment with interactive menus\r\n- **Security**: LUKS disk encryption, SSH key-only, UFW firewall, fail2ban\r\n\r\n## Deployment Phases\r\n\r\n| Phase | Name | Status | Description |\r\n|-------|------|--------|-------------|\r\n| 01 | Foundation | ✅ Deployed | OS hardening, SSH, firewall, LUKS, Docker, Git, DAS backup target |\r\n| 02 | Infrastructure | ✅ Deployed | Caddy, Pi-hole, Netdata, SMTP, data directories |\r\n| 03 | Core Services | ✅ Deployed | Samba, Jellyfin, user provisioning, storage, backup orchestrator, container health checks |\r\n| 04 | Photo Management | ✅ Deployed | Immich, external library, photo prep tooling |\r\n| 05 | Family Wiki \u0026 AI | 🚧 In Progress | Wiki.js, local LLM (Ollama + Open WebUI), RAG, wiki-to-RAG sync |\r\n| 06 | Home Automation | 📋 Planned | Home Assistant, smart device control |\r\n| 07 | Advanced Features | 📋 Planned | Zero-trust remote access, container lifecycle, optional services |\r\n\r\n## Repository Structure\r\n\r\n```\r\nconfigs/                    # Configuration templates (*.example — secrets never committed)\r\n  foundation.env.example    #   System-level config (hostname, IPs, disks)\r\n  services.env.example      #   Service config (domains, SMTP, DNS)\r\n  secrets.env.example       #   Sensitive data (passphrases, API keys)\r\n  docker-compose/           #   Docker Compose files per service\r\n  caddy/                    #   Caddyfile and error pages\r\n  samba/                    #   Samba configuration\r\n  monitoring/               #   Container health check config\r\n\r\nscripts/\r\n  deploy/                   # Phased deployment scripts with interactive menus\r\n  deploy/tasks/             #   Modular task scripts (one per deployment step)\r\n  backup/                   # Backup orchestrator + per-service backup scripts\r\n  operations/utils/         # Shared utilities (logging, env loading, validation)\r\n  operations/monitoring/    # Container health checks\r\n\r\ndocs/                       # Operational documentation (AS-IS reference)\r\n  deployment_manuals/       #   Step-by-step deployment guides per phase\r\n  00-architecture-overview  #   System architecture and design decisions\r\n  12-runbooks               #   Troubleshooting and recovery procedures\r\n\r\ntests/                      # Property-based tests and validation scripts (30 files)\r\n```\r\n\r\n`.kiro/` (specs, steering, hooks) is gitignored and lives only in the local dev environment.\r\n\r\n## Getting Started\r\n\r\n### Fresh Install\r\n\r\n1. Install Ubuntu Server LTS 24.04 (minimal, with SSH enabled)\r\n2. Clone the repo directly on the server:\r\n   ```bash\r\n   sudo mkdir -p /opt/homeserver \u0026\u0026 cd /opt/homeserver\r\n   sudo git clone https://github.com/youruser/homeserver.git .\r\n   ```\r\n3. Copy example configs and customize:\r\n   ```bash\r\n   cp configs/foundation.env.example configs/foundation.env\r\n   cp configs/services.env.example configs/services.env\r\n   cp configs/secrets.env.example configs/secrets.env\r\n   # Edit each file with your values\r\n   ```\r\n4. Run Phase 1 deployment (interactive menu):\r\n   ```bash\r\n   sudo scripts/deploy/deploy-phase1-foundation.sh\r\n   ```\r\n5. Continue with Phase 2, 3, 4 in order. Each deployment manual is in `docs/deployment_manuals/`.\r\n\r\nEach deployment script provides an interactive menu:\r\n- **Option 0**: Initialize/update configuration (prompts for all variables)\r\n- **Option c**: Validate configuration\r\n- **Options 1-N**: Execute individual deployment tasks\r\n- **Option v**: Run full phase validation\r\n- **Option q**: Quit\r\n\r\n## Testing\r\n\r\n30 test files with 800+ property-based assertions. Tests validate script structure, correctness properties, and governance compliance without requiring the server.\r\n\r\n```bash\r\n# Run all test suites\r\nbash tests/run-all.sh\r\n\r\n# Run specific test suite\r\nbash tests/test_backup_alerting.sh        # Backup \u0026 alerting (192 assertions)\r\nbash tests/test_phase1_scripts.sh         # Phase 1 foundation (76 assertions)\r\nbash tests/test_phase3_scripts.sh         # Phase 3 core services\r\nbash tests/test_phase4_scripts.sh         # Phase 4 photo management\r\nbash tests/test_phase5_scripts.sh         # Phase 5 wiki + LLM platform\r\n```\r\n\r\n## Configuration\r\n\r\nThree logical config files (resolved at runtime on the server):\r\n\r\n| File | Permissions | Purpose |\r\n|------|-------------|---------|\r\n| `foundation.env` | 644 | System-level: hostname, IPs, disks, backup DAS |\r\n| `services.env` | 644 | Service-level: domains, SMTP, DNS settings |\r\n| `secrets.env` | 600 (root) | Sensitive: LUKS passphrase, API keys |\r\n\r\nCopy `*.example` files and customize. Real values are never committed to Git.\r\n\r\n## Governance\r\n\r\nScript size guidelines enforced by `scripts/operations/validate-governance.sh`:\r\n\r\n| Script Type | Target LOC | Rationale |\r\n|-------------|-----------|-----------|\r\n| Deployment scripts | ~300 | AI context window + readability |\r\n| Task modules | ~150 | Single responsibility |\r\n| Utility libraries | ~200 | Reusable, focused |\r\n| Backup/monitoring | ~150 | Operational simplicity |\r\n\r\n## Key Design Decisions\r\n\r\n- **DHCP reservation** (not static IP) — network resilient if server fails\r\n- **Registered domain** with internal subdomain — proper HTTPS, no browser warnings\r\n- **Application-level access control** — Linux permissions for ownership, apps for visibility\r\n- **`group_add` for containers** — simple Linux group model, no UID remapping\r\n- **Samba `force group`** — shared uploads get correct group ownership automatically\r\n- **Config-driven** — `foundation.env` / `services.env` / `secrets.env`, no hardcoded values\r\n\r\n## Access Model\r\n\r\n| Role | SSH | Docker | Samba | Web Apps |\r\n|------|-----|--------|-------|----------|\r\n| Admin | ✅ All devices | ✅ | ✅ Full | ✅ Full |\r\n| Power User | ✅ Personal device | ✅ | ✅ Limited | ✅ Full |\r\n| Standard User | ❌ | ❌ | ✅ Personal + shared | ✅ Full |\r\n\r\n## Notes\r\n\r\n- Secrets (`.env`, keys, certs) are gitignored and never committed\r\n- Pre-commit hook scans for PII/secrets via [gitleaks](https://github.com/gitleaks/gitleaks) — run `bash scripts/setup-hooks.sh` after cloning\r\n- Companion public repo (published separately) holds generic operational documentation\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpozs77%2Fhome-server-platform","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnpozs77%2Fhome-server-platform","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpozs77%2Fhome-server-platform/lists"}