# 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).