# tower-of-joy

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

## Overview

**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 Start

**Main Dashboard:** https://home.schweitz.net (Organizr - unified interface for all services)


## System Specifications

- **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/`

## Architecture

```
┌─────────────────────────────────────────┐
│  Infrastructure Layer                   │
│  ├── Portainer (8080) - Container mgmt │
│  ├── NPM (8000) - Reverse proxy        │
│  └── Ollama (11434) - ML models [GPU]  │
├─────────────────────────────────────────┤
│  Networking Layer                       │
│  └── Headscale (8085) - Secure mesh    │
├─────────────────────────────────────────┤
│  Monitoring Layer                       │
│  ├── Uptime Kuma (3001) - Uptime       │
│  ├── Netdata (19999) - Metrics         │
├─────────────────────────────────────────┤
│  Optimization Layer                     │
│  ├── Watchtower - Auto-updates         │
│  └── Maintenance - Automated backups   │
├─────────────────────────────────────────┤
│  Application Layer (Backlog)            │
│  ├── Jellyfin (8096) - Media [GPU]     │
│  ├── Nextcloud (8082) - Cloud storage  │
│  └── Samba (445) - File shares         │
└─────────────────────────────────────────┘
```

## 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
│   └── ...
├── 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
```

## Documentation

- **[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
- **[containers/research.md](containers/research.md)** - Platform research and comparison
- **[containers/implementation-plan.md](containers/implementation-plan.md)** - Detailed deployment guide

## 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
```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
```

### Phase Deployment
```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)
```

## Service Ports

| Service | Port | Description |
|---------|------|-------------|
| **Nginx Proxy Manager** | 8000 | Unified web interface entry point |
| **Portainer** | 8080 | Container management UI |
| **AMP** | 8081 | Game server management (existing) |
| **Open WebUI** | 82 | LLM chat interface |
| **Ollama** | 11434 | ML model API |
| **Core API** | 8083 | OpenAPI functions for Open WebUI |
| **Code-Server** | 8084 | Browser-based IDE (localhost only) |
| **Headscale** | 8085 | Tailscale control server |
| **Jellyfin** | 8096 | Media streaming |
| **Nextcloud** | 8082 | Cloud storage |
| **Uptime Kuma** | 3001 | Service monitoring |
| **Netdata** | 19999 | System monitoring |
| **Heimdall** | 8888 | Application dashboard |
| **Organizr** | 9999 | Unified dashboard |

## GPU Services

Two services leverage the RTX 2080 Ti for GPU acceleration:

1. **Ollama** (ML inference)
   - Supports 3B-13B parameter models
   - Recommended: llama3.2:3b, mistral:7b, codellama:7b

2. **Jellyfin** (Media transcoding)
   - NVIDIA NVENC hardware encoding
   - Can handle multiple 4K transcodes simultaneously

## Storage Strategy

**SSD (Performance-Critical):**
- Docker configs
- Application databases
- Cache directories
- Container images

**HDD (Capacity-Critical):**
- Media files (Jellyfin)
- User data (Nextcloud)
- Game server worlds (AMP)
- Backups

## Current Status

**Phase:** Planning & Documentation Complete ✅

**Next Steps:**
1. Review implementation plan
2. Verify prerequisites (Docker, GPU, disk space)
3. Begin Phase 1: Foundation Setup

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
- 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/

---

**Version:** 0.1.0-planning
**Last Updated:** 2025-11-11
**System:** tower-of-joy