Homelab/AGENTS.md

AGENTS - Docker Infrastructure Documentation

Overview

This document provides a comprehensive overview of the Docker infrastructure managed in /docker/. This self-hosted ecosystem contains 30+ services organized into functional categories, all integrated through a reverse proxy and secured with proper network segmentation.

Core Infrastructure Agents

Management & Monitoring

• Portainer - Container management UI (port 9443)
• Homepage - Service dashboard (port 7575)
• WUD (WhatsUpDocker) - Docker image management utility

Reverse Proxy & Security

• Nginx Proxy Manager - SSL termination and reverse proxy (ports 80, 443, 81)
• Docker Socket Proxy - Secure Docker API access (port 2375)

Media & Entertainment Stack

Media Server

• Jellyfin - Media server with hardware transcoding (port 8096)
  • Intel GPU acceleration via render device
  • NAS storage integration

Download & Index Management

• qBittorrent - Torrent client (ports 56881, 7070)
• Prowlarr - Indexer manager (port 9696)
• FlareSolverr - Cloudflare bypass service (port 8191)

Content Management

• Radarr - Movie management (port 7878)
• Sonarr - TV show management (port 8989)
• Lidarr - Music management (port 8686)
• Bazarr - Subtitle management (port 6767)
• Jellyseerr - Media request system (port 5055)

File Sharing

• Slskd - Soulseek file sharing client (ports 5030, 5031, 50300)

Document & Data Management

Document Processing

• Paperless-ngx - Document management (port 8100)
  • MariaDB database, Redis broker, Tika text extraction, Gotenberg PDF processing
• Paperless-AI - AI-powered document processing for Paperless-ngx
• Stirling-PDF - PDF manipulation tools (port 8090)
• OnlyOffice - Document collaboration (port 8091)

Photo Management

• Immich - AI-powered photo management (port 2283)
  • PostgreSQL with vector search, Redis cache
  • Local SSD storage for config and thumbs

File Synchronization

• Syncthing - File synchronization (ports 21027, 22000, 8384)
  • Obsidian vault synchronization
  • Multiple shared folders

AI & Development Services

AI Infrastructure

• Open WebUI - LLM interface (port 3000)
• LiteLLM - AI gateway (port 4000)
  • PostgreSQL database for configuration
  • Supports multiple AI providers

Development Tools

• Gitea - Git service (ports 222, 8418)
  • MySQL database
• Newt - AI service integration

Genealogy & Personal Tools

Family History

• GrampsWeb Jamie - Genealogy UI (port 5511)
• GrampsWeb Helen - Genealogy UI (port 5512)
  • Shared Redis broker
  • Separate trees for different family branches

Finance & Tracking

• Speedtest Tracker - Network monitoring (port 8180)
  • MariaDB database, automated testing

Personal Tools

• Tandoor Recipes - Self-hosted recipe management
• Surmai - Personal flight tracking tool

Music & Scrobbling

• Maloja - Music scrobbling service (port 42010)
• Multi-Scrobbler - Cross-platform scrobbling (port 9078)
  • Integrates with Jellyfin and Last.fm

Utilities & External Services

Remote Access

• RustDesk - Remote desktop (host mode)

Network Tools

• iperf3-server - Network performance testing (port 5201)
• ntopng - Network traffic monitoring tool (port 3939)

Browser Workspace

• Kasm - Browser isolation workspace (containerized browsing)

Game Servers

• Foundry Watcher - Foundry VTT player monitoring service
  • SSH log tailing from Foundry server
  • REST API for player status (port 30001)
  • MQTT integration for connection events

ROM Management

• Retrom - ROM library management service
  • retrom: Main ROM service container (port 5111)
  • retrom-db: PostgreSQL database for Retrom
  • retrom-adminer: Adminer interface for database management (port 8080)
  • retrom-jaeger: Distributed tracing for performance monitoring

Home Automation

• Neolink - Reolink camera bridge for Frigate/Home Assistant integration

Discord Bot (OpenCode)

• Service: Discord Agent Bot
• Role: AI-powered Discord bot using Ollama LLM
• Container: discord-agent
• Network: internal_net, db_net
• Configuration: /docker/discord-agent/config/agent-config.yaml
• Data: /docker/discord-agent/data/
• LLM: Ollama (ministral-3:8b) at http://192.168.0.31:11434
• Features: Discord commands, service integrations, AI chat capabilities
• Database: MySQL for conversation persistence
• Cogs: Modular architecture with base_cog and integration_cog

RedBot

• Service: RedBot Discord Bot
• Role: Alternative Discord bot with custom cogs
• Container: redbot
• Network: web_net

Other Tools

• Newt - AI service integration

Network Architecture

Docker Networks

• media_net - Media services and *arr stack
• db_net - Database services (internal only)
• web_net - Web-accessible services
• internal_net - Internal service communication

Storage Structure

/docker/
├── Arrs/ (Media stack: Prowlarr, Radarr, Sonarr, Lidarr, Bazarr, Jellyfin, Jellyseerr)
├── immich/ (Photo management)
├── paperless/ (Document management)
├── litellm/ (AI gateway)
├── discord-agent/ (Discord bot with Ollama LLM integration)
├── gitea/ (Git service)
├── gramps-jamie/ (Genealogy)
├── gramps-helen/ (Genealogy)
├── npm/ (Nginx Proxy Manager)
├── qBittorrent/ (Download client)
├── slskd/ (Soulseek client)
├── speedtest-tracker/ (Network monitoring)
├── maloja/ (Music scrobbling)
├── scrobble/ (Multi-scrobbler)
├── syncthing/ (File sync)
├── Homepage/ (Dashboard)
├── retrom/ (ROM library management)
├── wud/ (Docker image management)
├── ntopng/ (Network traffic monitoring)
├── kasm/ (Browser workspace)
├── neolink/ (Reolink camera bridge)
├── surmai/ (Flight tracking)
├── tandoor/ (Recipe management)
├── foundry-watcher/ (Foundry VTT monitoring)
└── Various other service configs

Key Features & Configuration

Security

• Container security with no-new-privileges:true
• Network segmentation (databases internal-only)
• Reverse proxy with SSL termination

Performance

• Intel GPU hardware acceleration for Jellyfin
• Log rotation (10MB max, 3 files)
• Resource limits (Portainer: 512MB RAM)

Data Management

• Comprehensive backup script included
• Separate volumes for critical data
• NAS storage integration for media files

Environment

• System configured for Pacific/Auckland timezone
• PUID/PGID for proper file permissions
• Extensive environment variable configuration

Service Dependencies

Database Services

• MariaDB instances for media stack, tracking, and document services
• PostgreSQL for AI services, photo management, and finance
• Redis for caching and message brokering

Network Dependencies

• All web services route through Nginx Proxy Manager
• Internal services communicate via internal_net
• Media services isolated on media_net
• Database services on internal-only db_net

Maintenance Agents

Automated Tasks

• Backup Script - Regular data backups
• Speedtest Tracker - Automated network testing

Manual Tasks

• Service monitoring via Portainer
• Container management via Portainer
• Service configuration via Nginx Proxy Manager

Development & Debugging

Service Access

• Web Services: Access through reverse proxy (80/443)
• Admin Interfaces: Direct ports for management (e.g., 9443, 7575)
• Internal Services: Host-only access for security

Troubleshooting

• Container logs accessible via Portainer
• Network diagnostics via iperf3-server

This Docker infrastructure represents a comprehensive self-hosted ecosystem covering media management, document processing, AI services, development tools, and personal productivity applications, all integrated through a reverse proxy and organized with proper network segmentation.