How to Configure Docker Compose for Block Buzz Production VPS Deployment

Block Buzz provides a dedicated production Docker Compose bundle under deploy/compose/ that deploys the relay service alongside Postgres, Redis, and MinIO using environment-based configuration and named volumes for persistent storage.

Block Buzz is an open-source relay implementation that requires a robust container orchestration strategy for production environments. Configuring Docker Compose for Block Buzz production VPS deployment involves switching from the root-level development file to the specialized production stack located in the deploy/compose/ directory. This guide walks through the specific file paths, environment variables, and deployment commands defined in the block/buzz source code.

Select the Production Compose File

The repository root contains a docker-compose.yml file intended strictly for local development. For production VPS deployments, you must use deploy/compose/compose.yml, which defines the complete production service topology.

This production configuration declares five services:

• relay – The core Block Buzz application container
• postgres – PostgreSQL database for persistent storage
• redis – Redis cache and message broker
• minio – MinIO object storage for media
• minio-init – Helper container that creates the required media bucket on startup

All services attach to the buzz-net bridge network, which carries the label com.buzz.network: production. This isolates the stack from other containers on the host while enabling internal DNS resolution for hostnames like postgres, redis, and minio.

Configure Environment Variables

The production compose file externalizes configuration through environment variables. Copy the provided template and fill in the required secrets before launching the stack.

cp .env.example .env

Edit .env in the repository root to include these mandatory values:

• BUZZ_S3_ACCESS_KEY and BUZZ_S3_SECRET_KEY – MinIO administrator credentials
• POSTGRES_PASSWORD – Database superuser password
• REDIS_PASSWORD – Redis authentication token

Optional variables customize runtime behavior:

• BUZZ_IMAGE – Container image tag (defaults to ghcr.io/block/buzz:main)
• BUZZ_HTTP_PORT – External port mapping (default varies by configuration)
• BUZZ_AUTO_MIGRATE – Boolean flag to enable automatic database migrations on startup

A minimal production .env file looks like this:

# .env (production)

POSTGRES_PASSWORD=super-secret-pg
REDIS_PASSWORD=super-secret-redis
BUZZ_S3_ACCESS_KEY=buzz_prod_key
BUZZ_S3_SECRET_KEY=buzz_prod_secret

# Optional overrides

# BUZZ_HTTP_PORT=3000

# BUZZ_IMAGE=ghcr.io/block/buzz:v1.2.3

Launch the Production Stack

With the environment file populated, start the production services using the explicit file path. Run this command from the repository root:

docker compose -f deploy/compose/compose.yml --env-file .env up -d

If you have not pre-pulled the image, Docker will download the default ghcr.io/block/buzz:main tag automatically. To verify the image version before deployment:

docker pull ghcr.io/block/buzz:main

Development Overrides for Debugging

When troubleshooting on a VPS, you can expose internal service ports without modifying the core production file. The deploy/compose/compose.dev.yml overlay adds port mappings for Postgres, Redis, MinIO, Adminer, and Prometheus while leaving the base configuration untouched.

Launch with both files to enable debugging access:

docker compose -f deploy/compose/compose.yml \
               -f deploy/compose/compose.dev.yml \
               --env-file .env up -d

Remove the override file when returning to strict production mode to close administrative ports.

Verify Container Health

Each service in deploy/compose/compose.yml declares a Docker healthcheck. The relay container performs a raw TCP request against the /_readiness endpoint, while minio uses curl to poll its internal health endpoint. Docker marks containers as healthy only after these checks succeed, ensuring dependent services start in the correct order (e.g., redis initializes before relay).

Monitor status with:

docker compose -f deploy/compose/compose.yml ps

Expected output shows all services in Up state with healthy status:

Name                       State          Health
buzz-prod-relay            Up             healthy
buzz-prod-postgres         Up             healthy
buzz-prod-redis            Up             healthy
buzz-prod-minio            Up             healthy

Persistent Storage and Network Isolation

Data durability relies on four named Docker volumes declared at the bottom of compose.yml:

• buzz-postgres-data – Database files
• buzz-redis-data – Redis persistence
• buzz-minio-data – Object storage buckets
• buzz-git-data – Git repository backing the relay

These volumes survive container restarts and are the source of truth for your production state. The dedicated buzz-net bridge network ensures traffic isolation from unrelated containers on the VPS host.

Summary

• Use deploy/compose/compose.yml for production; the root docker-compose.yml is development-only.
• Supply required secrets via a root-level .env file: POSTGRES_PASSWORD, REDIS_PASSWORD, and MinIO credentials.
• Start the stack with docker compose -f deploy/compose/compose.yml --env-file .env up -d.
• Apply compose.dev.yml only when you need exposed ports for debugging tools like Adminer or Prometheus.
• Verify health via docker compose ps to ensure the relay, database, cache, and storage services report healthy states.
• Data persists across restarts using named volumes for Postgres, Redis, MinIO, and Git data.

Frequently Asked Questions

What is the difference between the root docker-compose.yml and deploy/compose/compose.yml?

The root docker-compose.yml configures a local development environment with simplified networking and volume setups. The deploy/compose/compose.yml file defines a hardened production topology with dedicated healthchecks, the buzz-net isolation bridge, named volumes for durability, and initialization helpers like minio-init that create required storage buckets automatically.

How do I expose internal database ports for debugging on my VPS?

Layer the development override file during startup. Run docker compose -f deploy/compose/compose.yml -f deploy/compose/compose.dev.yml --env-file .env up -d. This exposes Postgres, Redis, and MinIO ports on the host interface without altering the base production configuration. Remove the override and recreate the containers to close these ports.

Which environment variables are mandatory for a production deployment?

You must define POSTGRES_PASSWORD, REDIS_PASSWORD, BUZZ_S3_ACCESS_KEY, and BUZZ_S3_SECRET_KEY before starting the stack. Optional variables include BUZZ_IMAGE to pin a specific container tag, BUZZ_HTTP_PORT to change the external listening port, and BUZZ_AUTO_MIGRATE to enable automatic schema migrations on container boot.

How does Block Buzz handle database migrations in production?

When BUZZ_AUTO_MIGRATE is set to a truthy value, the relay container executes pending database migrations automatically during its startup sequence before accepting traffic. If this variable is unset or false, you must run migrations manually using the relay binary or a separate job container connected to the buzz-net network and buzz-postgres-data volume.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}