CLAUDE.md

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

Overview

This is an Infrastructure as Code repository for a Docker-based homelab. It uses Ansible to manage Docker Compose deployments across multiple VMs and LXC containers on Proxmox.

Common Commands

# Run from the repository root: ~/clustered-fucks

# Check status of all managed hosts (disk, memory, containers)
ansible-playbook playbooks/check-status.yml

# Deploy compose files to hosts (generic deployment)
ansible-playbook playbooks/deploy-compose.yml                           # All hosts, all stacks
ansible-playbook playbooks/deploy-compose.yml --limit databases         # Single host
ansible-playbook playbooks/deploy-compose.yml -e stack_filter=mealie    # Specific stack
ansible-playbook playbooks/deploy-compose.yml -e restart_stacks=true    # Deploy and restart

# Deploy specific service
ansible-playbook playbooks/deploy-<service>.yml

# Run ad-hoc commands on hosts
ansible docker_hosts -m ping                                             # Test connectivity
ansible docker_hosts -m shell -a "docker ps -q | wc -l"                  # Container counts
ansible databases -m shell -a "docker logs mealie 2>&1 | tail -30"       # View logs

# Maintenance
ansible-playbook playbooks/update-all.yml                               # apt upgrade all docker hosts
ansible-playbook playbooks/docker-prune.yml                             # Clean unused Docker resources
ansible-playbook playbooks/restart-utils.yml                            # Restart autoheal/watchtower/portainer

Architecture

Host Organization

Services are organized by deployment target in compose-files/<hostname>/<service>/:

Host	IP Suffix	Type	Primary Services
replicant	.80	VM	Arr stack, Emby, Navidrome, Homepage
databases	.81	VM	PostgreSQL, Forgejo, Mealie
immich	.82	VM	Immich photo management
network-services	.121	LXC	Unifi, Docker proxy
download-stack	.122	LXC	NZBGet, ruTorrent, slskd
docker666	.123	LXC	Gluetun, misc services

Ansible Groups

docker_hosts - All VMs + LXCs (primary deployment targets)
all_managed - Everything including Proxmox nodes
proxmox_nodes - Hypervisors only
legacy - Systems being migrated (nas, alien)

Deployment Pattern

Compose files stored in compose-files/<host>/<service>/docker-compose.yml
Secrets in .env files (not in git, copied via playbooks)
Service-specific playbooks in playbooks/deploy-<service>.yml
Default appdata path on hosts: /home/docker/appdata/<service>/
Shared Docker networks: proxy, media, download, database

Service Dependencies

Immich and Mealie depend on PostgreSQL on the databases VM
All docker hosts run the utils stack (autoheal, watchtower, portainer-agent)
Media services share NFS mounts from Synology NAS at 192.168.1.251

Creating New Deployments

# 1. Create compose directory
mkdir -p compose-files/<target_host>/<service>

# 2. Add docker-compose.yml and .env (secrets)

# 3. Create playbook (use existing deploy-*.yml as template)
# Key pattern: copy compose + .env, ensure network exists, docker compose up -d

# 4. Deploy
ansible-playbook playbooks/deploy-<service>.yml

Key Files

ansible.cfg - Ansible config (inventory path, SSH settings, fact caching)
inventory/hosts.yml - All managed hosts with IPs and connection settings
inventory/group_vars/all.yml - Global variables (timezone, NAS paths, ntfy topics)
docs/control-server-guide.md - Detailed operations guide

3.6 KiB Raw Blame History