jpmschweitzer/portainer-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

restructure documentation

Browse Source
This commit is contained in:
jpmschweitzer
2025-11-20 10:17:09 +01:00
parent cb428a885d
commit 0e3fef20fc
28 changed files with 1332 additions and 402 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+115 -121
View File
@@ -1,35 +1,58 @@
# tower-of-joy
# portainer-core
> Self-hosted home server infrastructure with GPU-accelerated ML model serving, media streaming, and secure remote access
> Self-hosted home server infrastructure with GPU-accelerated ML, AI orchestration, media streaming, and secure remote access
## Overview
**Main Dashboard:** https://home.schweitz.net (Organizr)
**tower-of-joy** is a containerized home server platform running on the "tower-of-joy" system, leveraging Portainer + Docker Compose for service orchestration. The infrastructure supports GPU-accelerated workloads (ML inference via Ollama, media transcoding via Jellyfin) while maintaining a clean separation between performance-critical configs (SSD) and bulk content storage (HDD).
## Quick Links
## Quick Start
### 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
**Main Dashboard:** https://home.schweitz.net (Organizr - unified interface for all services)
### Implementation Plans
- [Implementation Plans](PLANS.md) - Master plan tracker
- [Active Plans](plans/active/) - Current development work
- [Completed Plans](plans/completed/) - Historical implementations
### Documentation Index
## System Specifications
#### Architecture & Design
- [Shared Infrastructure Architecture](docs/architecture/SHARED_INFRASTRUCTURE_ARCHITECTURE.md) - PostgreSQL/Redis shared infrastructure
- **Host:** tower-of-joy (Zorin OS 16.3 / Ubuntu 20.04)
- **CPU:** Intel i7-6700 (4C/8T @ 3.40GHz)
- **RAM:** 16GB
- **GPU:** NVIDIA RTX 2080 Ti (11GB VRAM)
- **Storage:**
- **SSD (489GB):** Configs, databases, Docker images → `/home/jpmschweitzer/docker-data/`
- **HDD (3.7TB):** Media, user content, backups → `/mnt/media/`
#### 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
## Architecture
#### 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 (8001) - Container mgmt │
│ ├── Portainer (8080) - Container mgmt │
│ ├── PostgreSQL Shared (5432) - DB │
│ ├── Redis Shared (6379) - Cache │
│ ├── NPM (81) - Reverse proxy │
│ ├── NPM (8000) - Reverse proxy │
│ └── Ollama (11434) - ML models [GPU] │
├─────────────────────────────────────────┤
│ Networking Layer │
@@ -39,14 +62,14 @@
│ Monitoring Layer │
│ ├── Uptime Kuma (3001) - Uptime │
│ ├── Netdata (19999) - Metrics │
│ └── Organizr (9999) - Dashboard │
│ └── Organizr (8084) - Dashboard │
├─────────────────────────────────────────┤
│ Optimization Layer │
│ ├── Watchtower - Auto-updates │
│ └── Maintenance - Automated backups │
├─────────────────────────────────────────┤
│ Application Layer │
│ ├── Open WebUI (82) - LLM chat UI │
│ ├── Open WebUI (8081) - LLM chat UI │
│ ├── Core API (8083) - Infra mgmt │
│ ├── Jellyfin (8096) - Media [GPU] │
│ ├── Nextcloud (8082) - Cloud storage │
@@ -58,59 +81,28 @@
## Project Structure
```
tower-of-joy/
├── stacks/ # Docker Compose files (version-controlled)
│ ├── portainer.yml
│ ├── nginx-proxy-manager.yml
│ ├── ollama.yml
│ ├── headscale.yml
│ ├── jellyfin.yml
│ ├── nextcloud.yml
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
│ └── ...
├── scripts/ # Maintenance automation
│ ├── health-check.sh
│ ├── gpu-check.sh
│ ├── backup-configs.sh
│ ├── disk-usage.sh
│ └── cleanup.sh
├── containers/ # Research & implementation docs
│ ├── research.md
│ └── implementation-plan.md
├── Makefile # Common operations
├── STATUS.md # Current phase tracking
├── CHANGELOG.md # Version history
├── AGENTS.md # AI agent guidelines
└── SYSTEM.md # Hardware documentation
├── 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
```
## Documentation
- **[CONTAINERS.md](CONTAINERS.md)** - Complete container reference guide with specs and access details
- **[docs/SHARED_INFRASTRUCTURE_ARCHITECTURE.md](docs/SHARED_INFRASTRUCTURE_ARCHITECTURE.md)** - PostgreSQL/Redis shared infrastructure design
- **[AGENTS.md](AGENTS.md)** - Guidelines for AI coding agents (conventions, testing, commits)
- **[STATUS.md](STATUS.md)** - Current implementation phase and progress
- **[CHANGELOG.md](CHANGELOG.md)** - Version history and completed work
- **[SYSTEM.md](SYSTEM.md)** - Detailed hardware and software specs
## Development Setup
### Python Environment
Some automation scripts require Python dependencies. A virtual environment is provided:
```bash
# Activate virtual environment
source .venv/bin/activate
# Install/update dependencies
pip install -r requirements.txt
# Deactivate when done
deactivate
```
**Note:** The `.venv/` directory is gitignored and must be created on each system.
## Common Commands
### Infrastructure Management
@@ -132,94 +124,96 @@ make update-jellyfin # Update Jellyfin to latest
make stop-nextcloud # Stop Nextcloud stack
```
### Phase Deployment
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
make deploy-phase1 # Deploy foundation (Portainer, NPM, Ollama)
make deploy-phase2 # Deploy networking (Headscale)
make deploy-phase3 # Deploy monitoring (Uptime Kuma, Netdata, Heimdall)
make deploy-phase4 # Deploy optimization (Watchtower, Maintenance)
make deploy-apps # Deploy applications (Jellyfin, Nextcloud, Samba)
# Activate virtual environment
source .venv/bin/activate
# Install/update dependencies
pip install -r requirements.txt
# Deactivate when done
deactivate
```
## Service Ports
### Service Development
See individual service documentation:
- [Core API Development](docs/services/core-api.md#development)
## Service Ports Reference
| Service | Port | Description |
|---------|------|-------------|
| **Portainer** | 8001 | Container management UI |
| **PostgreSQL Shared** | 5432 | Shared database server (internal) |
| **Redis Shared** | 6379 | Shared cache server (internal) |
| **Nginx Proxy Manager** | 81 | Reverse proxy admin |
| **Open WebUI** | 82 | LLM chat interface |
| **Ollama** | 11434 | ML model API |
| **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 |
| **Code-Server** | 8084 | Browser-based IDE (localhost only) |
| **Organizr** | 8084 | Unified dashboard |
| **Headscale** | 8085 | VPN control server |
| **Jellyfin** | 8096 | Media streaming |
| **Nextcloud** | 8082 | Cloud storage |
| **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 |
| **Organizr** | 9999 | Unified dashboard |
See [Stacks Reference](docs/reference/stacks.md#port-allocation) for complete port allocation.
## GPU Services
Two services leverage the RTX 2080 Ti for GPU acceleration:
Two services leverage the RTX 2080 Ti:
1. **Ollama** (ML inference)
- Supports 3B-13B parameter models
- Recommended: llama3.2:3b, mistral:7b, codellama:7b
1. **Ollama** - ML model inference (3B-13B parameter models)
2. **Jellyfin** - Hardware video transcoding (NVENC)
2. **Jellyfin** (Media transcoding)
- NVIDIA NVENC hardware encoding
- Can handle multiple 4K transcodes simultaneously
See [GPU Docker Configuration](docs/guides/gpu-docker-config.md) for setup.
## Storage Strategy
**SSD (Performance-Critical):**
- Docker configs
- Application databases
- Cache directories
- Container images
**SSD (Performance):** `/home/jpmschweitzer/docker-data/`
- Docker configs, databases, cache, container images
**HDD (Capacity-Critical):**
- Media files (Jellyfin)
- User data (Nextcloud)
- Game server worlds (AMP)
- Backups
**HDD (Capacity):** `/mnt/media/`
- Media files, user data, backups
## Current Status
See [Stacks Reference](docs/reference/stacks.md#storage-convention) for details.
**Phase:** Planning & Documentation Complete ✅
## Current Phase
**Next Steps:**
1. Review implementation plan
2. Verify prerequisites (Docker, GPU, disk space)
3. Begin Phase 1: Foundation Setup
**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 working on this codebase:
- Read [AGENTS.md](AGENTS.md) for guidelines
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
## License
Personal infrastructure project - not licensed for reuse.
## Resources
- **Portainer:** https://docs.portainer.io/
- **Ollama:** https://github.com/ollama/ollama
- **Headscale:** https://headscale.net/
- **Jellyfin:** https://jellyfin.org/docs/
- **Nextcloud:** https://docs.nextcloud.com/
- [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.5.0-optimization
**Last Updated:** 2025-11-16
**Version:** 0.7.1
**Last Updated:** 2025-11-20
**System:** tower-of-joy