Homelab Infrastructure

The technical documentation for the Flora Family homelab, including UID standards, network layout, and container configurations.

UID/GID Standards

UID/GID Standards

The Flora Family homelab uses a standardized UID/GID mapping system to ensure security, prevent ID collisions, and simplify file permission management across the container infrastructure.

๐Ÿ› ๏ธ Infrastructure Core (System IDs)

These IDs are reserved for the underlying data layers and databases.

๐Ÿ  Family & Admin (50,000 Block)

Reserved for human users and administrative bots.

๐Ÿค– Automated Services (51,000 Block)

Reserved for containerized services and application logic.

UID GID Service Category
51004 61004 Caddy Core Proxy
51010 61010 Paperless Organizational
51020 61020 BookStack Organizational
51052 61052 Immich Media/Photos
51054 61054 n8n Automation
51055 61055 OpenWebUI AI Interface
51100 61100 Minecraft Gaming
51101 61101 Foundry Gaming

๐Ÿ” Security Principles

  1. Non-Root Execution: No containers (except Watchtower & beszel-agent) run as root.
  2. Config Isolation: All docker-compose files in /srv are owned by root:root with 755/644 permissions.
  3. Data Ownership: All volume mounts in /main/appdata are owned by their respective service account.
  4. Least Privilege: env files are restricted to 600 permissions.

Network Architecture

Details on the physical and logical networking, including the opnSense gateway, internal subnets, and reverse proxy configuration.

Network Architecture

LAN Layout & Gateway

LAN Layout & Gateway

๐ŸŒ Internet Edge

๐Ÿ›ก๏ธ Core Routing (Server Closet)

Core Services

๐Ÿ“ก Physical Switching & Wireless

๐Ÿ”’ Security Updates (March 19, 2026)

Network Architecture

Reverse Proxy (Caddy)

Reverse Proxy (Caddy)

Caddy serves as the primary ingress point for all web services in the Flora Family homelab. It handles SSL termination (ACME), local CA management, and request routing.

๐Ÿ—๏ธ Structure

๐Ÿ’พ Log Exporting

๐Ÿ“ Caddyfile Strategy

The Caddyfile is organized into modular sites located in sites-enabled/. This mimics traditional Apache/Nginx structures for clean management.

Common Snippets

  1. security_headers.caddy: Implements HSTS, X-Frame-Options (DENY), and nosniff.
  2. common_tls_internal.caddy: Uses tls internal for services only accessible on the LAN, backed by the local Caddy CA.
  3. common_tls_external.caddy: Standard ACME/Let's Encrypt for public-facing services.

๐Ÿ” Internal CA & Trust

When using tls internal, Caddy acts as its own Certificate Authority.

๐Ÿ”€ Typical Route Block

searxng.flora.family {
    reverse_proxy searxng:8080
    import /etc/caddy/snippets/security_headers.caddy
    import /etc/caddy/snippets/common_tls_internal.caddy
}

Flobot: Transfer to Terra Container

Flobot: Transfer to Terra Container

Overview

Flobot (the OpenClaw AI assistant for the Flora family homelab) transitioned from running on Saturn to running as a containerized service on terra in March 2026.

Migration Details

Architecture on Terra

Capabilities

Flobot now has read/write access to critical homelab services via API tokens, enabling:

Authentication

Terra (Primary Compute)

Deep dive into the main workhorse of the homelab, covering hardware specs, ZFS storage architecture, and container standards.

Terra (Primary Compute)

Hardware & OS

Hardware & OS

Terra is the primary compute node for the Flora Family homelab, designed for high-concurrency tasks like AI processing, media transcoding, and ZFS storage management.

๐Ÿ–ฅ๏ธ Physical Specs

๐ŸŒฌ๏ธ Cooling (Noctua Standards)

Fan Connectivity Map

Sensor Description Connection
fan1 CHA_FAN1 back exhaust fans (2x80mm)
fan2 CPU_FAN bottom CPU fan (1x120mm)
fan3 CHA_FAN2 SDD drive cage fan (1x40mm)
fan4 CHA_FAN3 front intake fans (2x80mm)
fan5 ? Shows 0 rpm
fan6 W_PUMP HBA & NVMe fans (1x40mm + 2x20mm)
fan7 ? Shows 0 rpm
? CPU_OPT top CPU fan (1x120mm)
? AIO_PUMP empty
- - HDD drive cage fan (1x80mm)

๐Ÿ’พ Storage Media

โš™๏ธ OS & Software

Terra (Primary Compute)

ZFS Storage Architecture

ZFS Storage Architecture

Terra utilizes ZFS for primary data storage, leveraging its advanced features for data integrity, snapshots, and caching.

๐ŸŠ Pools

๐Ÿš€ main (SSD Pool)

๐Ÿ˜ bulk (HDD Pool)

๐Ÿ“‚ Key Datasets & Mounts

๐Ÿ›ก๏ธ Health & Maintenance

๐Ÿ” Automated Monitoring (smartd)

Drive health is monitored via smartmontools with automated short and long self-tests configured to email results. Test schedules are staggered to prevent resource contention.

๐Ÿงน ZFS Scrubbing

A scrub is performed automatically on the 3rd Sunday of every month to ensure data integrity and prevent bitrot.

Scrub Schedule (Cron): 24 0 15-21 * * root if [ $(date +\%w) -eq 0 ] && [ -x /usr/lib/zfs-linux/scrub ]; then /usr/lib/zfs-linux/scrub; fi

Terra (Primary Compute)

Container Architecture

Container Architecture

The Flora Family homelab relies on a standardized Docker deployment pattern to ensure security, portability, and ease of management.

๐Ÿ“‚ Directory Layout

To maintain a clean separation between configuration and state, Terra uses two primary directories:

๐Ÿ› ๏ธ Deployment Standards

๐Ÿ” Non-Root Execution

Every service is configured to run as a non-privileged user, with the specific exceptions of Watchtower and Beszel Agent (which require root/host socket access to monitor system health and container status).

Non-root execution is achieved through one of three methods:

  1. Standard user: flag: For images that support it (e.g., user: "51100:61100").
  2. Environment Variables: Many linuxserver.io images use PUID/PGID variables.
  3. Custom Dockerfile Builds: Used for "scratch" images or minimalist images (like OpenWebUI and SearXNG) to manually inject the desired UID/GID and install local CA certificates.

๐Ÿ”— Shared Infrastructure

Common backend services are standardized to simplify inter-container networking and permissions:

๐Ÿ”„ Lifecycle Management

Terra (Primary Compute)

Performance & Stability Optimizations

Performance & Stability Optimizations

This page documents the specific kernel and hardware tweaks applied to Terra (Ryzen 5950X / Ubuntu 24.04) to optimize for container performance, storage throughput, and long-term stability.

๐Ÿ›ก๏ธ Stability & Power Management (The "Golden Config")

Typical Current Idle (UEFI)

Processor C-State Limit (Kernel)

65W Eco Mode (Manual PBO)

โšก CPU & Power Performance

AMD P-State (Active Mode)

IRQ Balancing

๐Ÿง  Memory Tuning

Speed & Stability

Static Hugepages

๐Ÿ’พ I/O & Network Tuning (sysctl)

ZFS Write Buffering

Fluent-bit Batching (ClickHouse)

๐ŸŽฎ GPU Optimization (Quadro P2200)

Persistence Mode

Terra (Primary Compute)

Luna (Backup Server)

Luna (Backup Server)

Luna is the secondary compute and backup node for the Flora Family homelab. It serves as the primary replication target for Terra.

๐Ÿ–ฅ๏ธ System Status

๐Ÿ’พ Storage Architecture (ZFS)

๐ŸŒก๏ธ Monitoring

โš™๏ธ Software & Management

๐Ÿ› ๏ธ Recovery Notes (Feb 2026)

SMB & Time Machine

SMB & Time Machine Services

Our network file sharing (SMB) is central to the Flora Family homelab, providing shared access for group projects, personal file storage, and macOS backups via Time Machine. This configuration is managed at /etc/samba/smb.conf.

Global Configuration

macOS Optimization (vfs_fruit)

Sharing files with Macs is optimized using the fruit VFS module. This allows Samba to behave like a native Mac server, supporting resource forks, extended attributes, and Finder specific icons (modeled as MacSamba).

Available Shares

General Purpose Shares

Personal Shares

Time Machine

Configuring macOS for Time Machine

To use the timemachine share as a backup target for a Mac, follow these steps:

1. Connect to the Share

  1. Open Finder.
  2. In the menu bar, select Go > Connect to Server... (or press Cmd+K).
  3. Enter the server address: smb://terra.flora.family/timemachine
  4. Click Connect and authenticate using your JumpCloud credentials.

2. Select the Backup Disk

  1. Open System Settings (or System Preferences) on your Mac.
  2. Navigate to General > Time Machine.
  3. Click Add Backup Disk... (or Select Disk...).
  4. Select the timemachine network share from the list.
  5. When prompted, choose to use your existing JumpCloud credentials to allow Time Machine to connect automatically in the future.

Tip: Initial backups can be large. It is recommended to perform the first backup while connected via Ethernet.

Source Reference: The primary configuration for these services can be found on the server at /etc/samba/smb.conf.

AI-Powered Log Aggregation (ClickHouse + Ollama)

AI-Powered Log Aggregation with ClickHouse & Ollama

This page documents the minimalist log aggregation and AI search pipeline built for the Flora family homelab (terra + opnsense).

Architecture

ClickHouse Table Schema

CREATE TABLE system_logs (
    timestamp DateTime64(3),
    host String,
    unit String,
    message String,
    priority Int8,
    log_id String,
    embedding Array(Float32),
    INDEX ann_idx embedding TYPE vector_similarity('hnsw', 'cosineDistance', 768) GRANULARITY 1
) ENGINE = ReplacingMergeTree()
ORDER BY (log_id);

Components

1. Fluent Bit (Ingestion)

Fluent Bit reads the systemd journal and ships logs to ClickHouse via HTTP. Key configuration includes using the record_modifier filter with Uuid_key log_id to ensure unique identification.

2. Log Brain (Embedding Loop)

A Python background service (log-brain.service) runs an embedding loop:

  1. Queries logs where length(embedding) = 0 using FINAL to handle merging.
  2. Sends the message to Ollama for embedding.
  3. Upserts the record back to ClickHouse with the vector.

3. Reverse Proxy

Caddy provides internal TLS for both Ollama (ollama.flora.family) and ClickHouse (logs.flora.family).

Search Examples

I (Flobot) can now search logs using standard SQL for keywords or cosineDistance for semantic similarity.

ClickHouse Log Aggregation

ClickHouse Log Aggregation & Investigation

Architecture Overview

Log Pipeline (Migrated to Vector - Feb 2026):

ClickHouse Access

Table Schema

CREATE TABLE default.system_logs (
  timestamp DateTime64(3),
  host String,
  unit String,
  message String,
  priority Int8,
  log_id String,
  embedding Array(Float32),  -- 768-dim vectors
  source String DEFAULT 'systemd'
)
ENGINE = ReplacingMergeTree
ORDER BY log_id

Log Sources

Vector Migration (Feb 2026)

Noise Management & Filtering

Embedding Pipeline

Performance (Feb 2026):

Key Learnings

  1. Timezone consistency is critical: Migrating from UTC to local time in the pipeline saves massive mental overhead during investigations.
  2. Priority Intelligence: Mapping systemd priorities (0-7) into the database allows for instant "Error-only" dashboards.
  3. Recursive logging is a DDoS: Always filter your log-aggregator's own logs out of the stream.
  4. ReplacingMergeTree quirk: Must insert complete rows (all columns) for deduplication to work.

Future Work

Shell Standards & QoL

Shell Standards & QoL

This page documents the standardized shell environment applied across the Flora Family infrastructure via Ansible.

๐Ÿ› ๏ธ Ansible Management

๐Ÿš ZSH Configuration

๐ŸŽจ Dynamic Theme Detection

Standardized the term_theme_detect function in linux_specific.zsh.

๐Ÿณ Docker Shortcuts

๐Ÿ–ฅ๏ธ Terminal Standards

AI Conference Technical Notes (2026-03-24)

AI Conference Technical Notes (2026-03-24)

Architecture Overview

Deep-dive notes from the 2026 All Things AI conference sessions centered on robust, production-grade agentic systems.

1. Pydantic AI & Logfire (Observability Stack)

Pydantic AI is the standard for type-safe agentic architectures. Integration with Logfire creates Context Graphs, turning logging into a primary observability tool. This allows for clear visualization of agent decision-making traces.

2. Three-Tiered Memory Architecture

A move away from LLM-centric memory management towards a structured, verifiable storage system:

3. The "Smart Gateway" Philosophy

4. Knowledge & Context Graphs

5. Prototyping

Marimo identified as a preferred "reactive" alternative to traditional cell-based Jupyter flows for executable rapid prototyping.

6. Hypothetical Document Embedding (HyDE)

A high-accuracy retrieval pattern: instead of embedding the user's question, the system generates a "fake answer" via the LLM, embeds that, and searches the document store using "answer-to-answer" matching.

7. The Three Laws of Agentic AI

Reframing security as "Rules of Conduct" for autonomous agents:

Implementation Strategy (Homelab):