claude-home/server-configs/README.md

Home Lab Server Configurations

Version-controlled configuration files for the home lab infrastructure. This system provides a centralized way to track, sync, and deploy Docker Compose files and VM/LXC configurations across multiple hosts.

Quick Start

# Check status of all hosts
./sync-configs.sh status

# Pull latest configs from all hosts
./sync-configs.sh pull

# Pull from a specific host
./sync-configs.sh pull ubuntu-manticore

# Show differences between local and remote
./sync-configs.sh diff

# Push configs (no restart)
./sync-configs.sh push

# Deploy and restart a specific service
./sync-configs.sh deploy sba-bots paper-dynasty

Directory Structure

server-configs/
├── hosts.yml              # Host inventory with connection details
├── sync-configs.sh        # Main sync script
├── .gitignore             # Prevents secrets from being committed
├── README.md              # This file
│
├── proxmox/               # Proxmox hypervisor configs
│   ├── lxc/               # LXC container configurations
│   └── qemu/              # VM configurations
│
├── ubuntu-manticore/      # Physical Ubuntu server
│   └── docker-compose/
│       ├── jellyfin/
│       ├── tdarr/
│       └── watchstate/
│
├── sba-bots/              # SBA Discord bots VM
│   └── docker-compose/
│       ├── paper-dynasty/
│       ├── major-domo/
│       └── ...
│
├── strat-database/        # Database services VM
│   └── docker-compose/
│       ├── pd-database/
│       ├── sba-database/
│       └── ...
│
├── arr-stack/             # Media automation LXC
│   └── docker-compose/
│       └── arr-stack/
│
├── n8n/                   # Workflow automation LXC
│   └── docker-compose/
│       └── n8n/
│
├── akamai/                # Cloud server (Linode)
│   └── docker-compose/
│       ├── nginx-proxy-manager/
│       ├── major-domo/
│       └── ...
│
└── nobara-desktop/        # Local dev machine
    └── docker-compose/

Host Inventory

Host	Type	IP	Description
proxmox	Proxmox VE	10.10.0.11	Main hypervisor (VMs/LXCs)
ubuntu-manticore	Docker	10.10.0.226	Physical server - media services
discord-bots	Docker	10.10.0.33	Discord bots and game services
sba-bots	Docker	10.10.0.88	SBA/Paper Dynasty production
strat-database	Docker	10.10.0.42	Database services
arr-stack	Docker	10.10.0.221	Sonarr/Radarr/etc.
n8n	Docker	10.10.0.210	Workflow automation
akamai	Docker	172.237.147.99	Public-facing services
nobara-desktop	Local	-	Development workstation

Commands Reference

./sync-configs.sh pull [host]

Pulls Docker Compose files from remote hosts to the local repository. Only syncs docker-compose*.yml, compose.yml, and .env.example files - not application data.

./sync-configs.sh push [host]

Pushes local configs to remote hosts. Does NOT restart services. Use this to stage changes before deployment.

./sync-configs.sh diff [host]

Shows differences between local repository and remote host configurations.

./sync-configs.sh deploy <host> <service>

Pushes config for a specific service and restarts it. Example:

./sync-configs.sh deploy sba-bots paper-dynasty

./sync-configs.sh status

Shows connectivity status and config count for all hosts.

./sync-configs.sh list

Lists all configured hosts and their services.

Secrets Management

Secrets are NOT stored in this repository.

All sensitive values (tokens, passwords, API keys) are referenced via environment variables (${VAR_NAME}) and stored in .env files on each host. The .gitignore prevents .env files from being committed.

For each service that requires secrets, a .env.example file is provided showing the required variables:

# Example .env.example
BOT_TOKEN=your_discord_bot_token_here
API_TOKEN=your_api_token_here
DB_PASSWORD=your_database_password_here

When deploying a new service:

1. Copy .env.example to .env on the target host
2. Fill in the actual secret values
3. Run docker compose up -d

Workflow

Making Configuration Changes

1. Pull latest to ensure you have current configs:

   ./sync-configs.sh pull
   

2. Edit locally in your preferred editor

3. Review changes before pushing:

   ./sync-configs.sh diff <host>
   

4. Push changes to the host:

   ./sync-configs.sh push <host>
   

5. Deploy when ready to restart:

   ./sync-configs.sh deploy <host> <service>
   

6. Commit to git:

   git add -A && git commit -m "Update <service> config"
   

Adding a New Host

1. Add host entry to hosts.yml:

   new-host:
     type: docker
     ssh_alias: new-host
     ip: 10.10.0.XXX
     user: cal
     description: "Description here"
     config_paths:
       docker-compose: /path/to/compose/files
     services:
       - service1
       - service2
   

2. Add SSH alias to ~/.ssh/config if needed

3. Create directory and pull:

   mkdir -p server-configs/new-host/docker-compose
   ./sync-configs.sh pull new-host
   

Adding a New Service

1. Create the service on the host with docker-compose.yml
2. Pull the config:

   ./sync-configs.sh pull <host>
   

3. Sanitize any hardcoded secrets (replace with ${VAR} references)
4. Create .env.example if secrets are required
5. Commit to git

Proxmox Configs

Proxmox VM and LXC configurations are pulled for reference and backup purposes. The sync script does NOT push Proxmox configs back automatically due to the sensitive nature of hypervisor configuration.

To restore a VM/LXC config:

1. Review the config file in proxmox/qemu/ or proxmox/lxc/
2. Manually copy to Proxmox if needed
3. Use Proxmox web UI or CLI for actual restoration

Troubleshooting

Host shows as offline

• Check if the VM/LXC is running on Proxmox
• Verify SSH connectivity: ssh <host-alias>
• Check hosts.yml for correct IP/alias

Changes not taking effect

• Ensure you ran push after editing
• Check if service needs restart: deploy command
• Verify the remote file was updated: diff command

Permission denied on push

• Check SSH key is loaded: ssh-add -l
• Verify user has write access to config directory
• For root-owned paths (arr-stack, n8n), ensure SSH alias uses correct user

Related Documentation

• Tdarr Setup - Media transcoding configuration
• Networking - NPM and network config
• Monitoring - System monitoring setup