# 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
- **Glances** - System monitoring dashboard with hardware access
- **Portainer** - Container management UI (port 9443)
- **Watchtower** - Automated container updates (daily polling)
- **Homepage** - Service dashboard (port 7575)

### 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
- **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
- **WYGIWYH** - Financial tracking (port 9008)
  - PostgreSQL database
- **Speedtest Tracker** - Network monitoring (port 8180)
  - MariaDB database, automated testing

### 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)

### 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
- **ByteStash** - File sharing service
- **KitchenOwl** - Recipe management
- **PinchFlat** - Cycling tracking

## 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)
└── Various other service configs
```

## Key Features & Configuration

### Security
- Container security with `no-new-privileges:true`
- Network segmentation (databases internal-only)
- Automated updates via Watchtower
- 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
- **Watchtower** - Daily container updates
- **Backup Script** - Regular data backups
- **Speedtest Tracker** - Automated network testing

### Manual Tasks
- Service monitoring via Glances
- 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
- System metrics via Glances
- 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.