# portainer-core

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

**Main Dashboard:** https://home.schweitz.net (Organizr)

## Quick Links

### Getting Started
- [System Specifications](docs/reference/SYSTEM.md) - Hardware and software details
- [Container Reference](docs/reference/CONTAINERS.md) - All deployed services
- [Current Status](STATUS.md) - Implementation progress and phase tracking

### Implementation Plans
- [Implementation Plans](PLANS.md) - Master plan tracker
- [Active Plans](plans/active/) - Current development work
- [Completed Plans](plans/completed/) - Historical implementations

### Documentation Index

#### Architecture & Design
- [Shared Infrastructure Architecture](docs/architecture/SHARED_INFRASTRUCTURE_ARCHITECTURE.md) - PostgreSQL/Redis shared infrastructure

#### Operational Guides
- [Backup Procedures](docs/guides/backup-procedures.md) - Backup strategies and procedures
- [Code-Server Setup](docs/guides/code-server-setup.md) - Browser-based IDE configuration
- [Connect Devices Guide](docs/guides/connect-devices-guide.md) - Headscale VPN setup
- [GPU Docker Configuration](docs/guides/gpu-docker-config.md) - NVIDIA GPU passthrough
- [Headscale Setup](docs/guides/headscale-setup.md) - Mesh VPN deployment
- [NPM Logging Guide](docs/guides/npm-logging-guide.md) - Nginx Proxy Manager logging

#### Services
- [Core API](docs/services/core-api.md) - Infrastructure management and AI orchestration
- [Organizr Widgets](docs/services/organizr-widgets.md) - Service control dashboard

#### Reference
- [Stacks Reference](docs/reference/stacks.md) - All Docker Compose stacks
- [Scripts Reference](docs/reference/scripts.md) - Maintenance automation
- [Automation Reference](docs/reference/AUTOMATION.md) - Portainer REST API usage
- [Container Reference](docs/reference/CONTAINERS.md) - Complete container profiles
- [System Reference](docs/reference/SYSTEM.md) - Hardware specifications
- [Changelog](CHANGELOG.md) - Version history

### For AI Agents
- [Agent Guidelines](AGENTS.md) - **REQUIRED READING** for all LLM coding agents

## 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       │
├─────────────────────────────────────────┤
│  Monitoring Layer                       │
│  ├── Uptime Kuma (3001) - Uptime       │
│  ├── Netdata (19999) - Metrics         │
│  └── Organizr (8084) - 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
│   └── ...
├── organizr-widgets/      # Dashboard widgets
├── 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
```bash
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
```bash
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](docs/reference/stacks.md) for complete stack inventory and deployment procedures.

## Development Setup

### Python Environment

Some automation scripts require Python dependencies:

```bash
# Activate virtual environment
source .venv/bin/activate

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

# Deactivate when done
deactivate
```

### Service Development

See individual service documentation:
- [Core API Development](docs/services/core-api.md#development)

## 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 |
| **Organizr** | 8084 | Unified dashboard |
| **Headscale** | 8085 | VPN control server |
| **Jellyfin** | 8096 | Media streaming |
| **Uptime Kuma** | 3001 | Service monitoring |
| **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 |
| **Netdata** | 19999 | System monitoring |

See [Stacks Reference](docs/reference/stacks.md#port-allocation) 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](docs/guides/gpu-docker-config.md) 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](docs/reference/stacks.md#storage-convention) for details.

## Current Phase

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

See [STATUS.md](STATUS.md) for detailed progress tracking.

## Contributing

This is a personal infrastructure project. For AI agents:
- **Read [AGENTS.md](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](https://docs.portainer.io/)
- [Ollama](https://github.com/ollama/ollama)
- [Headscale](https://headscale.net/)
- [Jellyfin](https://jellyfin.org/docs/)
- [Nextcloud](https://docs.nextcloud.com/)

---

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