add homekeeper stack

2026-07-06 19:25:38 +02:00
commit 58983e6855
90 changed files with 6816 additions and 0 deletions
@@ -0,0 +1,90 @@
+# Homekeeper Infrastructure
+
+Ansible setup for a Hetzner VM (Ubuntu 24.04) running Homekeeper via Podman.
+
+## Architecture
+
+```
+nginx (system)          ← HTTPS, routes by path
+├── /                   ← static landing page (/var/www/html)
+├── /gitea/             → Gitea on :3000 (git + container registry)
+├── /api/               → homekeeper-api on :8000
+├── /beekeeper/         → homekeeper-beekeeper on :3838
+└── /listkeeper/        → homekeeper-listkeeper on :3839
+
+Podman (rootful, Quadlets → systemd units)
+├── homekeeper-db       postgres:17, data at /opt/homekeeper/pg_data
+├── homekeeper-api      from Gitea registry, auto-update enabled
+├── homekeeper-beekeeper  from Gitea registry, auto-update enabled
+└── homekeeper-listkeeper from Gitea registry, auto-update enabled
+
+gitea container         from docker.io, auto-update disabled
+```
+
+## First-time setup
+
+### 1. Provision a Hetzner VM
+- Ubuntu 24.04, min. CX22 (2 vCPU, 4 GB RAM)
+- Add your SSH key in Hetzner console
+- Point your domain DNS A-record to the VM IP
+
+### 2. Configure variables
+Edit `group_vars/all.yml`:
+- Set `domain`
+- Set all `CHANGE_ME` passwords (consider `ansible-vault encrypt_string`)
+- Update `inventory/hosts.yml` with the VM IP
+
+### 3. First run (without registry login — Gitea not yet up)
+Comment out the "Login to Gitea registry" task in `roles/podman/tasks/main.yml`,
+then run without the homekeeper role:
+
+```bash
+ansible-playbook -i inventory/hosts.yml site.yml --skip-tags homekeeper
+```
+
+### 4. Set up Gitea
+- Visit https://git.friessn.de/ and complete the installation wizard
+- Create user matching `gitea_admin_user`
+- Create a repository for the code
+- Generate an API token (Settings → Applications) with `package:write` scope
+- Set `registry_token` in `group_vars/all.yml`
+
+### 5. Push images to Gitea registry
+On your local machine, build and push the three custom images:
+
+```bash
+# Login to Gitea registry
+docker login git.friessn.de -u nico
+
+# Build and push
+docker build -t git.friessn.de/nico/homekeeper-api:latest ./api
+docker build -t git.friessn.de/nico/homekeeper-beekeeper:latest ./beekeeper
+docker build -t git.friessn.de/nico/homekeeper-listkeeper:latest ./listkeeper
+
+docker push git.friessn.de/nico/homekeeper-api:latest
+docker push git.friessn.de/nico/homekeeper-beekeeper:latest
+docker push git.friessn.de/nico/homekeeper-listkeeper:latest
+```
+
+### 6. Full playbook run
+```bash
+ansible-playbook -i inventory/hosts.yml site.yml
+```
+
+## Deploy updates
+
+After pushing a new image to the Gitea registry, `podman auto-update` picks it up
+automatically within `autoupdate_schedule` (default: every 15 minutes).
+
+For an immediate deploy:
+```bash
+ssh root@YOUR_IP podman auto-update
+```
+
+## Secrets management
+
+For production, use ansible-vault:
+```bash
+ansible-vault encrypt_string 'mysecretpassword' --name 'db_password'
+```
+Paste the output into `group_vars/all.yml` and run playbooks with `--ask-vault-pass`.