110 lines
3.6 KiB
Markdown
110 lines
3.6 KiB
Markdown
# 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
|
||
```json
|
||
{"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
|
||
```json
|
||
{"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
|
||
```json
|
||
{"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
|
||
```json
|
||
{"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
|