# `backend_api` role — runtime baseline for the Go API container

Multi-instance scaffolding for the Go backend API behind HAProxy. v1.0.9 W4 Day 19 — phase-1 of the active/active deploy story.

## What this role DOES

- Creates the `veza-api` system user.
- Lays down `/opt/veza/backend-api`, `/etc/veza`, `/var/log/veza`.
- Renders a hardened systemd unit pointing at the binary path.
- Idempotent ; safe to re-apply against an already-running instance.

## What this role does NOT do (deliberately)

- **Build / copy the Go binary.** That happens out-of-band : a `make backend-api-deploy` target builds the binary on the dev host and pushes it via `incus file push backend-api-X /opt/veza/backend-api/veza-api`. CI integration (Forgejo job → ansible-pull) is W5+ work.
- **Render `.env`.** Secrets live in `group_vars/backend_api.vault.yml` (encrypted) and are pushed by a separate task in `playbooks/backend_api.yml` ; they don't belong in this role's defaults.
- **Run database migrations.** Migrations are gated by a CI job — running them via Ansible would race with multi-instance deploys.

## Deploying the binary (one-shot, until CI lands)

```bash
# On the dev host :
make -C veza-backend-api build  # produces ./bin/veza-api
for ct in backend-api-1 backend-api-2; do
  incus file push veza-backend-api/bin/veza-api "$ct"/opt/veza/backend-api/veza-api \
    --uid 1001 --gid 1001 --mode 0755
  incus exec "$ct" -- systemctl restart veza-backend-api
done
```

Roll one container at a time so HAProxy never sees both backends down.

## Defaults

| variable                    | default                          | meaning                         |
| --------------------------- | -------------------------------- | ------------------------------- |
| `backend_api_user`          | `veza-api`                       | system user                     |
| `backend_api_install_dir`   | `/opt/veza/backend-api`          | binary + working dir            |
| `backend_api_binary_name`   | `veza-api`                       | binary basename                 |
| `backend_api_listen_port`   | `8080`                           | matches HAProxy upstream config |
| `backend_api_env_file`      | `/etc/veza/backend-api.env`      | EnvironmentFile= path           |
| `backend_api_log_dir`       | `/var/log/veza`                  | tail-friendly log dir           |