89 lines
4.7 KiB
Markdown
89 lines
4.7 KiB
Markdown
# Homelab Showcase
|
|
|
|
A public-safe overview of a real multi-host homelab built around segmented networking, self-hosted applications, resilient storage, local AI, offline services, and low-power edge nodes.
|
|
|
|
> This repository is intentionally **not** the operational source of truth. Exact addresses, domains, account names, device identifiers, locations, mount paths, credentials, and raw controller exports are omitted or replaced with examples.
|
|
|
|
## What this lab is designed to do
|
|
|
|
- Keep household services useful during an internet outage
|
|
- Separate trusted devices, servers, IoT, cameras, guests, and lab workloads
|
|
- Centralize applications without making one server responsible for every failure domain
|
|
- Keep bulk storage close to media ingestion and backup workflows
|
|
- Route local AI work to the most appropriate always-on or high-performance host
|
|
- Publish selected services through authenticated tunnels instead of broad inbound exposure
|
|
- Preserve recovery options with encrypted secrets, snapshots, versioned sync, and documented rollback steps
|
|
|
|
## Current architecture
|
|
|
|
| Node | Platform | Primary role |
|
|
|---|---|---|
|
|
| **Application host** | TrueNAS SCALE | Primary application, database, identity, observability, media, and shared AI host |
|
|
| **Storage host** | Storage-focused Linux server | Bulk storage, media-ingestion pipeline, synchronization hub, remote-support relay, and selected CPU services |
|
|
| **Resilience host** | Ubuntu Server | Offline knowledge, resilient local tools, home automation VM, game orchestration, and secondary AI/DNS services |
|
|
| **GPU workstation** | CachyOS workstation | Operator workstation and opportunistic high-performance GPU compute |
|
|
| **Edge node** | Low-power Linux node | Weather dispatch and mesh-radio edge services |
|
|
|
|
See [Architecture](docs/architecture.md) for the data flow and [Services](docs/services.md) for the representative service design by role.
|
|
|
|
## Design highlights
|
|
|
|
- **Segmented UniFi network:** management, trusted clients, servers, IoT, cameras, guests, and quarantine are separate policy lanes.
|
|
- **Authenticated ingress:** selected applications use a tunnel gateway, an internal reverse proxy, and SSO. Most services have no direct internet-facing listener.
|
|
- **Three-node DNS design:** one authoritative configuration source synchronizes to two backup resolvers; public fallback DNS is treated separately from private-zone continuity.
|
|
- **Shared databases:** PostgreSQL, MariaDB, and Redis provide a managed data layer for compatible application stacks.
|
|
- **Split storage and compute:** application compute is concentrated on the primary host while large media/photo datasets stay on the storage server.
|
|
- **Tiered local AI:** an always-on light tier handles routine work; the GPU workstation is optional capacity rather than a hard dependency.
|
|
- **Offline-first node:** documentation, educational content, notes, utilities, and selected models remain available locally.
|
|
- **Encrypted operations:** runtime secrets live outside application repositories and are encrypted before entering version control.
|
|
|
|
## Repository map
|
|
|
|
```text
|
|
docs/
|
|
architecture.md High-level topology and request flows
|
|
networking.md Segmentation and access-control model
|
|
operations.md Deployment, verification, backup, and rollback patterns
|
|
security.md Public/private boundary and secret-handling rules
|
|
services.md Representative service design by host role
|
|
examples/
|
|
compose/ Sanitized Compose and environment examples
|
|
scripts/
|
|
check-public-safety.py
|
|
```
|
|
|
|
## Reusable patterns
|
|
|
|
- [Sanitized Compose example](examples/compose/docker-compose.yml)
|
|
- [Environment template](examples/compose/.env.example)
|
|
- [Public-safety scanner](scripts/check-public-safety.py)
|
|
- [Operational practices](docs/operations.md)
|
|
- [Security model](docs/security.md)
|
|
|
|
## Public-safety policy
|
|
|
|
Every commit is checked with a repository-specific privacy scanner for:
|
|
|
|
- private or management addresses
|
|
- MAC addresses and device identifiers
|
|
- internal domains and personal filesystem paths
|
|
- private-key material, tokens, passwords, and authorization headers
|
|
- real `.env` files and key-bearing file types
|
|
|
|
The detector source is executed and syntax-checked rather than matched against its own regex literals. Binary files are rejected for manual review. Gitleaks separately scans the complete Git history in CI. See [Security](docs/security.md).
|
|
|
|
## Scope
|
|
|
|
This repository demonstrates architecture and operating patterns. It deliberately excludes:
|
|
|
|
- deployable production secrets
|
|
- exact network coordinates
|
|
- raw exports, backups, logs, and incident artifacts
|
|
- household or personal records
|
|
- device serial numbers and persistent client identifiers
|
|
- live tunnel, VPN, DNS, or identity-provider configuration
|
|
|
|
## License
|
|
|
|
MIT — see [LICENSE](LICENSE).
|