# 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

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

1. Compose files stored in `compose-files/<host>/<service>/docker-compose.yml`
2. Secrets in `.env` files (not in git, copied via playbooks)
3. Service-specific playbooks in `playbooks/deploy-<service>.yml`
4. Default appdata path on hosts: `/home/docker/appdata/<service>/`
5. 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

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

## Additional Context Paths

The following external directories are part of this project's context:

- `~/scripts/` - Utility scripts for homelab management (add-host.sh, control-menu.sh, ssh-manager.sh, sync-dyno.sh)