From c842b4a398205b1af3c908c230bdaf098304f9bf Mon Sep 17 00:00:00 2001
From: Arpad Krejczinger <krejczinger.arpad@gmail.com>
Date: Sun, 1 Mar 2026 23:45:18 +0100
Subject: [PATCH] Streamline AI docs, add skills, enforce symlink-everything
 policy

- Add .claude/skills/: homelab-context (auto-loads key facts each session),
  homelab-status (/homelab-status command), deploy-config (symlink setup guide)
- Remove AGENTS.md and ai/sessions/: superseded by plan mode + skill system
- Remove 4 obsolete session commands (session-start/list/switch, reload-instructions)
- Rewrite CLAUDE.md: remove duplicate content, enforce symlink policy, clarify sudo pattern
- Trim docs/services.md from 946 to ~230 lines: remove planning-era content,
  keep install steps and current status for migration reference
- Strip stale "sudo cp" deploy header from ssh-honeypot.service (now symlinked to repo)
- Update TODO.md: mark NAS migration and symlink tasks done, add jellyfin upgrade warning
---
 .claude/skills/deploy-config/SKILL.md   |  52 ++
 .claude/skills/homelab-context/SKILL.md |  98 +++
 .claude/skills/homelab-status/SKILL.md  |  15 +
 AGENTS.md                               |  76 --
 CLAUDE.md                               | 250 ++----
 TODO.md                                 |  22 +-
 config/systemd/ssh-honeypot.service     |   9 -
 docs/services.md                        | 993 ++++--------------------
 8 files changed, 388 insertions(+), 1127 deletions(-)
 create mode 100644 .claude/skills/deploy-config/SKILL.md
 create mode 100644 .claude/skills/homelab-context/SKILL.md
 create mode 100644 .claude/skills/homelab-status/SKILL.md
 delete mode 100644 AGENTS.md

diff --git a/.claude/skills/deploy-config/SKILL.md b/.claude/skills/deploy-config/SKILL.md
new file mode 100644
index 0000000..995f2e3
--- /dev/null
+++ b/.claude/skills/deploy-config/SKILL.md
@@ -0,0 +1,52 @@
+---
+name: deploy-config
+description: Set up symlinks from system config locations to this repo. Use when setting up on a new machine, or when a config file is found to be a real file instead of a symlink (config drift). Not for routine config changes — just edit the repo file directly.
+disable-model-invocation: true
+allowed-tools: Write, Bash(chmod *), Bash(diff *), Bash(ls *)
+---
+
+All system configs should be symlinked to this repo. Editing the repo file IS editing the live config.
+
+## Symlink Map
+
+| System location | Repo source |
+|---|---|
+| `/etc/nginx/sites-available/homelab` | `config/nginx/homelab.conf` |
+| `/var/www/homelab/index.html` | `config/www/index.html` |
+| `/etc/systemd/system/copyparty.service` | `config/systemd/copyparty.service` |
+| `/etc/systemd/system/glances-web.service` | `config/systemd/glances-web.service` |
+| `/etc/systemd/system/ssh-honeypot.service` | `config/systemd/ssh-honeypot.service` |
+| `/opt/docker/<service>/docker-compose.yml` | `config/docker/<service>/docker-compose.yml` |
+
+## When to use this skill
+
+- **New machine setup**: Create all symlinks from scratch
+- **Drift detected**: A system file is a real file instead of a symlink — replace it with a symlink
+- **New config added to repo**: Create the initial symlink for it
+
+## How to create/fix a symlink
+
+Generate a script in `scripts/tmp/symlink-<name>.sh`:
+
+```bash
+#!/bin/bash
+set -e
+REPO="/home/hoborg/homelab/<repo-path>"
+SYSTEM="<system-path>"
+
+# Back up if it's a real file (not already a symlink)
+[ ! -L "$SYSTEM" ] && cp "$SYSTEM" "${SYSTEM}.backup.$(date +%Y%m%d)" && echo "Backup created"
+
+ln -sf "$REPO" "$SYSTEM" && echo "Symlink created"
+# Add post-link steps here (e.g. nginx -t && systemctl reload nginx, systemctl daemon-reload)
+```
+
+Tell the user to run: `sudo bash ~/homelab/scripts/tmp/symlink-<name>.sh`
+
+## Routine config changes
+
+Just edit `config/<path>` in the repo. The symlink means it's already live. Then:
+- Nginx: `sudo nginx -t && sudo systemctl reload nginx`
+- Systemd unit: `sudo systemctl daemon-reload && sudo systemctl restart <service>`
+- Docker: `cd /opt/docker/<service> && docker compose restart`
+- www/index.html: no action needed (served directly)
diff --git a/.claude/skills/homelab-context/SKILL.md b/.claude/skills/homelab-context/SKILL.md
new file mode 100644
index 0000000..acc1ab0
--- /dev/null
+++ b/.claude/skills/homelab-context/SKILL.md
@@ -0,0 +1,98 @@
+---
+name: homelab-context
+description: Background reference for the homelab repo. Auto-loads key facts about services, ports, paths, and operational rules when working in this project.
+user-invocable: false
+---
+
+## Architecture
+
+- **Domain**: ak-homelab.duckdns.org (DuckDNS)
+- **Static IP**: 192.168.0.100 (interface: enp4s0)
+- **SSH**: port 2222 (system), port 2223 (Gitea git)
+- **NAS**: 192.168.0.101, mounted at `/mnt/nas/`
+
+## Services & Ports
+
+| Service     | Port  | Type     | Path            |
+|-------------|-------|----------|-----------------|
+| Nginx       | 80/443| systemd  | reverse proxy   |
+| Gitea       | 3000  | Docker   | /gitea/         |
+| Jellyfin    | 8096  | Docker   | /media/         |
+| Copyparty   | 8082  | systemd  | /files/         |
+| Netdata     | 19999 | Docker   | /netdata/       |
+| Portainer   | 9000  | Docker   | /portainer/     |
+| qBittorrent | 8080  | Docker   | /qbt/           |
+
+## Key Paths
+
+All configs are **symlinked** from system locations to this repo — editing the repo file is editing the live config:
+
+| System location | Repo source |
+|---|---|
+| `/opt/docker/<service>/docker-compose.yml` | `config/docker/<service>/docker-compose.yml` |
+| `/etc/nginx/sites-available/homelab` | `config/nginx/homelab.conf` |
+| `/var/www/homelab/index.html` | `config/www/index.html` |
+| `/etc/systemd/system/copyparty.service` | `config/systemd/copyparty.service` |
+| `/etc/systemd/system/glances-web.service` | `config/systemd/glances-web.service` |
+| `/etc/systemd/system/ssh-honeypot.service` | `config/systemd/ssh-honeypot.service` |
+
+- NAS docker data: `/mnt/nas/docker-data/<service>/`
+
+## Critical Rules
+
+### Docker UID for NAS-mounted volumes
+Services with data on NAS (`/mnt/nas/`) must use `USER_UID=1024 USER_GID=100` to match NAS file ownership. Services with local storage use `1000:1000`.
+
+### Docker config changes
+Edit `config/docker/<service>/docker-compose.yml` in repo → restart container. No copy needed (symlinked).
+
+### After editing a config in repo
+- **Docker**: `cd /opt/docker/<service> && docker compose restart`
+- **Nginx**: `sudo nginx -t && sudo systemctl reload nginx`
+- **Systemd unit**: `sudo systemctl daemon-reload && sudo systemctl restart <service>`
+- **www/index.html**: no action needed
+
+### Sudo scripts
+Never run sudo directly. Generate a script in `scripts/tmp/` and run `sudo bash ~/homelab/scripts/tmp/<script>.sh`.
+The sudoers rule `/etc/sudoers.d/homelab-scripts` grants NOPASSWD for `scripts/tmp/*` — no password needed.
+
+### s6-overlay containers (Gitea)
+Do NOT set `user:` directive in docker-compose. Use `USER_UID`/`USER_GID` env vars instead — s6-overlay needs root to start, then drops privileges.
+
+### Never copy any config files
+All configs are symlinked. Copying a file breaks the link and causes drift from the repo.
+
+## NAS Services Currently Using 1024:100
+- Gitea (`/mnt/nas/docker-data/gitea/data`)
+- Nextcloud app + db (`/mnt/nas/docker-data/nextcloud/`)
+
+## Management Quick Reference
+
+```bash
+# Docker service (from anywhere)
+cd /opt/docker/<service> && docker compose logs -f
+cd /opt/docker/<service> && docker compose restart
+cd /opt/docker/<service> && docker compose down && docker compose up -d
+
+# Systemd services
+sudo systemctl status nginx copyparty netdata
+sudo systemctl restart nginx
+
+# Nginx
+sudo nginx -t && sudo systemctl reload nginx
+
+# NAS mount check
+mountpoint /mnt/nas && echo mounted
+```
+
+## Keeping Skills Up To Date
+
+After any change to service configuration, ports, paths, Docker UIDs, or operational rules:
+- Update this skill file (`homelab-context/SKILL.md`) to reflect the new state
+- Update `homelab-status/SKILL.md` if services are added or removed
+- This ensures future sessions always have accurate context without re-reading files
+
+## Docs Reference
+- Full service install steps (for migration): `docs/services.md`
+- Network & security: `docs/network-security.md`
+- Troubleshooting: `docs/troubleshooting/`
diff --git a/.claude/skills/homelab-status/SKILL.md b/.claude/skills/homelab-status/SKILL.md
new file mode 100644
index 0000000..4cdacfa
--- /dev/null
+++ b/.claude/skills/homelab-status/SKILL.md
@@ -0,0 +1,15 @@
+---
+name: homelab-status
+description: Check status of all homelab services at once.
+disable-model-invocation: true
+allowed-tools: Bash(docker *), Bash(systemctl *), Bash(mountpoint *), Bash(nginx *)
+---
+
+Check and report status of all homelab services:
+
+1. Run `docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"` to show all containers
+2. Run `systemctl is-active nginx copyparty netdata` to show systemd service states
+3. Run `mountpoint /mnt/nas` to confirm NAS is mounted
+4. Run `sudo nginx -t` to verify nginx config is valid
+5. Report any services that are stopped, failed, or unhealthy
+6. Note any containers not running that should be (gitea, jellyfin, portainer, qbittorrent, nextcloud)
diff --git a/AGENTS.md b/AGENTS.md
deleted file mode 100644
index b2630df..0000000
--- a/AGENTS.md
+++ /dev/null
@@ -1,76 +0,0 @@
-# AI Agent Instructions and Restrictions
-
-## CRITICAL SECURITY RESTRICTIONS
-
-### ❌ SUDO COMMAND PROHIBITION
-
-**NEVER, UNDER ANY CIRCUMSTANCES, RUN SUDO COMMANDS**
-
-The AI agent MUST NOT execute any commands that require elevated privileges:
-- ❌ `sudo` commands
-- ❌ `su` commands  
-- ❌ Commands that modify system files directly
-- ❌ Commands that require root privileges
-
-### ✅ APPROVED ALTERNATIVES
-
-Instead of running sudo commands, the AI should:
-1. **Create scripts** that the user can run with `sudo -A`
-2. **Document commands** for the user to execute manually
-3. **Explain what needs to be done** and why
-4. **Provide step-by-step instructions** for the user
-
-### EXAMPLES
-
-**❌ WRONG:**
-```bash
-sudo systemctl restart nginx
-sudo chmod 755 /etc/nginx/conf.d/
-```
-
-**✅ CORRECT:**
-```bash
-# Create a script for the user to run
-echo "systemctl restart nginx" > /tmp/restart-nginx.sh
-chmod +x /tmp/restart-nginx.sh
-
-# Then tell the user:
-# "Run: sudo -A /tmp/restart-nginx.sh"
-```
-
-### RATIONALE
-
-- User explicitly denied AI access to sudo
-- Security best practice: AI should not have root privileges
-- User prefers manual control over system changes
-- Prevents accidental system modifications
-
-### VERIFICATION
-
-This restriction has been tested and verified:
-- ✅ AI cannot run sudo commands via bash tool
-- ✅ AI will create scripts instead
-- ✅ User maintains full control over privileged operations
-
-## OTHER OPERATIONAL GUIDELINES
-
-### File Operations
-- ✅ Read files in user directories
-- ✅ Write files in user directories  
-- ✅ Create scripts in `/tmp` or user directories
-- ❌ Modify system configuration files directly
-
-### Network Operations
-- ✅ Check network status with unprivileged commands
-- ✅ Test connectivity
-- ❌ Modify firewall rules directly
-- ❌ Bind to privileged ports (< 1024)
-
-### Service Management
-- ❌ Start/stop/restart system services directly
-- ✅ Check service status with unprivileged commands
-- ✅ Create systemd service files for user to deploy
-
----
-
-**REMEMBER: When in doubt, create a script and let the user run it with sudo.**
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
index cae41dc..ed0d956 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,236 +4,106 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-This is a personal homelab setup repository documenting the migration from cloud services to self-hosted solutions on a ThinkPad running Arch Linux. The project uses Docker for containerized services behind an Nginx reverse proxy.
+Personal homelab on a ThinkPad running Arch Linux. Docker services behind an Nginx reverse proxy. Full context is in `.claude/skills/homelab-context/SKILL.md`.
 
 ## Architecture
 
-### Network Infrastructure
-- **Domain**: ak-homelab.duckdns.org (DuckDNS dynamic DNS)
-- **Static IP**: 192.168.0.100 (dual interface: ethernet enp4s0, WiFi wlp1s0)
-- **SSH**: Custom port 2222 for system access
-- **Reverse Proxy**: Nginx for path-based routing to services
+- **Domain**: ak-homelab.duckdns.org (DuckDNS)
+- **Static IP**: 192.168.0.100 (interface: enp4s0)
+- **NAS**: 192.168.0.101, mounted at `/mnt/nas/`
+- **Reverse Proxy**: Nginx → path-based routing to services
+
+## Configuration Management
+
+All configs are version-controlled in `config/`. Docker compose files are **always symlinked** — never copied:
 
-### Service Architecture
 ```
-Internet → Router → Nginx (80/443) → Services
-                 → SSH (2222) → System
-                 → Gitea SSH (2223) → Git operations
+/opt/docker/<service>/docker-compose.yml → ~/homelab/config/docker/<service>/docker-compose.yml
 ```
 
-**Current Services:**
-- Gitea Git server: Docker container on port 3000, accessible via `/gitea/` path
-- Copyparty file server: Systemd service on port 8082, accessible via `/files/` path with WebDAV support
-- Jellyfin media server: Docker container on port 8096, accessible via `/media/` path
-- Nginx: Reverse proxy routing to `ak-homelab.duckdns.org/servicename/`
+Editing the repo file is editing the live config. Restart the container to apply changes.
 
-### Configuration Management
+All configs — Docker, nginx, systemd units, www — are symlinked to this repo. Editing a file in `config/` is editing the live config. Use `/deploy-config` only on a new machine to create symlinks from scratch, or if drift is detected (a real file exists instead of a symlink).
 
-All configurations are version controlled in the `config/` directory:
-- `config/docker/gitea/`: Gitea container setup and deployment scripts
-- `config/docker/jellyfin/`: Jellyfin media server configuration
-- `config/nginx/`: Reverse proxy configurations with SSL and WebDAV support
-- `config/scripts/`: Utility scripts for system maintenance
-- `~/.config/copyparty/`: Copyparty file server configuration
+## Sudo Access
 
-Configuration files include deployment instructions in comments showing target locations (e.g., `/opt/docker/gitea/`, `/etc/nginx/sites-available/`).
+A sudoers rule at `/etc/sudoers.d/homelab-scripts` grants NOPASSWD for scripts in `scripts/tmp/`:
+```
+hoborg ALL=(ALL) NOPASSWD: /bin/bash /home/hoborg/homelab/scripts/tmp/*
+```
+Scripts generated there can be run with `sudo bash ~/homelab/scripts/tmp/<script>.sh` — no password needed.
+
+Never run sudo commands directly. Always create a script in `scripts/tmp/`.
+
+## Docker Guidelines
+
+- **NAS-mounted volumes** (`/mnt/nas/`): use `USER_UID=1024 USER_GID=100` to match NAS file ownership
+- **Local volumes**: use `USER_UID=1000 USER_GID=1000`
+- **s6-overlay containers** (Gitea): do NOT set `user:` directive — use `USER_UID`/`USER_GID` env vars only
+- **Never copy docker-compose files** — they are symlinked; copying breaks the link and causes config drift
 
 ## Key Commands
 
-### Docker Service Management
+### Docker
 ```bash
-# Gitea operations (from /opt/docker/gitea/)
-docker-compose logs gitea        # View logs
-docker-compose down             # Stop
-docker-compose up -d            # Start
-docker-compose pull && docker-compose up -d  # Update
-
-# Jellyfin operations (from /opt/docker/jellyfin/)
-docker-compose logs jellyfin     # View logs
-docker-compose down             # Stop
-docker-compose up -d            # Start
-docker-compose pull && docker-compose up -d  # Update
-
-# Deploy from repo
-sudo cp config/docker/gitea/docker-compose.yml /opt/docker/gitea/
-sudo cp config/docker/jellyfin/docker-compose.yml /opt/docker/jellyfin/
+cd /opt/docker/<service>
+docker compose logs -f          # View logs
+docker compose restart          # Restart
+docker compose down && docker compose up -d  # Full restart
 ```
 
-### Copyparty File Server Management
+### Nginx
 ```bash
-# Service operations
-sudo systemctl status copyparty   # Check status
-sudo systemctl start copyparty    # Start service
-sudo systemctl stop copyparty     # Stop service
-sudo systemctl restart copyparty  # Restart (reload config)
-
-# Configuration
-sudo cp ~/.config/copyparty/copyparty.conf ~/.config/copyparty/copyparty.conf.backup
-# Edit config and restart service to reload
-```
-
-### Nginx Operations
-```bash
-# Deploy configuration
-sudo cp config/nginx/homelab.conf /etc/nginx/sites-available/homelab
-sudo ln -s /etc/nginx/sites-available/homelab /etc/nginx/sites-enabled/homelab
-
-# Management
 sudo nginx -t                   # Test config
-sudo systemctl reload nginx     # Reload
-sudo systemctl status nginx     # Status
+sudo systemctl reload nginx     # Reload (use restart for major changes)
 ```
 
-### SSL Certificate Management
+### Systemd Services
 ```bash
-sudo certbot --nginx -d ak-homelab.duckdns.org
-sudo systemctl enable certbot.timer  # Auto-renewal
+sudo systemctl status nginx copyparty
+sudo systemctl restart <service>
 ```
 
 ## Development Workflow
 
-### Task Tracking
-Use `TODO.md` for centralized task management organized by category (Network & Security, Git & Development, System Configuration, etc.). Mark completed items and update status in documentation.
+1. Edit files in `config/` (these are the live configs for Docker via symlink)
+2. For non-Docker configs: use `/deploy-config` skill or write a `scripts/tmp/` script
+3. Update `docs/` if the change affects setup or architecture
+4. Update `.claude/skills/homelab-context/SKILL.md` if ports, paths, or rules changed
+5. Commit with a clear message
 
-### Configuration Changes
-1. Edit files in `config/` directory
-2. Test locally when possible
-3. Deploy to target locations with sudo commands included in file headers
-4. Update documentation status in `docs/services.md`
-5. Commit changes with logical separation
+## Documentation Structure
 
-### Documentation Structure
-- `docs/`: Technical documentation for setup procedures
-- `README.md`: Overview and current status  
-- `TODO.md`: Active task tracking
-- Configuration files self-document deployment locations in headers
+- `docs/` — Human-readable reference. Keep for migration and troubleshooting.
+- `README.md` — Overview and current status
+- `TODO.md` — Active task tracking
+- `.claude/skills/homelab-context/SKILL.md` — AI-optimized operational facts (keep in sync with reality)
 
-### Network Configuration Notes
-- System uses dual ethernet ports (enp3s0f0, enp4s0) - stick to enp4s0 consistently
-- Port conflicts: SSH (2222), Gitea SSH (2223), Gitea Web (3000)
-- Router forwarding: HTTP (80), HTTPS (443), SSH (2222), Git SSH (2223)
-
-### Service URLs
-- **Local access**: http://192.168.0.100/servicename/
-- **External access**: https://ak-homelab.duckdns.org/servicename/
-- **Gitea SSH**: ssh://git@ak-homelab.duckdns.org:2223
-- **Voice Assistant**: http://127.0.0.1:8880 (local TTS server)
-- **Copyparty WebDAV**: https://ak-homelab.duckdns.org/files/ (for X-plore, rclone, etc.)
-
-### Voice Assistant Commands
-```bash
-# Enable voice mode (starts server and configures voice-mode)
-./scripts/enable-voice.sh
-
-# Disable voice mode (stops server)
-./scripts/disable-voice.sh
-
-# Manual voice server management
-cd voice-server
-poetry run voice-server        # Start server
-poetry install                 # Install dependencies
-poetry run pytest              # Run tests
-
-# Test TTS directly
-curl -X POST "http://127.0.0.1:8880/v1/audio/speech" \
-  -H "Content-Type: application/json" \
-  -d '{"input": "Hello world!", "voice": "ryan"}' \
-  --output test.wav
-```
-
-### Disk Usage Analysis Tools
-```bash
-# System-level disk space overview (recommended for regular checks)
-duf                            # Modern df with colors and progress bars
-
-# Directory size analysis 
-dust /home/hoborg             # Quick visual summary with tree view
-dust /home/hoborg --depth 3   # Limit depth for large directories
-
-# Interactive cleanup and detailed analysis
-ncdu /home/hoborg             # Navigate with arrow keys, delete with 'd'
-ncdu /opt/docker              # Analyze Docker data usage
-ncdu ~                        # Scan home directory for large files
-
-# Usage patterns:
-# 1. duf - Quick system health check (like htop for disk space)
-# 2. dust - Fast overview of directory sizes (like tree with sizes)  
-# 3. ncdu - Deep dive cleanup and file management (like htop for files)
-```
-
-### WebDAV Client Setup
-```bash
-# X-plore File Manager (Android)
-# Server: ak-homelab.duckdns.org
-# Path: /files/
-# Port: 443 (HTTPS)
-# Username: hoborg
-# Password: AdminPass2024!
-
-# rclone configuration
-rclone config create homelab-webdav webdav \
-  url=https://ak-homelab.duckdns.org/files/ \
-  vendor=other \
-  user=hoborg \
-  pass=$(rclone obscure "AdminPass2024!")
-
-# Mount with rclone
-rclone mount homelab-webdav: ~/homelab-files --daemon
-
-# Test WebDAV
-curl -X PROPFIND https://hoborg:AdminPass2024!@ak-homelab.duckdns.org/files/ \
-  -H "Depth: 1" -H "Content-Type: text/xml"
-```
-- Always edit the local configs before when possible, and then copy them to the proper location. Instead of editing system files directly (and then losing the config and it won't be in this repo)
-- Never run sudo commands, instead create a script in scripts/tmp and ask the user to run it.
+For detailed install steps per service, see `docs/services.md`.
 
 ## Security Hardening Guidelines
-- When working on security hardening, make sure you **understand the service needs** first, to ensure the security doesn't interfre with normal operations (e.g. some services need read/write filesystem access, not just read)
-- Some containers (like Gitea with s6-overlay) need root start then privilege drop via USER_UID/USER_GID environment variables
+
+- Understand service needs before applying restrictions (some need rw filesystem access)
 - Test each security change individually, not in batches
-- Network access patterns matter: SSH Git needs direct access, HTTP can be proxied through localhost
-- DO NOT set Docker user: directive for services using s6-overlay init systems (breaks initialization)
+- Network access patterns matter: SSH Git needs direct access, HTTP can go through localhost proxy
 
 ## Claude Development Guidelines
 
 ### CRITICAL: Anti-Pattern Reminders
-**BEFORE writing ANY script or solution, Claude MUST:**
 
-1. **RESEARCH FIRST, CODE NEVER** - Always research existing solutions in this exact order:
-   - **pacman** (official Arch packages) - HIGHEST PREFERENCE
-   - **AUR** (yay/paru) - SECOND PREFERENCE
-   - **GitHub/manual installs** - LOWEST PREFERENCE, last resort only
-
-2. **VERIFY SYNTAX BEFORE WRITING** - Never generate scripts with broken syntax:
-   - Use `--help` to check command syntax BEFORE using it
-   - Test commands in small parts first
-   - Never assume argument names or formats
-
-3. **STICK TO THE CHOSEN SOLUTION** - Don't drift away from proven solutions:
-   - If research finds tool X works, USE tool X
-   - Don't randomly switch to tool Y mid-implementation
-   - Finish what you start before considering alternatives
-
-4. **PREFER SIMPLE OVER COMPLEX**:
-   - Use existing tools rather than writing custom scripts
-   - Bash for simple tasks, Python only when complexity requires it
-   - One working solution beats three broken attempts
-
-5. **CHECK PACKAGE REPOSITORIES FIRST**:
-   - Always check `pacman -Ss` before any manual installation
-   - Always check `yay -Ss` before downloading random scripts
-   - Maintained packages > GitHub scripts > custom solutions
+1. **RESEARCH FIRST** — Check existing solutions in order: pacman → AUR → GitHub
+2. **VERIFY SYNTAX BEFORE WRITING** — Use `--help`, test in parts, never assume argument formats
+3. **STICK TO THE CHOSEN SOLUTION** — Don't drift mid-implementation
+4. **PREFER SIMPLE OVER COMPLEX** — Existing tools > custom scripts; bash > python for simple tasks
+5. **CHECK PACKAGE REPOS FIRST** — `pacman -Ss` before any manual installation
 
 ### Failure Patterns to Avoid
-- ❌ Writing broken syntax without testing commands first
-- ❌ Switching solutions mid-implementation without reason
+- ❌ Broken syntax without testing commands first
+- ❌ Switching solutions mid-implementation
 - ❌ Overcomplicating when simple solutions exist
 - ❌ Installing random scripts before checking packages
-- ❌ Creating custom tools when proven ones exist
 
-### Success Pattern to Follow
+### Success Pattern
 - ✅ Research → Choose → Verify syntax → Implement → Test
-- ✅ pacman → AUR → GitHub (in that preference order)
+- ✅ pacman → AUR → GitHub (preference order)
 - ✅ Use proven, maintained tools over custom scripts
-- ✅ Test command syntax with `--help` first
-- ✅ Stay focused on the chosen solution
\ No newline at end of file
diff --git a/TODO.md b/TODO.md
index b1bf824..5750a36 100644
--- a/TODO.md
+++ b/TODO.md
@@ -1,5 +1,13 @@
 # Homelab TODO List
 
+## HIGH PRIO
+
+- [ ] Move all bigger storages to NAS if it isn't there already
+  - Gitea
+  - Nextcloud
+- [ ] Unify YADM configs across different systems
+  - use YADM alternatives method if needed for conflicts
+
 ## Network & Security
 - [x] DuckDNS dynamic DNS setup *(completed - ak-homelab.duckdns.org)*
 - [x] SSH security hardening *(documented in network-security.md)*
@@ -7,7 +15,7 @@
 - [x] Router port forwarding configuration
 - [x] !!! Set up geoblocking for SSH. Rest of SSH hardening already done.
 - [ ] !!! Modify syncthing to sync the NAS folders where appropriate (e.g. Logseq)
-- [ ] Dockerize everything and use symlinks for dockerfiles (tired of constantly copying stuff over)
+- [x] Dockerize everything and use symlinks for dockerfiles — all docker-compose files symlinked from `/opt/docker/` to repo `config/docker/`
 - [ ] !!! IMPORTANT: Run setup scripts made by security reviewer agent
   - [ ] Ran out of AI quota mid-security review so continue where we left off. Some scripts created but it's not
   complete yet
@@ -117,6 +125,18 @@ Lower priority - mostly using SSH or TTY anyways
 - [x] Figure out drag and drop window tiling solution -> workaround with keyboard shortcuts
 - [ ] Install multimedia codecs and applications
 
+## Docker Storage Migration
+- [x] Move Gitea storage to NAS — migrated to `/mnt/nas/docker-data/gitea/data` (USER_UID=1024:100 to match NAS ownership)
+- [x] Move Nextcloud storage to NAS — migrated to `/mnt/nas/docker-data/nextcloud/`
+- [ ] Persist copyparty index database to NAS — currently rebuilt from scratch on every restart (slow, scans entire NAS); mount `/mnt/nas/.copyparty-db` into the container so the index survives restarts
+- [ ] Clean up old leftover data: `/opt/docker/gitea/data/`, `/opt/docker/gitea/data.old/`, Docker volumes `gitea_gitea`, `nextcloud_nextcloud_data`, `nextcloud_nextcloud_db`
+
+## Docker Image Upgrades
+See `docs/docker-upgrade-plan.md` for full plan. Key warnings:
+- **Jellyfin**: v10.11+ does a major EF Core DB migration (`library.db` → `jellyfin.db`). Known to hang at "Saving BaseItem entries". **Back up jellyfin data volume before upgrading.**
+- **Redis**: Stay on `7-alpine` — Redis 8 has ACL breaking changes, not worth upgrading for a cache role
+- All containers are behind on updates as of 2026-02-27 (see plan doc for details)
+
 ## Security & Maintenance
 - [ ] Configure automatic security updates
 - [ ] Set up system monitoring and alerting
diff --git a/config/systemd/ssh-honeypot.service b/config/systemd/ssh-honeypot.service
index 7fae8f3..df3528e 100644
--- a/config/systemd/ssh-honeypot.service
+++ b/config/systemd/ssh-honeypot.service
@@ -1,12 +1,3 @@
-# SSH Honeypot Service
-# Deploy to: /etc/systemd/system/ssh-honeypot.service
-# 
-# Setup commands:
-#   sudo cp config/systemd/ssh-honeypot.service /etc/systemd/system/
-#   sudo systemctl daemon-reload
-#   sudo systemctl enable ssh-honeypot.service
-#   sudo systemctl start ssh-honeypot.service
-
 [Unit]
 Description=SSH Honeypot (Port 22)
 After=network.target
diff --git a/docs/services.md b/docs/services.md
index c80b736..dfa332b 100644
--- a/docs/services.md
+++ b/docs/services.md
@@ -1,283 +1,72 @@
 # Services & Applications
 
-Planning and configuration for self-hosted services and applications.
+Reference for all self-hosted services. Useful for troubleshooting and migrating to a new machine.
 
 ## Nginx Reverse Proxy
 
-**Status**: ✅ Active
-**Port**: 80 (HTTP), 443 (HTTPS)
-**Configuration**: `/etc/nginx/sites-available/homelab`
+**Status**: ✅ Active | **Config**: `config/nginx/homelab.conf` → `/etc/nginx/sites-available/homelab` (symlinked)
 
 ### Features
-- Path-based routing to services (`/gitea/`, `/files/`, `/media/`)
-- SSL termination with Let's Encrypt certificates
-- Security headers (XSS protection, content type sniffing prevention)
-- WebDAV support for Copyparty file server
-- Custom landing page at domain root with service dashboard
-- HTTP to HTTPS redirects
-- Custom error pages
-
-### Configuration Notes
-- Uses `default_server` directive to handle all requests to port 80/443
-- Default nginx server block in `/etc/nginx/nginx.conf` is commented out to prevent conflicts
-- Landing page served from `/var/www/homelab/index.html`
-- Root location uses `location /` (not `location = /`) for proper index file handling
+- Path-based routing (`/gitea/`, `/files/`, `/media/`, `/netdata/`, `/portainer/`)
+- SSL termination with Let's Encrypt (auto-renewal via certbot timer)
+- WebDAV support for Copyparty
+- HTTP → HTTPS redirect
+- Security headers
 
 ### Management
 ```bash
-# Deploy configuration from repo
-sudo cp config/nginx/homelab.conf /etc/nginx/sites-available/homelab
-
-# Test configuration syntax
-sudo nginx -t
-
-# Restart nginx (recommended over reload for major config changes)
-sudo systemctl restart nginx
-
-# View logs
-sudo journalctl -u nginx -f
-
-# Check active configuration
-sudo nginx -T | grep -A20 "server_name ak-homelab"
+sudo nginx -t                        # Test config
+sudo systemctl reload nginx          # Reload (or restart for major changes)
+sudo journalctl -u nginx -f          # Logs
 ```
 
-### Landing Page
-The homelab landing page (`/var/www/homelab/index.html`) provides a dashboard with:
-- Service status indicators
-- Direct links to all services
-- Responsive design with gradient styling
-- Service icons and descriptions
-
-Update the landing page:
+### New Machine Setup
 ```bash
-# Copy from repo (if you have a config/www/index.html)
-sudo cp config/www/index.html /var/www/homelab/
-sudo chown http:http /var/www/homelab/index.html
+sudo pacman -S nginx certbot certbot-nginx
+sudo mkdir -p /etc/nginx/sites-available /etc/nginx/sites-enabled
+sudo ln -s /home/hoborg/homelab/config/nginx/homelab.conf /etc/nginx/sites-available/homelab
+sudo ln -s /etc/nginx/sites-available/homelab /etc/nginx/sites-enabled/homelab
+sudo certbot --nginx -d ak-homelab.duckdns.org
+sudo systemctl enable --now certbot-renew.timer
 ```
 
-### Troubleshooting
-For landing page 404 issues, see the detailed troubleshooting guide in `docs/troubleshooting.md` under "Landing Page Returns 404 Not Found".
+---
 
-Common debugging commands:
-```bash
-# Check nginx configuration is active
-sudo nginx -T | grep -A10 "server_name ak-homelab"
+## Gitea (Git Server)
 
-# Test landing page access
-curl -I https://ak-homelab.duckdns.org/
+**Status**: ✅ Running | **Docker**: `/opt/docker/gitea/` | **Data**: `/mnt/nas/docker-data/gitea/data`
 
-# Monitor nginx logs in real-time
-sudo journalctl -u nginx -f
+- **Web**: https://ak-homelab.duckdns.org/gitea/
+- **SSH**: `ssh://git@ak-homelab.duckdns.org:2223`
+- **Ports**: 3000 (web, localhost only), 2223 (SSH, public)
+- **UID**: 1024:100 (matches NAS file ownership)
 
-# Verify file permissions
-sudo ls -la /var/www/homelab/index.html
-```
-
-## Git Repository Hosting
-
-### Service Options
-- **Gitea**: Lightweight, Go-based, minimal resource usage ✅ *Recommended*
-- **Forgejo**: Gitea fork, community-driven development
-- **GitLab CE**: Feature-rich but more resource intensive
-- **Gogs**: Simple, lightweight alternative
-
-### Gitea Installation (Docker - Recommended)
-
-**Status:** ✅ **Container Running** ⚠️ **Configuration Issues** - UI accessible, config needs debugging
-
-**Prerequisites:**
-```bash
-# Install Docker and Docker Compose
-sudo pacman -S docker docker-compose
-sudo systemctl enable docker
-sudo systemctl start docker
-
-# Add user to docker group (logout/login required)
-sudo usermod -aG docker hoborg
-```
-
-**Gitea Docker Setup:**
-```bash
-# Create directories for persistent data
-mkdir -p ~/docker/gitea/{data,config}
-
-# Run Gitea container
-docker run -d \
-  --name gitea \
-  -p 3000:3000 \
-  -p 2222:22 \
-  -v ~/docker/gitea/data:/data \
-  -v ~/docker/gitea/config:/etc/gitea \
-  -e USER_UID=1000 \
-  -e USER_GID=1000 \
-  gitea/gitea:latest
-
-# Alternative: Docker Compose (preferred)
-# See docker-compose.yml below
-```
-
-**Docker Compose Configuration:**
-Create `~/docker/gitea/docker-compose.yml`:
-```yaml
-version: "3"
-
-networks:
-  gitea:
-    external: false
-
-services:
-  server:
-    image: gitea/gitea:latest
-    container_name: gitea
-    environment:
-      - USER_UID=1000
-      - USER_GID=1000
-    restart: always
-    networks:
-      - gitea
-    volumes:
-      - ./data:/data
-      - /etc/timezone:/etc/timezone:ro
-      - /etc/localtime:/etc/localtime:ro
-    ports:
-      - "3000:3000"
-      - "2223:22"  # Gitea SSH (avoid conflict with system SSH on 2222)
-```
-
-**Start with Docker Compose:**
-```bash
-cd ~/docker/gitea
-docker-compose up -d
-```
-
-### Current Configuration
-
-**Container Status:** ✅ Running at /opt/docker/gitea
-**Access URLs:**
-- **Local Web**: http://192.168.0.100:3000
-- **External Web**: http://ak-homelab.duckdns.org:3000 (requires port forwarding)
-- **Git SSH**: ssh://git@ak-homelab.duckdns.org:2223 (requires port forwarding)
-
-**Port Assignments:**
-- **System SSH**: 2222 (for server administration)
-- **Gitea SSH**: 2223 (for Git operations)
-- **Gitea Web**: 3000 (web interface)
-
-**Database**: SQLite (default, stored in container volume)
-**Data Location**: /opt/docker/gitea/data (persistent volume)
-
-**Router Port Forwarding Required:**
-- 3000 → 192.168.0.100:3000 (web interface)
-- 2223 → 192.168.0.100:2223 (Git SSH operations)
-
-**Container Management:**
+### Management
 ```bash
 cd /opt/docker/gitea
-docker-compose logs gitea        # View logs
-docker-compose down             # Stop container
-docker-compose up -d            # Start container
-docker-compose pull && docker-compose up -d  # Update
+docker compose logs -f gitea
+docker compose restart
+docker compose pull && docker compose up -d   # Update
 ```
 
-### Gitea Configuration Recommendations
-
-**Database Selection:**
-- ✅ **SQLite** (Recommended for homelab)
-  - Zero configuration, single file
-  - Perfect for personal/small team use
-  - Easy backups and migration
-- **PostgreSQL** (Production alternative)
-  - Better performance for heavy usage
-  - Requires additional container setup
-
-**Domain & URL Configuration:**
-- **Server Domain**: `ak-homelab.duckdns.org`
-- **Gitea Base URL**: `http://ak-homelab.duckdns.org/gitea/`
-- **SSH Domain**: `ak-homelab.duckdns.org`
-- **SSH Port**: `2223`
-
-**Password Hash Algorithm:**
-- ✅ **Argon2** (Recommended)
-  - Most secure modern algorithm
-  - Resistant to GPU/ASIC attacks
-  - Higher CPU usage but excellent security
-- **bcrypt** (Alternative)
-  - Well-tested, lower resource usage
-  - Good balance of security and performance
-
-**Setup Progress:**
-1. ✅ Gitea container running
-2. ✅ Nginx reverse proxy setup complete
-3. ✅ Router port forwarding (80, 443) - **COMPLETE - External access working**
-4. ✅ Gitea web configuration - **COMPLETE**
-   - Initial setup wizard completed
-   - Admin user account created
-   - SSH access configured
-   - Repository migration completed
-5. ✅ SSL certificate setup - **COMPLETE - Let's Encrypt with auto-renewal**
-
-**Current Access:**
-- ✅ Local UI working: https://192.168.0.100/gitea/ (HTTPS with SSL)
-- ✅ External access: https://ak-homelab.duckdns.org/gitea/ - **WORKING (HTTPS enabled)**
-- ✅ Git SSH access: ssh://git@ak-homelab.duckdns.org:2223 - **WORKING**
-
-**Completed Configuration:**
-- Router forwards: 80→80, 443→443, 2223→2223
-- Removed direct port 3000 forwarding
-- Homelab repository successfully migrated to Gitea
-- External access confirmed working from Windows PC
-- SSL certificates installed with Let's Encrypt
-- Automatic HTTP→HTTPS redirect enabled
-- Certificate auto-renewal configured
-
-## Cloud Storage Solutions
-
-### Service Options
-- **Copyparty**: Lightweight file server with resumable uploads, dedup, WebDAV ✅ **DEPLOYED**
-- **Nextcloud**: Full-featured, extensive app ecosystem
-- **ownCloud**: Original project, stable and mature
-- **Seafile**: Performance-focused file sync
-- **Syncthing**: Decentralized sync (no server needed) ✅ **INSTALLED**
-
-### Copyparty Installation and Configuration
-
-**Status:** ✅ **DEPLOYED AND WORKING** - File server with upload/download capabilities
-
-**Installation:**
+### New Machine Setup
 ```bash
-# Installed via Arch package
-sudo pacman -S copyparty
-
-# Configuration file location
-/home/hoborg/.config/copyparty/copyparty.conf
-
-# Systemd service location
-/etc/systemd/system/copyparty.service
+sudo mkdir -p /opt/docker/gitea
+sudo ln -s /home/hoborg/homelab/config/docker/gitea/docker-compose.yml /opt/docker/gitea/docker-compose.yml
+cd /opt/docker/gitea && docker compose up -d
 ```
 
-**Current Setup:**
-- **Local Access**: https://127.0.0.1/files/ (SSL enabled)
-- **External Access**: https://ak-homelab.duckdns.org/files/ (HTTPS with Let's Encrypt SSL)
-- **WebDAV Access**: https://ak-homelab.duckdns.org/files/ (X-plore, rclone compatible)
-- **Port**: 8082 (behind Nginx reverse proxy on /files/ path)
-- **Service**: Managed by systemd, auto-starts on boot
-- **SSL**: Let's Encrypt certificates with automatic renewal
+---
 
-**User Accounts:**
-- **guest**: Standard user with read/write (`rw`) access to shared areas
-- **hoborg**: Admin user with full access (`rwmd` - read/write/move/delete) to all areas including private folder
+## Copyparty (File Server / WebDAV)
 
-**Features:**
-- ✅ File upload/download via web interface
-- ✅ WebDAV support for X-plore File Manager, rclone, etc.
-- ✅ File deletion via WebDAV (requires `d` permission)
-- ✅ Drag & drop upload in web interface
-- ✅ Support for files with spaces/special characters
-- ✅ Large file upload support (up to 10GB)
-- ✅ Resume interrupted uploads
-- ✅ File deduplication and integrity checking
+**Status**: ✅ Running | **Type**: systemd | **Config**: `config/systemd/copyparty.service` (symlinked)
 
-**Volume Structure:**
+- **Web / WebDAV**: https://ak-homelab.duckdns.org/files/
+- **Port**: 8082 (behind Nginx)
+- **Config**: `~/.config/copyparty/copyparty.conf`
+
+### Volumes
 ```
 /shared     → /home/hoborg/shared       (guest: rw, hoborg: rwmd)
 /documents  → /home/hoborg/Documents    (hoborg: rwmd)
@@ -287,660 +76,162 @@ sudo pacman -S copyparty
 /private    → /home/hoborg/private      (hoborg only: rwmd)
 ```
 
-**Features Enabled:**
-- User-changeable passwords (stored securely in encrypted database)
-- Upload deduplication (saves storage space)
-- File indexing and search (e2dsa)
-- Resumable uploads with up2k
-- File integrity verification
-- Thumbnail generation for images and videos
-
-**Security:**
-- Authentication required for all access
-- Passwords stored in encrypted format: `/home/hoborg/.config/copyparty/passwords.json`
-- Admin-only private folder isolated from shared areas
-- Reverse proxy headers for proper client IP logging
-
-**Service Management:**
+### Management
 ```bash
-# Check status
 sudo systemctl status copyparty
-
-# View logs
-journalctl -fu copyparty
-
-# Restart service
 sudo systemctl restart copyparty
-
-# Enable/disable autostart
-sudo systemctl enable copyparty
-sudo systemctl disable copyparty
+journalctl -fu copyparty
 ```
 
-**Configuration Files:**
-- **Main config**: `/home/hoborg/.config/copyparty/copyparty.conf`
-- **Systemd service**: `/home/hoborg/homelab/config/systemd/copyparty.service`
-- **Nginx integration**: Path `/files/` in homelab.conf
+### WebDAV Clients
+- **X-plore (Android)**: Server `ak-homelab.duckdns.org`, Path `/files/shared/`, Port 443, HTTPS
+- **rclone**: `rclone config create homelab-webdav webdav url=https://ak-homelab.duckdns.org/files/ vendor=other user=hoborg`
 
-**WebDAV Client Setup:**
-
-*X-plore File Manager (Android):*
-- Server: `ak-homelab.duckdns.org`
-- Path: `/files/shared/` (or other folder paths)
-- Protocol: HTTPS (port 443)
-- Username: `hoborg`
-- Password: [your password]
-
-*rclone configuration:*
+### New Machine Setup
 ```bash
-rclone config create homelab-webdav webdav \
-  url=https://ak-homelab.duckdns.org/files/ \
-  vendor=other \
-  user=hoborg \
-  pass=$(rclone obscure "your_password")
+sudo pacman -S copyparty
+sudo ln -s /home/hoborg/homelab/config/systemd/copyparty.service /etc/systemd/system/copyparty.service
+sudo systemctl daemon-reload && sudo systemctl enable --now copyparty
 ```
 
-**Troubleshooting:**
-- For issues with files containing spaces, see [docs/troubleshooting/webdav-copyparty.md](troubleshooting/webdav-copyparty.md)
-- Check nginx WebDAV configuration for URL encoding issues
-- Verify copyparty permissions include `d` flag for delete operations
+---
 
-**Testing Confirmed:**
-- ✅ File uploads working (including video files)
-- ✅ WebDAV folder uploads from Android (X-plore File Manager)
-- ✅ User authentication and authorization
-- ✅ Private folder access restricted to admin
-- ✅ External access through reverse proxy
-- ✅ Service auto-starts on boot
+## Jellyfin (Media Server)
 
-### Nextcloud Installation
-```bash
-# Via snap (recommended)
-sudo snap install nextcloud
+**Status**: ✅ Running | **Docker**: `/opt/docker/jellyfin/`
 
-# Or via Docker
-docker run -d \
-  --name nextcloud \
-  -p 8080:80 \
-  -v nextcloud_data:/var/www/html \
-  nextcloud
+- **Local**: http://localhost:8096
+- **External**: https://ak-homelab.duckdns.org/media/
+- **Hardware accel**: VAAPI/QSV via `/dev/dri`
+
+### Media Library Paths (inside container)
+```
+/media/music    → /home/hoborg/Music
+/media/videos   → /home/hoborg/Videos
+/media/pictures → /home/hoborg/Pictures
+/media/shared   → /home/hoborg/shared
+/media/private  → /home/hoborg/private
 ```
-Personal notes: Not a fan of snap, isn't there an AUR package?
-Go with docker otherwise
 
-### Features
-- File synchronization across devices
-- Video files, game installers -> high prio
-- Self-hosted git mirrors of favorite FOSS projects -> medium prio
-- Calendar and contacts (CalDAV/CardDAV) -> low prio
-- Document editing (OnlyOffice/Collabora) -> low prio
-- Photo management and sharing -> low prio
-- Mobile apps available?
-
-## Media Management
-
-### Jellyfin Media Server
-
-**Status:** ✅ **DEPLOYED AND WORKING** - Docker-based media server with hardware acceleration
-
-**Installation:**
+### Management
 ```bash
-# Deploy configuration files
-sudo mkdir -p /opt/docker/jellyfin/{config,cache}
-sudo cp config/docker/jellyfin/docker-compose.yml /opt/docker/jellyfin/
-
-# Start container
 cd /opt/docker/jellyfin
-sudo docker-compose up -d
+docker compose logs -f jellyfin
+docker compose restart
+docker compose pull && docker compose up -d   # Update
 ```
 
-**Current Setup:**
-- **Local Access**: http://localhost:8096
-- **External Access**: https://ak-homelab.duckdns.org/media/ (HTTPS with Let's Encrypt SSL)
-- **Container**: jellyfin/jellyfin:latest with network_mode: host
-- **Hardware Acceleration**: VAAPI, QSV, CUDA support enabled
+### ⚠️ Upgrade Warning
+v10.11+ performs a major EF Core DB migration (`library.db` → `jellyfin.db`). Known to hang at "Saving BaseItem entries". **Always back up the Jellyfin data volume before upgrading.**
 
-**Media Library Structure:**
-```
-/media/music    → /home/hoborg/Music        (shared with Copyparty)
-/media/videos   → /home/hoborg/Videos       (shared with Copyparty)
-/media/pictures → /home/hoborg/Pictures     (shared with Copyparty)
-/media/shared   → /home/hoborg/shared       (shared with Copyparty)
-/media/private  → /home/hoborg/private      (shared with Copyparty)
-```
-
-**Features Enabled:**
-- Hardware transcoding (Intel/AMD GPU via /dev/dri)
-- Multiple codec support (H.264, H.265, AV1, etc.)
-- Hardware acceleration filters and encoders
-- Reverse proxy integration with optimized streaming settings
-- Resource limits: 2GB max memory, 512MB reserved
-
-**Configuration Management:**
+### New Machine Setup
 ```bash
-# Check container status
-cd /opt/docker/jellyfin && sudo docker-compose logs jellyfin
-
-# Container management
-sudo docker-compose down             # Stop
-sudo docker-compose up -d            # Start
-sudo docker-compose pull && sudo docker-compose up -d  # Update
-
-# View detailed logs
-sudo docker-compose logs -f jellyfin
+sudo mkdir -p /opt/docker/jellyfin
+sudo ln -s /home/hoborg/homelab/config/docker/jellyfin/docker-compose.yml /opt/docker/jellyfin/docker-compose.yml
+cd /opt/docker/jellyfin && docker compose up -d
+# Visit http://localhost:8096 for setup wizard
 ```
 
-**Integration with Other Services:**
-- **Copyparty**: Shares same media folders without duplication
-- **Nginx**: Reverse proxy with streaming-optimized configuration
-- **SSL**: Secured with Let's Encrypt certificates and auto-renewal
+---
 
-**Initial Setup:**
-1. Visit http://localhost:8096 for setup wizard
-2. Create admin account and configure server
-3. Add media libraries pointing to `/media/music`, `/media/videos`, `/media/pictures`, `/media/shared`, `/media/private`
-4. Configure hardware acceleration in Dashboard > Playback settings
+## Nextcloud (Cloud Storage)
 
-**Folder Structure Compatibility: ✅ CONFIRMED WORKING**
-- **Music Library**: Successfully works with existing Artist/Album structure
-- **Copyparty Interoperability**: ✅ Both services share same folders without conflicts
-- **Metadata Support**: Downloads album artwork, descriptions, and artist information from online sources
-- **Electronic Music**: Works well with existing organized structure (e.g., "The Hu - Discography/Albums/...")
+**Status**: ✅ Running | **Docker**: `/opt/docker/nextcloud/` | **Data**: `/mnt/nas/docker-data/nextcloud/`
 
-**Metadata Management:**
-- **Auto-Download**: Enable MusicBrainz, TheAudioDB, Last.fm in Dashboard > Metadata > Music
-- **Manual Refresh**: Library scan via Dashboard > Libraries > Music > Scan Library
-- **Force Refresh**: Use "Replace All Metadata" for complete metadata re-download
-- **Individual Items**: Right-click albums/artists for targeted metadata refresh
+- **Web**: https://ak-homelab.duckdns.org/nextcloud/
+- **Stack**: nextcloud-app + mariadb + redis
 
-### Music Collection Management
-
-**Playlist Extraction:**
-- **YouTube Music**: Use `ytmusicapi` Python library or Google Takeout
-- **SoundCloud**: Use `scdl` tool or SoundCloud API
-- **Output Formats**: CSV (artist, title, playlist), JSON metadata, M3U playlists, plain text lists
-
-**Legal Music Sources:**
-- **High Quality**: Bandcamp (FLAC), Beatport, 7digital, HDtracks
-- **Mainstream**: Amazon Music, iTunes Store, artist websites
-- **Subscription Downloads**: Tidal, Qobuz premium tiers
-- **Physical Media**: CD ripping, vinyl digitization, cassette conversion
-
-**Organization Tools:**
-- **MusicBrainz Picard**: Automatic metadata tagging and correction
-- **beets**: Advanced music library management and organization
-- **Bulk Scripts**: Custom automation for file organization and import
-
-### Photo Management
-- **PhotoPrism**: AI-powered photo management
-- **Immich**: Modern photo backup solution
-- **LibrePhotos**: Privacy-focused alternative
-
-### Torrent Management
-
-**Recommendation: Use NAS Direct Torrenting**
-
-For homelab with NAS storage migration:
-- **NAS Direct**: Internet → NAS (50% less network traffic, better performance)
-- **Laptop → NAS**: Downloads go laptop → network → NAS (double network load)
-- **Access**: Use Synology Download Station via Local Network admin section
-- **Integration**: Mount NAS shares for Jellyfin media access
-- **Efficiency**: Keeps local network clear for other services
-
-## Monitoring & Logging
-
-### System Monitoring
+### Management
 ```bash
-# Prometheus + Grafana stack
-docker-compose up -d prometheus grafana node-exporter
+cd /opt/docker/nextcloud
+docker compose logs -f
+docker compose restart
 ```
 
-### Log Management
-- **Centralized logging**: rsyslog or journald
-- **Log rotation**: logrotate configuration
-- **Analysis**: grep, awk, or ELK stack for advanced needs
-
-### Health Checks
-- **Uptime monitoring**: Simple HTTP checks
-- **Service status**: systemd service monitoring
-- **Disk space**: Automated alerts for low space
-
-## Containerization Strategy
-
-### Docker Setup
+### New Machine Setup
 ```bash
-# Install Docker
-pacman -S docker docker-compose
-sudo systemctl enable docker
-
-# Add user to docker group
-sudo usermod -aG docker hoborg
+sudo mkdir -p /opt/docker/nextcloud
+sudo ln -s /home/hoborg/homelab/config/docker/nextcloud/docker-compose.yml /opt/docker/nextcloud/docker-compose.yml
+cd /opt/docker/nextcloud && docker compose up -d
 ```
 
-### Container Management
-- **Orchestration**: Docker Compose for multi-service apps
-- **Storage**: Named volumes for persistent data
-- **Networking**: Custom networks for service isolation
-- **Updates**: Watchtower for automated updates
+---
 
-## Reverse Proxy Configuration
+## Portainer (Docker Management)
 
-### Decision Matrix: Nginx vs Traefik
+**Status**: ✅ Running | **Docker**: `/opt/docker/portainer/`
 
-**Problem:** Multiple services need to be accessible under single domain with path-based routing.
-**Solution:** Reverse proxy to route requests based on URL paths.
+- **Access**: https://ak-homelab.duckdns.org/portainer/ (built-in auth)
+- **Port**: 9000
 
-#### Nginx
-✅ **Pros:**
-- Mature & battle-tested (decades of production use)
-- High performance for static files and caching
-- Flexible configuration - handles any routing scenario
-- Extensive ecosystem and documentation
-- Can handle non-Docker services easily
-
-❌ **Cons:**
-- Manual configuration required
-- No auto-discovery of services
-- Requires config reload for changes
-
-#### Traefik
-✅ **Pros:**
-- Docker-native auto-discovery via labels
-- Automatic HTTPS with Let's Encrypt
-- Dynamic configuration (no restarts)
-- Modern design for containerized environments
-
-❌ **Cons:**
-- Less mature, smaller ecosystem
-- Docker-dependent (less flexible)
-- Steeper learning curve for complex scenarios
-
-**Decision:** ✅ **Nginx** - Better for homelab due to reliability, documentation, and flexibility for mixed Docker/non-Docker services.
-
-### URL Architecture Decision
-
-**Options Considered:**
-1. **Separate subdomains**: `gitea.ak-homelab.duckdns.org` ❌ *DuckDNS doesn't support nested subdomains*
-2. **Multiple DuckDNS domains**: `ak-homelab-git.duckdns.org` ❌ *Management overhead*
-3. **Path-based routing**: `ak-homelab.duckdns.org/gitea/` ✅ **Selected**
-
-**Chosen Architecture:**
-```
-https://ak-homelab.duckdns.org/          → Landing page/dashboard
-https://ak-homelab.duckdns.org/gitea/    → Gitea Git server ✅ DEPLOYED
-https://ak-homelab.duckdns.org/files/    → Copyparty file server (WebDAV) ✅ DEPLOYED
-https://ak-homelab.duckdns.org/media/    → Jellyfin media server ✅ DEPLOYED
-https://ak-homelab.duckdns.org/monitor/  → System monitoring (planned)
-```
-
-### SSL/TLS Configuration
-
-**Status:** ✅ **COMPLETE** - Let's Encrypt SSL with automatic renewal
-
-**SSL Certificate Setup:**
+### Management
 ```bash
-# Certificate installation (completed)
-sudo certbot --nginx -d ak-homelab.duckdns.org
-
-# Auto-renewal service (enabled)
-sudo systemctl enable certbot-renew.timer
-sudo systemctl start certbot-renew.timer
+cd /opt/docker/portainer && docker compose restart
 ```
 
-**Certificate Details:**
-- **CA**: Let's Encrypt (trusted by all major browsers)
-- **Certificate**: `/etc/letsencrypt/live/ak-homelab.duckdns.org/fullchain.pem`
-- **Private Key**: `/etc/letsencrypt/live/ak-homelab.duckdns.org/privkey.pem`
-- **Renewal**: Automatic every 90 days via systemd timer
-- **Security**: Strong TLS configuration with DH parameters
+---
 
-**Security Features:**
-- **HTTP→HTTPS Redirect**: All HTTP traffic automatically redirected to HTTPS
-- **HSTS Headers**: Included via Let's Encrypt nginx configuration
-- **Strong Ciphers**: Modern TLS 1.2/1.3 cipher suites
-- **Perfect Forward Secrecy**: Enabled via Diffie-Hellman parameters
+## Netdata (System Monitoring)
+
+**Status**: ✅ Running | **Docker**: `/opt/docker/netdata/`
+
+- **Access**: https://ak-homelab.duckdns.org/netdata/ (nginx basic auth)
+- **Port**: 19999
+
+---
+
+## qBittorrent
+
+**Status**: ✅ Running | **Docker**: `/opt/docker/qbittorrent/`
+
+- **Access**: https://ak-homelab.duckdns.org/qbt/
+- **Port**: 8080
+- **Downloads**: NAS preferred (use Synology Download Station for direct-to-NAS torrenting)
+
+---
+
+## SSL Certificates
+
+**Status**: ✅ Auto-renewal active
 
-**Renewal Management:**
 ```bash
-# Check renewal status
-sudo systemctl status certbot-renew.timer
-
-# Manual renewal test (dry run)
+# Manual renewal test
 sudo certbot renew --dry-run
 
-# View renewal logs
+# Check timer
+sudo systemctl status certbot-renew.timer
 journalctl -u certbot-renew.service
 ```
 
-**Certificate Verification:**
-- Browser shows green padlock for all services
-- SSL Labs rating: A+ (expected)
-- All services accessible via HTTPS only
+- **Cert**: `/etc/letsencrypt/live/ak-homelab.duckdns.org/fullchain.pem`
+- **Key**: `/etc/letsencrypt/live/ak-homelab.duckdns.org/privkey.pem`
+- **Renewal**: Every 90 days via systemd timer
 
-### Advanced Nginx Options
+---
 
-**Nginx Plus (Commercial):** $2500+/year
-- Advanced load balancing, health checks
-- API management, JWT validation
-- Real-time monitoring dashboard
-- **Verdict:** Overkill for homelab
+## Landing Page
 
-**Nginx + Lua (OpenResty):**
-- Embed Lua scripts for dynamic processing
-- Complex routing logic, authentication
-- API gateway functionality
-- **Verdict:** Powerful but complex, not needed initially
+**Config**: `config/www/index.html` → `/var/www/homelab/index.html` (symlinked)
 
-### Nginx Setup
+Edit the file in the repo — changes are live immediately (no restart needed).
 
-**Status:** ✅ **Complete** - Reverse proxy configured and running
+---
+
+## Troubleshooting
+
+See `docs/troubleshooting/` for specific issues. Common checks:
 
 ```bash
-# Install nginx and SSL tools
-sudo pacman -S nginx certbot certbot-nginx
+# All containers running?
+docker ps
 
-# Create configuration
-sudo nano /etc/nginx/sites-available/homelab
-
-# Enable site
-sudo ln -s /etc/nginx/sites-available/homelab /etc/nginx/sites-enabled/
-
-# Test and reload
+# Nginx config valid?
 sudo nginx -t
-sudo systemctl reload nginx
+
+# NAS mounted?
+mountpoint /mnt/nas
+
+# Service logs
+journalctl -fu <service>
+docker compose -f /opt/docker/<service>/docker-compose.yml logs -f
 ```
-
-**Configuration Template:**
-```nginx
-server {
-    listen 80;
-    server_name ak-homelab.duckdns.org;
-
-    # Main landing page
-    location / {
-        root /var/www/homelab;
-        index index.html;
-    }
-
-    # Gitea reverse proxy
-    location /gitea/ {
-        proxy_pass http://127.0.0.1:3000/;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-
-    # Future services
-    # location /cloud/ {
-    #     proxy_pass http://127.0.0.1:8080/;
-    #     proxy_set_header Host $host;
-    # }
-}
-```
-
-### Router Port Forwarding Requirements
-- **HTTP**: Port 80 → 192.168.0.100:80
-- **HTTPS**: Port 443 → 192.168.0.100:443
-- **Remove**: Direct port 3000 forwarding (will go through nginx)
-
-### SSL Certificates
-```bash
-# Let's Encrypt via certbot (after nginx setup)
-sudo certbot --nginx -d ak-homelab.duckdns.org
-
-# Auto-renewal
-sudo systemctl enable certbot.timer
-```
-
-## Backup Strategy
-
-### Configuration Backups
-- **Service configs**: Docker volumes, /etc configs
-- **Database dumps**: Regular automated backups
-- **Storage**: External drive or cloud backup
-
-### Automated Backups
-```bash
-#!/bin/bash
-# backup-services.sh
-DATE=$(date +%Y%m%d)
-
-# Backup Gitea
-tar -czf /backup/gitea-$DATE.tar.gz /var/lib/gitea/
-
-# Backup Nextcloud data
-rsync -av /var/snap/nextcloud/common/nextcloud/data/ /backup/nextcloud-$DATE/
-
-# Database backup
-sudo -u postgres pg_dump gitea > /backup/gitea-db-$DATE.sql
-```
-
-## Resource Planning
-
-### Hardware Requirements
-- **RAM**: 4GB minimum, 8GB recommended
-- **Storage**:
-  - System: 50GB SSD
-  - Data: 1TB+ HDD for media/files
-- **Network**: Gigabit Ethernet preferred
-
-### Service Resource Usage
-| Service | RAM | CPU | Storage | Port |
-|---------|-----|-----|---------|------|
-| Gitea | 200MB | Low | 5GB+ | 3000 |
-| Nextcloud | 512MB | Medium | 10GB+ | 8080 |
-| Jellyfin | 1GB | High* | Media | 8096 |
-| Monitoring | 500MB | Low | 2GB | 3000/9090 |
-
-*High during transcoding
-
-## Security Considerations
-
-### Service Hardening
-- **Regular updates**: Automated security patches
-- **Access control**: VPN-only access when possible
-- **Authentication**: Strong passwords, 2FA where available
-- **Network isolation**: Separate VLANs or containers
-
-### Data Protection
-- **Encryption**: Full disk encryption (LUKS)
-- **Backups**: Encrypted offsite backups
-- **Access logs**: Monitor service access patterns
-- **Fail2ban**: Automatic IP blocking for repeated failures
-
-## Future Expansion
-
-### Additional Services to Consider
-- **Home Assistant**: ABSOLUTELY NOT
-- **Bitwarden/Vaultwarden**: Password management
-  - How is this better than keepassxc + filesync?
-- **Pi-hole**: Network-wide ad blocking
-- **Wireguard UI**: Web interface for VPN management
-- **Bookstack**: Documentation wiki
-  - What is this for? How does it compare to Logseq?
-- **FreshRSS**: RSS feed aggregator
-
-## System Monitoring & Management
-
-### Overview
-
-**Status:** 🚧 **PLANNED** - Implementing hybrid monitoring and management solution
-
-**Selected Tools:**
-- **Portainer** - Docker container management (web UI with built-in auth)
-- **Glances** - Real-time system monitoring (web + terminal, nginx basic auth required)
-- **Netdata** - Real-time system monitoring with rich dashboards (web UI, nginx basic auth)
-- **lazydocker** - Terminal-based Docker management (SSH sessions)
-
-### Architecture Decision
-
-**Hybrid Approach Rationale:**
-- **SSH workflow**: lazydocker + glances terminal mode for command-line administration
-- **Web overview**: Glances for quick system status checks
-- **Real-time monitoring**: Netdata for detailed system metrics and historical data
-- **Docker UI**: Portainer for comprehensive container management
-
-### Authentication Strategy
-
-- **Portainer**: ✅ Built-in user authentication and RBAC
-- **Glances**: ⚠️ Nginx basic auth required (exposes system metrics)
-- **Netdata**: ⚠️ Nginx basic auth required (exposes system metrics, cloud features disabled)
-- **Router**: ✅ Has own administrative login
-- **NAS Storage**: ✅ Has own administrative login
-
-**Nginx basic auth implemented** for monitoring services that expose system information without built-in authentication.
-
-### Service Details
-
-#### Portainer (Docker Management)
-**Status:** 📋 **Planned**
-- **Access**: https://ak-homelab.duckdns.org/portainer/
-- **Port**: 9000 (behind reverse proxy)
-- **Authentication**: Built-in user accounts with role-based permissions
-- **Features**: Container lifecycle, image management, volume management, stack deployment
-
-#### Glances (System Monitoring)
-**Status:** 📋 **Planned**
-- **Access**: https://ak-homelab.duckdns.org/glances/ (nginx basic auth)
-- **Port**: 61208 (behind reverse proxy with auth)
-- **Authentication**: Nginx basic auth (due to no built-in authentication)
-- **Features**: Real-time CPU/RAM/disk metrics, process monitoring, network stats
-- **Terminal mode**: Available via SSH for command-line monitoring
-
-#### Netdata (Real-time System Monitoring)
-**Status:** ✅ **DEPLOYED**
-- **Access**: https://ak-homelab.duckdns.org/netdata/ (nginx basic auth)
-- **Port**: 19999 (behind reverse proxy with auth)
-- **Authentication**: Nginx basic auth (same credentials as Glances: admin/AdminPass2024!)
-- **Configuration**: Privacy-focused local-only setup with cloud features disabled
-- **Features**: Real-time system metrics, network monitoring, process tracking, historical data
-
-#### lazydocker (Terminal Docker Tools)
-**Status:** 📋 **Planned**
-- **Access**: SSH terminal only
-- **Installation**: `pacman -S lazydocker`
-- **Usage**: Command-line Docker container management for SSH workflows
-
-### URL Architecture
-
-```
-Landing Page - Admin Tab:
-Server Administration:
-├── Glances → https://ak-homelab.duckdns.org/glances/ (nginx basic auth)
-├── Netdata → https://ak-homelab.duckdns.org/netdata/ (nginx basic auth)
-└── Portainer → https://ak-homelab.duckdns.org/portainer/ (built-in auth)
-
-Local Network:
-├── NAS Storage → http://192.168.0.101:5000/ (built-in auth)
-└── Router → http://192.168.0.1 (built-in auth)
-```
-
-### Implementation Plan
-
-1. **Package Installation**
-   ```bash
-   sudo pacman -S glances cockpit lazydocker
-   ```
-
-2. **Portainer Deployment**
-   ```bash
-   docker run -d \
-     --name portainer \
-     -p 9000:9000 \
-     -v /var/run/docker.sock:/var/run/docker.sock \
-     -v portainer_data:/data \
-     portainer/portainer-ce
-   ```
-
-3. **Service Configuration**
-   - Enable Cockpit: `sudo systemctl enable --now cockpit.socket`
-   - Configure Glances web mode: `glances -w -p 61208`
-   - Create systemd service for Glances web server
-
-4. **Nginx Configuration**
-   - Add reverse proxy configurations for all services
-   - Configure basic auth for Glances endpoint
-   - SSL termination for all admin services
-
-5. **Landing Page Update**
-   - Add all admin service links to Admin tab
-   - Include authentication indicators
-
-### Security Considerations
-
-**Data Exposure Analysis (Glances):**
-- **Exposed**: System metrics, process names, resource usage, network stats
-- **Not Exposed**: File contents, passwords, configuration details, logs
-- **Risk Level**: Medium (reconnaissance data for attackers)
-- **Mitigation**: Nginx basic auth prevents unauthorized access
-
-**Service Hardening:**
-- All services behind HTTPS with SSL certificates
-- Each service handles authentication independently
-- No shared credentials between services
-- Services isolated behind reverse proxy
-
-## Remote Desktop Access
-
-### TigerVNC
-
-**Status:** ✅ **INSTALLED** - VNC server for remote desktop access
-
-**Installation:**
-```bash
-# Install TigerVNC server and client
-sudo pacman -S tigervnc
-```
-
-**Service Configuration:**
-```bash
-# Configure user for VNC display :1
-echo ":1=hoborg" | sudo tee -a /etc/tigervnc/vncserver.users
-
-# Set VNC password
-vncpasswd
-
-# Configure desktop environment (~/.vnc/xstartup)
-#!/bin/bash
-xrdb $HOME/.Xresources
-startxfce4 &
-
-# Make executable
-chmod +x ~/.vnc/xstartup
-```
-
-**Service Management:**
-```bash
-# Enable and start VNC service
-sudo systemctl enable vncserver@:1.service
-sudo systemctl start vncserver@:1.service
-
-# Check service status
-sudo systemctl status vncserver@:1.service
-
-# Service uses vncsession-start for proper X11 session management
-```
-
-**Access Details:**
-- **Display**: `:1` (port 5901)
-- **Local Access**: VNC client to `192.168.0.100:5901`
-- **External Access**: Requires router port forwarding 5901→192.168.0.100:5901
-- **Security**: Password authentication, consider SSH tunneling for external access
-
-**Client Connection:**
-- **Windows**: TigerVNC Viewer to `192.168.0.100:5901`
-- **SSH Tunnel**: `ssh -L 5901:localhost:5901 hoborg@192.168.0.100 -p 2222`
-- **Tunneled Access**: VNC client to `localhost:5901`
-
-**Service Features:**
-- ✅ Systemd integration with proper session management
-- ✅ Automatic startup on boot
-- ✅ User-specific VNC sessions via `/etc/tigervnc/vncserver.users`
-- ✅ Uses `vncsession-start` for robust X11 handling
-- ✅ Proper PID file management in `/run/vncsession-:1.pid`
-
-**Security Considerations:**
-- VNC traffic is unencrypted - use SSH tunneling for remote access
-- Firewall configuration needed for direct external access
-- Consider VPN access instead of direct port forwarding