220 lines
8.5 KiB
Markdown
220 lines
8.5 KiB
Markdown
# 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
|