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

Comment out the "Login to Gitea registry" task in roles/podman/tasks/main.yml, then run without the homekeeper role:

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:

# 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

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:

ssh root@YOUR_IP podman auto-update

Secrets management

For production, use ansible-vault:

ansible-vault encrypt_string 'mysecretpassword' --name 'db_password'

Paste the output into group_vars/all.yml and run playbooks with --ask-vault-pass.

2.9 KiB Raw Blame History