# Infrastructure

This document describes the Docker-based infrastructure and network architecture for the home lab environment.

## Overview

The infrastructure consists of 56+ containerized services running across multiple hosts, with centralized reverse proxy and authentication.

## Network Architecture

### Primary Hosts

* **192.168.1.251** - **NAZ-Tee** - Infrastructure host (Portainer, DNS Watchtower, Synology DSM)
* **192.168.1.252** - **Ali3n** - Primary application host (majority of services)
* **192.168.1.244** - Home Assistant host
* **192.168.12.3** - Secondary application host (matrix, firefly, node-red, traefik host)
* **192.168.1.198** - UniFi Controller

### External Networks

* `traefik_proxy` - External Docker network for SSL/TLS termination via Traefik

## Reverse Proxy & SSL - runs on 192.168.12.3

### Traefik Configuration

Traefik runs as the central reverse proxy, providing:

* Automatic HTTPS via Let's Encrypt (`certResolver: default`)
* Two entry points:
  * `web` (HTTP) - redirects to HTTPS
  * `web-secure` (HTTPS)
* Configuration file: `~/dyno.yml`

### Domain Strategy

Services are accessible via two primary domains:

* **fails.me** - Primary domain
* **3ddbrewery.com** - Secondary domain

Most services support both domains with separate router configurations.

## Authentication

### Authelia Integration

Two Authelia middleware configurations provide SSO:

* `authelia-fails` - For *.fails.me domains
  * Forward auth address: `http://authelia:9091/api/verify?rd=https://auth.fails.me`
* `authelia-brewery` - For *.3ddbrewery.com domains
  * Forward auth address: `http://authelia:9091/api/verify?rd=https://auth.3ddbrewery.com`

### Service Authentication Patterns

Services follow three authentication patterns:

1. **Split by domain with auth** - Most services (Sonarr, Radarr, Books, SilverBullet, etc.)
   * Web UI requires Authelia authentication
   * API endpoints (`/api`) bypass authentication for automation
2. **No authentication** - Public or self-authenticating services (Bookmarks, Finance, ZNC, Immich, Navidrome)
3. **Hybrid authentication** - Services with special endpoints (Audiobookshelf with `/audiobookshelf/feed`, NZB with `/xmlrpc`)

## Service Categories

### Media Management (Arr Stack)

* **Sonarr** (192.168.1.252:8989) - TV shows at sonarr.* domains
* **Radarr** (192.168.1.252:7878) - Movies at radarr.*/movies.* domains
* **Lidarr** (192.168.1.252:8686) - Music at lidarr.* domains
* **Readarr** (192.168.1.252:8787) - Books at readarr.* domains
* **Prowlarr** (192.168.1.252:9696) - Indexer management at prowlarr.* domains
* **Bazarr** (192.168.1.252:6767) - Subtitles at bazarr.* domains

### Media Servers

* **Emby** (192.168.1.252:8096) - Media server at m.*/tv.* domains
* **Audiobookshelf** (192.168.1.252:13378) - Audiobooks/podcasts at podcasts.*/audiobookshelf.* domains
* **Navidrome** (192.168.1.252:4533) - Music streaming at music.* domains
* **Channels DVR** (192.168.1.252:8089) - Live TV at dvr.*/channels-dvr.* domains

### Custom Applications

* **Books V2** - Book library manager
  * Frontend (192.168.1.252:3000) at books.* domains
  * API (192.168.1.252:48000) at api.books.* domains
  * Stack: React + TypeScript + FastAPI + MySQL
* **SpeedRacer** - Running tracker at running.*/run.* domains
  * Frontend (192.168.1.252:5173)
  * API (192.168.1.252:6883) at /api path
  * Stack: React + TypeScript + FastAPI
* **Store Matching** (192.168.1.252:45580) - Store list matching at stores.* domains
  * Stack: React + Express + MySQL

### Infrastructure Services

* **Traefik** (192.168.12.3) - Reverse proxy and SSL termination
* **Authelia** - SSO authentication provider
* **Portainer** (192.168.1.251:9000) - Container management at portainer.*/docker.* domains
* **Watchtower** - Automatic container updates
* **Homepage** (192.168.1.252:3305) - Dashboard at h.* domains
* **ArchiveForge** (192.168.1.252:8766) - Automated Docker backup system at archiveforge.* domains

### Databases

*   **Immich Postgres**
*   **n8n Postgres**
*   **Mealie Postgres**
*   **External MariaDB** (192.168.1.251) - Used by Books V2 and Store Matching

### Productivity & Automation

* **n8n** (192.168.1.252:5678) - Workflow automation at n8n.* domains
* **Node-RED** - Multiple instances:
  * Main (192.168.1.252:1880) at node-red.* domains
  * HASS (192.168.1.244:1880) at nr.* domains (HTTPS with custom transport)
  * HET (192.168.12.3:1880) at nr-het.*/node-het.* domains
* **Mealie** (192.168.1.252:9925) - Recipe management at food.* domains
* **Immich** (192.168.1.252:2283) - Photo management at photos.* domains
* **SilverBullet** (192.168.1.252:53510) - Markdown-based knowledge management at sb.* domains
  * Stack: SilverBullet (ghcr.io/silverbulletmd/silverbullet)
  * Features: WYSIWYG markdown editor, wiki-style linking, Lua scripting, plugin system
  * Authentication: Authelia SSO for both domains
* **Karakeep** - Karaoke library management

### Monitoring & Management

* **Uptime Kuma** (192.168.1.251:3444) - Uptime monitoring at uptime.* domains
* **Beszel** (192.168.1.252:31090) - System monitoring at mon.* domains
* **Watchstate** (192.168.1.252:8585) - Media watch state sync at watchstate.* domains

### Development Tools

* **PhpMyAdmin** (192.168.1.252:2500) - MySQL management at php.*/phpmyadmin.* domains
* **PhpPgAdmin** (192.168.1.252:5183) - PostgreSQL management at phppgadmin.* domains
* **Cyberchef** (192.168.1.252:7318) - Data transformation at cyberchef.* domains
* **Webcheck** (192.168.1.252:6160) - Website analysis at webcheck.* domains

### Communications

* **ZNC** (192.168.1.251:6501 HTTPS) - IRC bouncer at znc.*/irc.* domains
* **Glowing Bear** (192.168.1.252:28280) - WeeChat web client at glow.*/chat.* domains
* **WeeChat Relay** (192.168.1.252:29001) - WeeChat relay at weechat.* domains
* **NTFY** (192.168.1.252:6741) - Notification service at notify.fails.me/ntfy.3ddbrewery.com

### Other Services

* **Home Assistant** (192.168.1.244:8123 HTTPS) - Home automation at home.* domains
* **UniFi Controller** (192.168.1.198:8443 HTTPS) - Network management at unifi.* domains
* **Calibre** (192.168.1.252:28080) - Library management (VNC) at library-vnc.* domains
* **Calibre Web** (192.168.1.252:28083) - Web reader at library.* domains
* **Jellyseerr** (192.168.1.252:5055) - Media requests at requests.* domains
* **Autoscan** (192.168.1.252:3030) - Media library scanning at autoscan.* domains
* **Subgen** (192.168.1.252:3900) - Subtitle generation at subgen.* domains

## Special Configurations

### HTTPS Backend Services

Services with HTTPS backends use `serversTransport: mytransport` with `insecureSkipVerify: true`:

* ZNC (192.168.1.251:6501)
* Home Assistant (192.168.1.244:8123)
* Node-RED HASS (192.168.1.244:1880)
* ruTorrent (192.168.1.252:38443)
* UniFi (192.168.1.198:8443)
* DSM (192.168.1.251:5001)

### Custom Middleware

* **dvr-headers** + **dvr-buffers** - Special handling for Channels DVR streaming
* **weechat-websocket** - WebSocket support for WeeChat
* **enable-websocket** - WebSocket headers for NTFY
* **run-api-strip** - Strip `/api/vi` prefix for SpeedRacer API

### Host Header Handling

Most services use `passHostHeader: false` to prevent host header issues. Exceptions:

* ZNC - `passHostHeader: true`
* Home Assistant - `passHostHeader: true`
* Glowing Bear - `passHostHeader: true`

## Data Storage

Application data is stored at `/mnt/docker-storage/appdata/[service-name]` with each service directory containing:

* `docker-compose.yml` - Service definition
* Service-specific configuration and data directories
* Optional service-specific `CLAUDE.md` documentation

### Volume Mount Patterns

*   **Absolute host paths**: Most common, e.g., `/home/maddox/docker/appdata/[service]/:/config`
*   **Named volumes**: Used by select services like Budibase and Immich.
*   **Shared media volumes**:
    *   `/volume1/Media` - Main media content
    *   `/volume1/docker/backup` - Off-box backup storage (NAS at 192.168.1.251)

## Backup Strategy

An automated backup solution, **ArchiveForge**, is in place to protect container data.

*   **What is backed up**: The entire `/mnt/docker-storage/appdata` directory.
*   **How it works**: ArchiveForge runs nightly, automatically stopping database containers for data consistency before creating compressed `tar.gz` archives.
*   **Backup Target**: Backups are stored on an off-box NAS at `192.168.1.251` in the `/volume1/docker/backup/ArchiveForge` directory.
*   **Retention Policy**:
    *   5 daily backups
    *   4 weekly backups
    *   6 monthly backups

## Common Operations

### Service Management

```bash
cd /mnt/docker-storage/appdata/[service-name]
docker-compose up -d          # Start service
docker-compose down           # Stop service
docker-compose restart        # Restart service
docker-compose logs -f        # View logs
```

### Traefik Configuration

Configuration file: on IM `/matrix/traefik/config/dyno.yml`

After changes:
1. Validate syntax
2. Restart Traefik to apply changes
3. Check logs for errors

### Container Lists

* `/mnt/docker-storage/appdata/all_containers.txt` - All running containers
* `/mnt/docker-storage/appdata/traefik_containers.txt` - Traefik-proxied containers

## Security

* All external traffic uses HTTPS with automatic Let's Encrypt certificates
* Sensitive admin interfaces protected by Authelia SSO
* API endpoints strategically exposed for automation while protecting web UIs
* Services use dedicated Docker networks for isolation
* Container updates managed by Watchtower with per-service opt-in/opt-out