# albok-service — fleet knowledgebase service (nh3-docker)

The FastAPI process that owns Albok's buildings-and-wings store (`vh/albok`,
`packages/albok-service`, contract `docs/contracts/unit2_service.contract.md`). It is the
**only writer** of the store. Deployed 2026-10-02 at albok-dev's request (operator-approved).

- **URL:** `http://albok.nh3.internal:8392` (= `http://10.100.50.40:8392`). Container port 8390.
  ⚠ Host port **8392**, because **8390 on nh3-docker is the althing post office**.
- **Image:** `gitea.phasefinal.com/pfi/albok-service:0.1.1` @ `sha256:33e4e98a…` (pinned in
  `compose.yaml`), built from vh/albok `e349d50` (tag albok-service/v0.1.1; albok core 0.1.1). 0.1.0 (`0b37431`) ran 2026-10-02 1754–1805.
- **Health:** `GET /health` (no auth) → `"status": "ok"` on 0.1.1. (0.1.0 always said `degraded`: its
  canary reports `alive` and the check expected `ok`; fixed in 0.1.1.) The Docker healthcheck checks HTTP 200.
- **0.1.1 also accepts numeric `default_gid` / `gid` in the config**, which would make the mounted
  `/etc/group` unnecessary. The current name-based config stays valid, so it is left as is.

## Pieces and where they live

| What | Where |
|---|---|
| store root (one git repo per wing) | `/srv/albok/store` — local ext4, `albok:albok` 0711 |
| private root (lease, journal, tokens.db, per-wing chroma) | `/srv/albok/private` — local ext4, `albok:albok` 0700, **single-attach** |
| config (holds the embedder key) | `/srv/albok/etc/albok.yaml` — `root:albok` 0640; rendered from `conf/albok.yaml.template` |
| container `/etc/group` | `/opt/docker/conf/albok-service/group` (= `conf/group`) |
| compose | `/opt/docker/compose/albok-service/compose.yaml` |

**Identities (fixed numeric ids, created by `playbooks/albok-service-host.yaml`):** user and group
`albok` 1500:1500 (the image's user), read groups `albok-read` **1510** (building `fleet`) and
`albok-personal` **1511** (building `personal`). Reserve 1512+ for restricted wings (agent-feedback,
vault) and add each to the host, `conf/group` and `group_add`.

**Why the group file and `group_add`:** the service resolves group NAMES with `grp.getgrnam()`
inside the container and `chgrp`s wing dirs as uid 1500. Without the names in the container's
`/etc/group` it reports "group does not resolve", and without membership the chgrp is refused.
Verified: wings came up `drwxr-s--- albok:albok-read` / `albok:albok-personal`, drift 0.

**Secrets (vault):** `albok/litellm-key`, a LiteLLM key scoped to `qwen3-embedding` only (alias
`albok-service`; verified 200 on embeddings, 403 on any other model); `albok/bootstrap-admin-token`,
the first-start admin token (also at `/srv/albok/private/bootstrap-admin-token`, 0600).

**Backups:** nh3-docker is VM 100 on nh3-pve, in the nightly 21:00 vzdump (snapshot mode → pbs-ana),
so `/srv/albok` is covered whole-VM. No file-level restic job for it.

## Deploy / redeploy

```bash
# 1. host prep (idempotent)
scripts/elway infra-ops@10.100.50.40 --playbook playbooks/albok-service-host.yaml
# 2. config: render the template with the vaulted key (never commit the rendered file)
umask 077; secret get albok/litellm-key | tr -d '\n' | python3 -c "import sys; k=sys.stdin.read(); \
  open('/tmp/albok.yaml','w').write(open('stacks/albok-service/conf/albok.yaml.template').read().replace('__ALBOK_LITELLM_KEY__', k))"
scripts/elway infra-ops@10.100.50.40 --upload /tmp/albok.yaml:/srv/albok/etc/albok.yaml:0640 --sudo --owner root:albok
# then delete /tmp/albok.yaml by its literal path
# 3. compose + conf, then start (root holds the registry login on nh3-docker)
scripts/deploy-stack.sh nh3-docker albok-service
ssh infra-ops@10.100.50.40 'cd /opt/docker/compose/albok-service && sudo docker compose up -d'
```

**Image rebuild** (from a clean archive, never a working tree):

```bash
git -C ~/development/albok archive <sha> | tar -x -C <scratch>
cd <scratch> && docker build -f packages/albok-service/Dockerfile -t gitea.phasefinal.com/pfi/albok-service:<ver> .
secret get nh3-dev/.config/claude-bot/gitea-token-sdkops | docker login gitea.phasefinal.com -u claude-bot --password-stdin
docker push gitea.phasefinal.com/pfi/albok-service:<ver>     # then pin the new digest in compose.yaml
```

## Viewers (read-only access to the store)

Mount `/srv/albok/store` **`:ro`**, `group_add` the read group's **numeric** gid (1510 / 1511), set
`GIT_OPTIONAL_LOCKS=0`, and add `safe.directory` for the path as the viewer sees it. Nothing else
may mount the store read-write.