# portainer-core

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

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

## Quick Links

### Documentation

- [Container Reference](CONTAINERS.md) - All services, ports, configuration
- [Changelog](CHANGELOG.md) - Version history
- [Agent Guidelines](AGENTS.md) - For LLM coding agents

#### Guides
- [GPU Docker Configuration](docs/guides/gpu-docker-config.md)
- [Headscale VPN Setup](docs/guides/headscale-setup.md)
- [Connect Devices to VPN](docs/guides/connect-devices-guide.md)
- [Code-Server Setup](docs/guides/code-server-setup.md)
- [NPM Logging](docs/guides/npm-logging-guide.md)

## 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                       │
│  ├── 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 [External Services](docs/EXTERNAL_SERVICES.md) 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 |
| **Organizr** | 8084 | Unified 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 |
| **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