# 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`.