sascha/homelab-butler
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
homelab-butler/README.md

3.6 KiB
Raw Blame History

Homelab Butler 🤵

Unified API proxy + infrastructure management for Homelab Pfannkuchen.

Base URL: http://10.4.1.116:8888 Auth: Authorization: Bearer *** Version: 2.1.0

Service Proxy

Proxies requests to backend services with automatic authentication:

Service Backend Auth
dockhand 10.4.1.116:3000 Session
sonarr 10.2.1.100:8989 API Key
radarr 10.2.1.100:7878 API Key
seerr 10.2.1.100:5055 API Key
outline 10.1.1.100:3000 Bearer
n8n 10.4.1.113:5678 X-N8N-API-KEY
proxmox 10.5.85.11:8006 PVE Token
homeassistant 10.10.1.20:8123 Bearer
grafana 10.1.1.111:3000 Bearer
uptime 159.69.245.190:3001 Bearer
waha 10.4.1.110:3500 API Key
forgejo 10.4.1.116:3001 Bearer
semaphore 10.4.1.116:8090 Bearer

Usage: GET/POST/PUT/DELETE /{service}/{path}

VM Lifecycle

Endpoint Method Description
/vm/list GET All VMs across all 7 Proxmox nodes
/vm/create POST Full VM deployment (~10 min): ISO build, VM create, SSH wait, inventory, Ansible
/vm/status/{vmid} GET VM status (CPU, RAM, uptime)
/vm/{vmid} DELETE Destroy VM

POST /vm/create

{"node": 5, "ip": "10.5.1.115", "hostname": "lychee", "cores": 2, "memory": 4096, "disk": 32}

Steps: iso-builder → Proxmox VM → wait SSH → add to pfannkuchen.ini → Ansible base setup (Docker, Borgmatic, Hawser)

Ansible / Inventory

Endpoint Method Description
/inventory/host POST Add host to pfannkuchen.ini (idempotent, with group)
/ansible/run POST Run Ansible playbook on host

POST /ansible/run

{"hostname": "lychee"}

Post-Run Automation (after successful Ansible):

  1. Hawser Token Sync – Reads /etc/hawser/config from VM, syncs token to Dockhand environment
  2. SOPS + .env Setup – If compose.yaml exists in /app-config/github/{hostname}/:
    • Generates secure secrets (admin password, DB password, secret key)
    • Creates .env file with service-specific variables
    • Encrypts to .env.enc using SOPS (Age key from automation1)
    • Copies both files to VM's git repo directory
    • Stores secrets in Butler vault cache for future reference

POST /inventory/host

{"name": "lychee", "ip": "10.5.1.115", "group": "auto"}

TTS / Speech

Endpoint Method Description
/tts/speak POST Text-to-speech via Chatterbox
/tts/voices GET Available voices
/tts/health GET Speaker + Chatterbox status

POST /tts/speak

{"text": "Hallo!", "target": "speaker"}
  • "target": "speaker" → plays on Pi5 speaker (10.10.1.166)
  • "target": "telegram" → generates OGG on hermes, use MEDIA:/tmp/trulla_voice.ogg

Credentials

Reads from Vaultwarden cache (synced by host cron) with flat-file fallback (/data/api/).

Stack

docker compose build && docker compose up -d

Requires:

  • .env with BUTLER_TOKEN
  • /app-config/kiro/api/ flat-file credentials
  • SSH key mount (/home/sascha/.ssh:/root/.ssh:ro) for VM operations

Changelog

v2.1.0 (22.04.2026)

  • ✅ Hawser Token Auto-Sync – After /ansible/run, reads token from VM and updates Dockhand environment
  • ✅ SOPS + .env Automation – Auto-generates and encrypts environment files for Git-centric deployments
  • ✅ Service Detection – Recognizes Paperless-ngx and other services from hostname, generates appropriate env vars

v2.0.0

  • Initial unified API proxy release