homelab-showcase/docs/services.md

Representative Service Architecture

This page is a deliberately generalized snapshot of the lab's service design, informed by read-only host, container, storage, and service inspection on 2026-09-08. It is not a complete production inventory. Exact products are included only when they illustrate a reusable pattern; precise placement, versions, counts, ports, addresses, domains, and runtime identifiers remain private.

Primary application host

The primary host concentrates the shared application plane:

• storage-aware container runtime
• internal reverse proxy and authenticated tunnel connector
• identity and SSO
• shared PostgreSQL, MariaDB, and Redis data services
• source hosting and container administration
• household productivity, document, photo, and media front ends
• monitoring, metrics, logs, dashboards, uptime checks, and notifications
• workflow automation
• always-on local model serving, model routing, vector search, and metasearch

Representative technologies include TrueNAS SCALE, Docker, Traefik, Authentik, PostgreSQL, Redis, Prometheus, Grafana, Ollama, and LiteLLM.

Large datasets are mounted from the storage host rather than duplicated into container-local volumes.

Storage and ingestion host

The storage host keeps capacity-heavy and data-local workloads together:

• ZFS-backed bulk datasets
• snapshots and backup targets
• media acquisition, organization, and post-processing
• file synchronization
• private remote-support rendezvous and relay
• a secondary DNS resolver
• selected CPU-only inference utilities
• host and container monitoring

Representative technologies include Unraid, ZFS, the common media-automation ecosystem, Syncthing, RustDesk, Technitium DNS, and Netdata.

Offline and resilience host

The resilience host stays useful when the primary application host or WAN is unavailable:

• offline reference and educational libraries
• local notes and browser utilities
• local model and vector services
• household helper and agent services
• CPU speech-to-text
• Home Assistant in a dedicated virtual machine
• game-server management
• mesh-radio observation
• a secondary DNS resolver
• trusted local file intake

Representative technologies include Ubuntu Server, KVM, Home Assistant OS, Kiwix, Kolibri, Ollama, Qdrant, and Docker.

Managed appliance workloads on this host are excluded from broad cleanup automation and maintained through their own control plane.

GPU operator workstation

The workstation provides optional accelerated capacity and daily operator tooling:

• high-performance local model inference
• accelerated speech-to-text and other GPU jobs
• container runtime
• printing
• private-overlay access
• file synchronization
• 3D-printing and slicing applications

The workstation is opportunistic capacity. Routine background services must continue when it sleeps or is offline.

Low-power edge node

A small independent Linux node handles hardware-adjacent, always-on functions:

• weather collection and dispatch
• mesh-radio and repeater support
• wired placement on a server-oriented network segment
• upstream reporting without joining the primary application failure domain

Placement rules

1. Shared applications and databases prefer the primary application host.
2. Large data and ingestion stay close to bulk storage.
3. Offline knowledge and resilience services remain independent of the primary host.
4. Heavy GPU work may use the workstation, but routine automation cannot require it.
5. Hardware-adjacent radio and weather services stay on low-power edge nodes.
6. DNS, file synchronization, and remote support span hosts to reduce single points of failure.
7. The complete service inventory, operational exceptions, and incident state remain in the private source-of-truth repository.