portainer-core

Self-hosted home server infrastructure with GPU-accelerated ML, media streaming, and secure remote access

Main Dashboard: https://home.schweitz.net (Tatlock UI)

Quick Links

Documentation

• Container Reference - All services, ports, configuration
• Changelog - Version history
• Agent Guidelines - For LLM coding agents

Guides

• GPU Docker Configuration
• Headscale VPN Setup
• Connect Devices to VPN
• Code-Server Setup
• NPM Logging

Architecture Overview

┌─────────────────────────────────────────┐
│  Infrastructure Layer                   │
│  ├── Portainer (8080) - Container mgmt │
│  ├── PostgreSQL Shared (5432) - DB     │
│  ├── Redis Shared (6379) - Cache       │
│  ├── NPM (8000) - Reverse proxy        │
│  └── Ollama (11434) - ML models [GPU]  │
├─────────────────────────────────────────┤
│  Networking Layer                       │
│  ├── docker-dataplane - Service mesh   │
│  └── Headscale (8085) - VPN mesh       │
├─────────────────────────────────────────┤
│  Dashboard Layer                        │
│  └── Tatlock UI (9999) - Dashboard     │
├─────────────────────────────────────────┤
│  Optimization Layer                     │
│  ├── Watchtower - Auto-updates         │
│  └── Maintenance - Automated backups   │
├─────────────────────────────────────────┤
│  Application Layer                      │
│  ├── Open WebUI (8081) - LLM chat UI   │
│  ├── Core API (8083) - Infra mgmt      │
│  ├── Jellyfin (8096) - Media [GPU]     │
│  ├── Nextcloud (8082) - Cloud storage  │
│  ├── Gitea (3002) - Git hosting        │
│  └── Samba (445) - File shares         │
└─────────────────────────────────────────┘

Project Structure

portainer-core/
├── plans/                  # Implementation plans
│   ├── active/            # Current development work
│   └── completed/         # Historical implementations
├── docs/                  # Documentation
│   ├── architecture/      # Design documents
│   ├── guides/            # Setup and operational guides
│   ├── services/          # Service-specific documentation
│   └── reference/         # Quick reference materials
├── stacks/                # Docker Compose files (version-controlled)
├── scripts/               # Maintenance automation
├── services/              # Service source code
│   ├── core-api/         # Infrastructure management API
│   └── ...
├── AGENTS.md             # AI agent guidelines (single source of truth)
├── README.md             # This file (documentation index)
├── PLANS.md              # Implementation plan tracker
├── STATUS.md             # Current phase tracking
└── CHANGELOG.md          # Version history

Common Commands

Infrastructure Management

make status              # Show running containers and system status
make health              # Comprehensive health check
make gpu-check           # Verify GPU passthrough
make disk                # Disk usage report
make backup              # Backup Docker configs
make cleanup             # Clean unused Docker resources

Stack Management

make deploy-portainer    # Deploy Portainer
make deploy-ollama       # Deploy Ollama
make logs-ollama         # View Ollama logs
make update-jellyfin     # Update Jellyfin to latest
make stop-nextcloud      # Stop Nextcloud stack

See Stacks Reference for complete stack inventory and deployment procedures.

Development Setup

Python Environment

Some automation scripts require Python dependencies:

# Activate virtual environment
source .venv/bin/activate

# Install/update dependencies
pip install -r requirements.txt

# Deactivate when done
deactivate

Service Development

See External Services for services maintained in separate repositories.

Service Ports Reference

Service	Port	Description
Portainer	8080	Container management UI
Nginx Proxy Manager	8000	Reverse proxy admin
Open WebUI	8081	LLM chat interface
Nextcloud	8082	Cloud storage
Core API	8083	Infrastructure management API
Tatlock UI	9999	Home lab dashboard
Headscale	8085	VPN control server
Jellyfin	8096	Media streaming
Gitea	3002	Git repository hosting
Gitea SSH	2222	Git SSH access
PostgreSQL Shared	5432	Shared database (internal)
Redis Shared	6379	Shared cache (internal)
Qdrant	6333, 6334	Vector database
Ollama	11434	ML model API
See Stacks Reference for complete port allocation.

GPU Services

Two services leverage the RTX 2080 Ti:

1. Ollama - ML model inference (3B-13B parameter models)
2. Jellyfin - Hardware video transcoding (NVENC)

See GPU Docker Configuration for setup.

Storage Strategy

SSD (Performance): /home/jpmschweitzer/docker-data/

• Docker configs, databases, cache, container images

HDD (Capacity): /mnt/media/

• Media files, user data, backups

See Stacks Reference for details.

Current Phase

Phase 2 of AI Orchestrator Enhancement (Memory Systems) 🔄 In Progress

See STATUS.md for detailed progress tracking.

Contributing

This is a personal infrastructure project. For AI agents:

• Read AGENTS.md first - Mandatory guidelines
• Follow conventional commit format
• Test GPU access before deploying GPU services
• Update STATUS.md when completing phases

Resources

• Portainer Documentation
• Ollama
• Headscale
• Jellyfin
• Nextcloud

---

Version: 0.7.1 Last Updated: 2025-11-20 System: tower-of-joy