homelab/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

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

• 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:

/opt/docker/<service>/docker-compose.yml → ~/homelab/config/docker/<service>/docker-compose.yml

Editing the repo file is editing the live config. Restart the container to apply changes.

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).

Sudo Access

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

cd /opt/docker/<service>
docker compose logs -f          # View logs
docker compose restart          # Restart
docker compose down && docker compose up -d  # Full restart

Nginx

sudo nginx -t                   # Test config
sudo systemctl reload nginx     # Reload (use restart for major changes)

Systemd Services

sudo systemctl status nginx copyparty
sudo systemctl restart <service>

Development Workflow

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

Documentation Structure

• 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)

For detailed install steps per service, see docs/services.md.

Security Hardening Guidelines

• 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 go through localhost proxy

Claude Development Guidelines

CRITICAL: Anti-Pattern Reminders

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

• ❌ Broken syntax without testing commands first
• ❌ Switching solutions mid-implementation
• ❌ Overcomplicating when simple solutions exist
• ❌ Installing random scripts before checking packages

Success Pattern

• ✅ Research → Choose → Verify syntax → Implement → Test
• ✅ pacman → AUR → GitHub (preference order)
• ✅ Use proven, maintained tools over custom scripts