Jamie/Homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
108ef2dda82a600041bf3173184aa154c00a67f4
Homelab/README.md

13 KiB
Raw Blame History

Docker Compose Infrastructure Documentation

Overview

This infrastructure manages a comprehensive self-hosted environment including media management (Jellyfin, *arr stack), document management (Paperless-ngx), AI services (Open WebUI, LiteLLM), photo management (Immich), genealogy tools (GrampsWeb), and various utilities.

Architecture

Internal Docker Services

Service Role / Component Web UI Port Notes
Jellyfin Media server with hardware transcoding 8096 -
Jellyseerr Media request management 5055 -
Radarr Movie management 7878 -
Sonarr TV show management 8989 -
Lidarr Music management 8686 -
Bazarr Subtitle management 6767 -
Prowlarr Indexer manager 9696 -
qBittorrent Download client 7070 -
Paperless Document management interface 8100 -
Stirling-PDF PDF manipulation tools 8090 -
OnlyOffice Document collaboration server 8091 -
Open WebUI LLM interface 3000 -
Immich Photo management 2283 -
Syncthing File synchronization 8384 -
Gitea Git service 8418 -
GrampsWeb Jamie Genealogy UI 5511 -
GrampsWeb Helen Genealogy UI 5512 -
Speedtest Tracker Network performance 8180 -
NPM Admin NPM admin UI 81 -
Maloja Music scrobbling 42010 -
Multi-Scrobbler Cross-platform scrobbler 9078 -
WYGIWYH Financial tracking 9008 -
Portainer Container management UI 9443 -
Homepage Service dashboard 7575 -

External Non-Docker Services

Service IP Role / Description Web UI Port Notes
npm (Nginx Proxy Manager) 192.168.0.10 Web UI; admin: 81 80/443 -
adguard 192.168.0.11 DNS/ad-blocking 3000 -
vaultwarden 192.168.0.12 Password manager 80/8080 -
crafty (Crafty Controller) 192.168.0.13 Minecraft server management 3000 -
nextcloud 192.168.0.14 File sync and collaboration 443 -
homeassistant 192.168.0.15 Home automation 8123 -
foundryvtt 192.168.0.16 Foundry VTT 30000 -
openmediavault 192.168.0.17 NAS management 80/443 -
wordpress-irodori 192.168.0.18 WordPress site 80 -
wordpress-dustin 192.168.0.19 WordPress site 80 -

Network Segmentation

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

Service Categories

Management & Infrastructure

  • Glances: System monitoring dashboard
  • Portainer: Container management UI
  • Watchtower: Automatic container updates
  • Homepage: Service dashboard
  • Docker Proxy: Secure Docker socket proxy
  • Nginx Proxy Manager (NPM): Reverse proxy with SSL

Media & Arr Stack

  • Prowlarr: Indexer manager
  • Radarr: Movie management
  • Sonarr: TV show management
  • Lidarr: Music management
  • Bazarr: Subtitle management
  • Jellyseerr: Media request management
  • Jellyfin: Media server with hardware transcoding
  • qBittorrent: Download client
  • Flaresolverr: Cloudflare bypass
  • Slskd: Soulsearch client
  • Soulsync: Music sync automation

Document & AI Suite

  • Paperless-ngx: Document management system
    • MariaDB database
    • Redis broker
    • Tika for text extraction
    • Gotenberg for PDF rendering
  • Paperless-AI: AI-powered document analysis
  • OnlyOffice: Document collaboration server
  • Stirling-PDF: PDF manipulation tools
  • Open WebUI: LLM interface
  • LiteLLM: LLM proxy/gateway with PostgreSQL

Photo & Data Management

  • Immich: Photo management and backup
    • PostgreSQL with vector extensions
    • Redis cache
    • SSD/NAS storage for thumbnails/profiles and full resolution
  • Syncthing: File synchronization (Obsidian vaults)

Development

  • Gitea: Self-hosted Git service with MySQL

Genealogy

  • GrampsWeb: Web interface for genealogy research
    • Two instances: Jamie and Helen family trees
    • Shared Redis broker

Utilities

  • Speedtest Tracker: Network performance monitoring with MariaDB
  • RustDesk: Remote desktop (hbbs + hbbr servers)
  • RedBot: Discord bot
  • iperf3: Network performance testing
  • Newt: Custom application

Finance

  • WYGIWYH: Financial tracking with PostgreSQL

Music & Scrobbling

  • Maloja: Music scrobbling server
  • Multi-Scrobbler: Cross-platform scrobbler

Storage Structure

Local Docker Configs (/docker/)

/docker/
├── Homepage/
├── Arrs/ (Prowlarr, Radarr, Sonarr, Lidarr, Bazarr, Jellyfin, Jellyseerr)
├── qBittorrent/
├── slskd/
├── soulsync/
├── paperless/
├── stirling/
├── immich/
├── obsidian/
├── syncthing/
├── gitea/
├── gramps-jamie/
├── gramps-helen/
├── speedtest-tracker/
├── rustdesk/
├── redbot/
├── maloja/
├── scrobble/
└── litellm/

NAS Storage (/mnt/Nas-Storage/data/)

/mnt/Nas-Storage/data/
├── media/
│   ├── movies/
│   ├── tv/
│   ├── music/
│   └── images/
└── torrents/
    └── soulsync/

Prerequisites

Required Environment Variables (.env file)

# System
PUID=1000
PGID=1000
TZ=Pacific/Auckland

# URLs
JELLYFIN_URL=https://your-jellyfin-domain.com
PAPERLESS_URL=https://your-paperless-domain.com
WYGIWYH_URL=https://your-wygiwyh-domain.com
HOMEPAGE_ALLOWED_HOSTS=your-homepage-domain.com

# Nginx Proxy Manager
NPM_PASSWORD=your_secure_password

# Paperless
PAPERLESS_DB_ROOT_PASSWORD=your_secure_password
PAPERLESS_DB_NAME=paperless
PAPERLESS_DB_USER=paperless
PAPERLESS_DB_PASSWORD=your_secure_password
PAPERLESS_SECRET_KEY=your_secret_key

# Immich
IMMICH_POSTGRES_PASSWORD=your_secure_password

# LiteLLM
GROQ_API_KEY=your_groq_api_key
LITELLM_MASTER_KEY=your_master_key

# Slskd
SLSKD_USERNAME=your_username
SLSKD_PASSWORD=your_secure_password

# Speedtest Tracker
SPEEDTEST_DB_NAME=speedtest
SPEEDTEST_DB_USER=speedtest
SPEEDTEST_DB_PASSWORD=your_secure_password
SPEEDTEST_APP_KEY=base64:your_generated_key

# WYGIWYH
WYGIWYH_DB_DATABASE=wygiwyh
WYGIWYH_DB_USER=wygiwyh
WYGIWYH_DB_PASSWORD=your_secure_password
WYGIWYH_SECRET_KEY=your_secret_key
WYGIWYH_ALLOWED_HOSTS=localhost,127.0.0.1,your-domain.com

# RedBot
REDBOT_TOKEN=your_discord_bot_token

System Requirements

  • Docker Engine 20.10+
  • Docker Compose V2
  • Sufficient storage for media and databases
  • Intel GPU for Jellyfin hardware transcoding (optional)

Installation

  1. Clone/Download this repository
  2. Create required directories 
    # See directory_structure.sh for automated setup
chmod +x directory_structure.sh
./directory_structure.sh
  3. Create .env file 
    cp .env.example .env
# Edit .env with your values
nano .env
  4. Set correct permissions 
    sudo chown -R $PUID:$PGID /docker
sudo chown -R $PUID:$PGID /mnt/Nas-Storage/data
  5. Start services 
    docker compose up -d

Service Access

Default ports (configure reverse proxy for SSL/domains):

  • Homepage: 7575
  • Portainer: 9443
  • Jellyfin: 8096
  • Radarr: 7878
  • Sonarr: 8989
  • Prowlarr: 9696
  • Lidarr: 8686
  • Bazarr: 6767
  • Jellyseerr: 5055
  • qBittorrent: 7070
  • Paperless: 8100
  • Stirling-PDF: 8090
  • OnlyOffice: 8091
  • Open WebUI: 3000
  • Immich: 2283
  • Syncthing: 8384
  • Gitea: 8418
  • GrampsWeb Jamie: 5511
  • GrampsWeb Helen: 5512
  • Speedtest Tracker: 8180
  • NPM Admin: 81
  • Maloja: 42010
  • Multi-Scrobbler: 9078

Maintenance

Backup Strategy

Critical Data to Backup:

  • /docker/ - All service configurations
  • Database volumes (see docker-compose.yaml)
  • .env file (store securely, contains secrets)

Optional (can be regenerated):

  • Media files on NAS
  • Immich thumbnails (can be regenerated)

Updates

Watchtower automatically updates containers daily. To manually update:

docker compose pull

docker compose up -d

Logs

View logs for any service:

docker compose logs -f [service_name]

Resource Limits

  • Portainer: 512MB RAM limit
  • Log rotation: 10MB max, 3 files

Hardware Acceleration

Jellyfin is configured for Intel GPU transcoding:

  • Device: /dev/dri/renderD128
  • Group: 104 (render group)

Verify GPU access:

ls -l /dev/dri/renderD128

Security Considerations

  1. Secrets Management: Store .env securely, never commit to version control
  2. Network Segmentation: Database network is internal-only
  3. Container Security: no-new-privileges:true on supported services
  4. Reverse Proxy: Use NPM for SSL termination and authentication
  5. Updates: Watchtower keeps containers updated

Troubleshooting

Service won't start

docker compose logs [service_name]
docker compose restart [service_name]

Database connection issues

# Check database is healthy
docker compose ps
# Verify network connectivity
docker compose exec [service] ping [db_service]

Permission errors

# Verify ownership
ls -la /docker/[service]/
# Fix if needed
sudo chown -R $PUID:$PGID /docker/[service]/

Storage full

# Check Docker disk usage
docker system df
# Clean up unused resources
docker system prune -a

Internal Docker Services\n\n| Service | Role / Component | Web UI Port | Notes |

|---|---|---:|---| | Jellyfin | Media server with hardware transcoding | 8096 | - | | Jellyseerr | Media request management | 5055 | - | | Radarr | Movie management | 7878 | - | | Sonarr | TV show management | 8989 | - | | Lidarr | Music management | 8686 | - | | Bazarr | Subtitle management | 6767 | - | | Prowlarr | Indexer manager | 9696 | - | | qBittorrent | Download client | 7070 | - | | Paperless | Document management interface | 8100 | - | | Stirling-PDF | PDF manipulation tools | 8090 | - | | OnlyOffice | Document collaboration server | 8091 | - | | Open WebUI | LLM interface | 3000 | - | | Immich | Photo management | 2283 | - | | Syncthing | File synchronization | 8384 | - | | Gitea | Git service | 8418 | - | | GrampsWeb Jamie | Genealogy UI | 5511 | - | | GrampsWeb Helen | Genealogy UI | 5512 | - | | Speedtest Tracker | Network performance | 8180 | - | | NPM Admin | NPM admin UI | 81 | - | | Maloja | Music scrobbling | 42010 | - | | Multi-Scrobbler | Cross-platform scrobbler | 9078 | - | | WYGIWYH | Financial tracking | 9008 | - | | Portainer | Container management UI | 9443 | - | | Homepage | Service dashboard | 7575 | - |

External Non-Docker Services\n\n| Service | IP | Role / Description | Web UI Port | Notes |\n|---|---|---|---:|---|\n| npm (Nginx Proxy Manager) | 192.168.0.10 | Web UI; admin: 81 | 80/443 | - |\n| adguard | 192.168.0.11 | DNS/ad-blocking | 3000 | - |\n| vaultwarden | 192.168.0.12 | Password manager | 80/8080 | - |\n| crafty (Crafty Controller) | 192.168.0.13 | Minecraft server management | 3000 | - |\n| nextcloud | 192.168.0.14 | File sync and collaboration | 443 | - |\n| homeassistant | 192.168.0.15 | Home automation | 8123 | - |\n| foundryvtt | 192.168.0.16 | Foundry VTT | 30000 | - |\n| openmediavault | 192.168.0.17 | NAS management | 80/443 | - |\n| wordpress-irodori | 192.168.0.18 | WordPress site | 80 | - |\n| wordpress-dustin | 192.168.0.19 | WordPress site | 80 | - |\n\nIf you want, I can tighten these with exact ports from your Proxmox/VM configs and add links to each service's docs.\n\n## Migration/Restoration

Your homelab includes a number of LXCs/VMs outside Docker. This section documents their host IPs, brief descriptions, and typical access ports. Verify in your Proxmox/VM configs.

  • npm (Nginx Proxy Manager) — 192.168.0.10 — Web UI and reverse proxy management; typical host ports: 80/443, admin: 81
  • adguard (AdGuard Home) — 192.168.0.11 — DNS/ad-blocking; UI: 3000
  • vaultwarden (Vaultwarden) — 192.168.0.12 — Password manager; UI: 80/8080
  • crafty (Crafty Controller) — 192.168.0.13 — Home automation central
  • nextcloud — 192.168.0.14 — File sync and collaboration; UI: 443
  • homeassistant — 192.168.0.15 — Home automation; UI: 8123
  • foundryvtt — 192.168.0.16 — Foundry VTT; UI: 30000
  • openmediavault (OMV) — 192.168.0.17 — NAS management; UI: 80/443
  • wordpress-irodori — 192.168.0.18 — WordPress site; UI: 80
  • wordpress-dustin — 192.168.0.19 — WordPress site; UI: 80
  1. Install Docker and Docker Compose on new system
  2. Restore /docker/ directory structure
  3. Restore .env file
  4. Restore database volumes
  5. Mount NAS storage at /mnt/Nas-Storage/data/
  6. Run docker compose up -d

Contributing Services

To add new services:

  1. Add service definition to appropriate section
  2. Assign to correct network(s)
  3. Add volume mounts under /docker/[service]/
  4. Update this README with service description
  5. Add required environment variables to .env.example

License

This is a personal infrastructure setup. Adapt as needed for your use case.

Support

For issues with specific services, consult their official documentation:

Last Updated: January 2026

Reference in New Issue View Git Blame Copy Permalink