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 for the data flow and Services 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

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

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.

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.

4.7 KiB Raw Permalink Blame History