Connecting PocketBase

Orb uses PocketBase to store access keys and check every incoming request. Set it up before creating keys.

1. Run PocketBase on the same machine

PocketBase 0.41.x is the version this was written against. Start it on loopback with the gateway’s data, hooks and migrations directories:

pocketbase serve \
  --http=127.0.0.1:8090 \
  --dir=pb_data \
  --hooksDir=pb_hooks \
  --migrationsDir=pb_migrations

Keep it on 127.0.0.1. Its admin UI is where keys are managed.

2. Point Orb at it

There is no environment variable or config key for this. The address lives in the Caddyfile, in the token_check snippet:

forward_auth 127.0.0.1:8090 {
    uri /gw/check?service={args[0]}
    copy_headers X-Gw-Token X-Upstream-Auth
}

If PocketBase runs somewhere else, change it there and reload Caddy. The admin UI is at http://127.0.0.1:8090/_/.

3. Create the collections

Nothing to create by hand. The migrations in pb_migrations/ create tokens (keys, scopes, limits) and token_events (the request log), and PocketBase applies them at startup. The hook in pb_hooks/gateway.pb.js adds the scope options for every service in both manifests when it boots.

If the scopes field is missing a service, the hook did not see the manifest. Restart PocketBase and check its log.

What a failed check does

Every request goes through PocketBase before Caddy forwards it. If PocketBase is not answering, the check cannot complete and Caddy refuses the request: traffic fails closed instead of passing through. A request with no token gets 401, a revoked or expired token 403, a token without the scope 403, and a token over its rate limit 429.