This is the single-node/VPS deployment bundle. It is intentionally separate from
the root docker-compose.yml, which remains local development infrastructure.
cd deploy/compose
cp .env.example .env
$EDITOR .env # replace every CHANGE_ME value
./run.sh startFor a public VPS with automatic Let's Encrypt certificates:
cd deploy/compose
BUZZ_COMPOSE_TLS=true ./run.sh startThe bootstrap script should eventually replace manual .env editing for normal
users. It is responsible for generating stable secrets and, optionally, an owner
keypair.
Compose defaults to the exact relay release ghcr.io/block/buzz:0.3.0.
A BUZZ_IMAGE already set in .env takes precedence over that default.
To upgrade to a newer release, set BUZZ_IMAGE in .env to its exact relay
image tag, then run ./run.sh upgrade. For rolling test builds, set
BUZZ_IMAGE=ghcr.io/block/buzz:main.
- Requires Docker Compose v2.24.4 or newer; the TLS override uses Compose's
!resettag to remove the direct relay port when Caddy terminates HTTPS. - Keep
BUZZ_RELAY_PRIVATE_KEY,BUZZ_GIT_HOOK_HMAC_SECRET, database/Redis, and S3 secrets stable across restarts. RELAY_OWNER_PUBKEYis intentionally not prefixed withBUZZ_; it must be a 64-character hex Nostr pubkey when closed relay mode is enabled.BUZZ_AUTO_MIGRATEis opt-in. SetBUZZ_AUTO_MIGRATE=trueor runbuzz-admin migratebefore starting the relay when bootstrapping a fresh database. Auto-migration requires an image that includes embedded SQLx migrations.- The stack uses Postgres, Redis, MinIO, and a git data volume because those are real Buzz dependencies today. Minimal mode can simplify this later.
- Mobile push remains off by default. To use the public gateway, keep the
template's explicit
BUZZ_PUSH_GATEWAY_DELIVERY_URLand setBUZZ_PUSH_ENABLED=true. To use another gateway, replace the exact HTTPS/v1/deliveries/apnsURL before enabling push. Newer gateways and relays also accept the platform-neutral/v1/deliveriesroute; the template stays on/v1/deliveries/apnsuntil the public gateway and a relay release both support it. - The bundled Compose stack fixes the relay endpoint to
http://minio:9000andBUZZ_S3_ADDRESSING_STYLE=path: Docker DNS resolvesminio, not<bucket>.minio. It is not configurable for an external S3 provider through.env; use the Helm chart or a custom Compose configuration for providers such as new Railway Storage Buckets that requirevirtualaddressing.
Run ./run.sh backup-hint for the backup checklist.
Bundled object storage uses Silo, a maintained
MinIO fork, with matching pgsty/silo and pgsty/mc release images pinned by
multi-platform digest. Both images allow anonymous pulls and support Linux
amd64 and arm64; the upstream Quay MinIO images no longer allow anonymous pulls.
The existing minio names and MINIO_* settings remain compatible. Keep the
Helm and Compose pins aligned when upgrading, and run Buzz's
object-store conformance probe
against the new release before deploying it.
For an existing MinIO data volume, follow Silo's migration guide and take a backup before upgrading. Replacing the container image upgrades the storage server as well as changing its registry.
Before sharing an install link publicly, verify a fresh install with:
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