# keep fleet setup — personal notes (copy to SETUP.local.md, gitignored)

Fill this in as you actually run the commands. It's your own record of
what recipient id belongs to which machine and which vault backs which
project — none of this is secret by itself (a recipient id or a vault
key doesn't grant access without the matching private key), but it's
real fleet topology that doesn't belong in a public repo.

## 0. Server

- [ ] Deployed at: `___________________` (e.g. https://keep.example.internal)
- [ ] `ADMIN_PASSWORD` stored in: `___________________` (password manager entry, not here)
- [ ] `KEEP_SERVER_URL` exported in shell profile on every machine below

## 1. Identities

One row per machine. `keep identity init` prints the public key; an
admin runs `keep recipient add`, which prints back a recipient id; that
id gets recorded locally with `keep identity set-id <id>`.

| Machine | Recipient id | Grant type (per vault, see §3) |
|---|---|---|
| this laptop | `___________________` | rw on everything it pushes |
| vps-1 (`___________________` hostname) | `___________________` | r- (read-only) |
| vps-2 | `___________________` | r- (read-only) |

Commands, run once per machine:

```bash
keep identity init                                          # on the machine itself
KEEP_ADMIN_PASSWORD=... keep recipient add --label "<name>" --pubkey <hex>   # from an admin machine
keep identity set-id <recipient-id>                          # back on the machine itself
```

## 2. Projects → vaults

One vault per project+environment. Vault key is a free-form string —
it does NOT need to match the repo name or the deploy directory name
(see IMPLEMENTATION.md — these are three independent strings in this
fleet on purpose).

| Project | Deploy dir | Vault key | `.keep-vault` written? |
|---|---|---|---|
| myapp | `/opt/docker/myapp` | `myapp/production` | [ ] |
| otherapp | `/opt/docker/otherapp` | `otherapp/production` | [ ] |

Bootstrap a project:

```bash
keep push myapp/production --file .env.production      # from the laptop, becomes rw grantee
keep grant myapp/production <vps-1-recipient-id> --read-only
echo "myapp/production" > /opt/docker/myapp/.keep-vault  # on vps-1, next to its docker-compose.yml
```

Or use `scripts/bootstrap-project.sh` (see below) to do the push+grant
step in one call for multiple VPS recipients at once.

## 3. CI announce (optional, per project)

Only needed if you want `keep watch` on a VPS to skip waiting for the
next scheduled sweep. Add to that project's own
`.gitea/workflows/docker.yml`, after the build-and-push step:

```yaml
- name: announce to keep
  continue-on-error: true
  run: keep announce myapp/production --tag ${{ steps.meta.outputs.short_sha }}
```

The vault key here must be the literal string from §2's table — not
derived from the repo name.

## 4. Sanity check

```bash
KEEP_ADMIN_PASSWORD=... keep overview
```

Confirm every project vault shows up with exactly the grants you
expect — laptop `rw`, each deploying VPS `r-`, nothing else.