93 lines
3.6 KiB
Markdown
93 lines
3.6 KiB
Markdown
# 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
|