Skip to content

Latest commit

 

History

History
89 lines (73 loc) · 3.74 KB

README.md

File metadata and controls

89 lines (73 loc) · 3.74 KB

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

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:

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.

Upgrade

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.

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.
  • 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.
  • 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_URL and set BUZZ_PUSH_ENABLED=true. To use another gateway, replace the exact HTTPS /v1/deliveries/apns URL before enabling push. Newer gateways and relays also accept the platform-neutral /v1/deliveries route; the template stays on /v1/deliveries/apns until the public gateway and a relay release both support it.
  • The bundled Compose stack fixes the relay endpoint to http://minio:9000 and BUZZ_S3_ADDRESSING_STYLE=path: Docker DNS resolves minio, 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 require virtual addressing.

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.

Validation

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