homelab/CLAUDE.md

CLAUDE.md

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

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.

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

Service Architecture

Internet → Router → Nginx (80/443) → Services
                 → SSH (2222) → System
                 → Gitea SSH (2223) → Git operations

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/

Configuration Management

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

Configuration files include deployment instructions in comments showing target locations (e.g., /opt/docker/gitea/, /etc/nginx/sites-available/).

Key Commands

Docker Service Management

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

Copyparty File Server Management

# 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

# 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

SSL Certificate Management

sudo certbot --nginx -d ak-homelab.duckdns.org
sudo systemctl enable certbot.timer  # Auto-renewal

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.

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

• 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

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

# 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

# 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

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

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