mirror of
https://github.com/block/buzz.git
synced 2026-11-01 06:51:17 +00:00
6636ce9f68
The published contract named a `trusted-proxy-hmac-v1` profile that no implementation accepts. This replaces it with `trusted-proxy-hmac-v2` as the sole stock proxy transport, specified from the wire format: envelope layout, length-prefixed MAC input, canonical encodings, discovery identifier, replay namespace, and lease bounds, with negative vectors. Denial handling is re-scoped. The no-mutation invariant now covers authoritative authorization state only, and denial observability moves to a separately bounded, non-authoritative channel carrying reason codes and correlation identifiers under payload minimization. A denied admission creates no authorization receipt, and a failed observation write never blocks, retries, or latches the denial. Runtime operations, deployment, and integration guidance is framed as future contract rather than current behavior. Subject stability is stated as a verifier trust assumption with its reassignment consequence, and the key-snapshot rollback claim is narrowed to what the model enforces. This is a documentation change. It adds no runtime parser, adapter, or enforcement path. Session-path rechecks and the policy digest input set remain relay-side follow-ups. The 24 trace and 16 invariant identifiers are unchanged.
81 lines
3.3 KiB
Markdown
81 lines
3.3 KiB
Markdown
# Buzz Docker Compose deployment
|
|
|
|
This is the single-node/VPS deployment bundle. It is intentionally separate from
|
|
the root `docker-compose.yml`, which remains local development infrastructure.
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
cd deploy/compose
|
|
cp .env.example .env
|
|
$EDITOR .env # replace every CHANGE_ME value
|
|
./run.sh start
|
|
```
|
|
|
|
For a public VPS with automatic Let's Encrypt certificates:
|
|
|
|
```bash
|
|
cd deploy/compose
|
|
BUZZ_COMPOSE_TLS=true ./run.sh start
|
|
```
|
|
|
|
The bootstrap script should eventually replace manual `.env` editing for normal
|
|
users. It is responsible for generating stable secrets and, optionally, an owner
|
|
keypair.
|
|
|
|
## Production notes
|
|
|
|
- Requires Docker Compose v2.24.4 or newer; the TLS override uses Compose's
|
|
`!reset` tag to remove the direct relay port when Caddy terminates HTTPS.
|
|
- Default `BUZZ_IMAGE` tracks `ghcr.io/block/buzz:main` for early testing. Pin it to `ghcr.io/block/buzz:sha-<7>` or a semver release tag for production once available.
|
|
- Keep `BUZZ_RELAY_PRIVATE_KEY`, `BUZZ_GIT_HOOK_HMAC_SECRET`, database/Redis,
|
|
and S3 secrets stable across restarts.
|
|
- `RELAY_OWNER_PUBKEY` is intentionally not prefixed with `BUZZ_`; it must be a
|
|
64-character hex Nostr pubkey when closed relay mode is enabled.
|
|
- `BUZZ_AUTO_MIGRATE` is opt-in. Set `BUZZ_AUTO_MIGRATE=true` or run
|
|
`buzz-admin migrate` before starting the relay when bootstrapping a fresh
|
|
database. Auto-migration requires an image that includes embedded SQLx
|
|
migrations.
|
|
- PostgreSQL must allow the `pgcrypto` extension — schema bootstrap and
|
|
migrations run `CREATE EXTENSION IF NOT EXISTS pgcrypto` (used for
|
|
`gen_random_uuid()` and digest hashing). On managed PostgreSQL, ensure the
|
|
extension is permitted for the migration role or pre-create it as an
|
|
administrator.
|
|
- The proposed NIP-FI configuration contract is future-facing; this bundle
|
|
does not imply that the current relay parses or enforces it. See the
|
|
[identity configuration contract](../../docs/CORPORATE_IDENTITY.md).
|
|
- The stack uses Postgres, Redis, MinIO, and a git data volume because
|
|
those are real Buzz dependencies today. Minimal mode can simplify this later.
|
|
|
|
Run `./run.sh backup-hint` for the backup checklist.
|
|
|
|
## NIP-FI readiness
|
|
|
|
This Compose bundle does not provision a NIP-FI runtime, trusted edge, issuer
|
|
integration, or conformance runner. It makes no claim that the proposed
|
|
`BUZZ_NIP_FI_V1_CONFIG_JSON` document is parsed or enforced. Do not advertise
|
|
or enforce NIP-FI from this bundle, and do not add a provider-specific sidecar
|
|
or unsigned corporate identity header as a substitute.
|
|
|
|
An activating deployment must pin an exact image, isolate verifier ingress
|
|
when `trusted-proxy-hmac-v2` is enabled, deliver HMAC secrets through a
|
|
secret store rather than `.env`, and pass the complete exact-head behavioral
|
|
matrix before activation. A valid Compose render or healthy relay does not
|
|
close those gates. See the
|
|
[provider-neutral deployment guide](../../docs/NIP_FI_DEPLOYMENT.md) and
|
|
[runtime operations guide](../../docs/NIP_FI_RUNTIME_OPERATIONS.md).
|
|
|
|
## Validation
|
|
|
|
Before sharing an install link publicly, verify a fresh install with:
|
|
|
|
```bash
|
|
cd deploy/compose
|
|
cp .env.example .env
|
|
$EDITOR .env
|
|
./run.sh config
|
|
./run.sh start
|
|
curl -fsS "http://127.0.0.1:$(grep -E '^BUZZ_HTTP_PORT=' .env | cut -d= -f2-)/_liveness"
|
|
./run.sh status
|
|
```
|