# How to Configure Docker Compose for Block Buzz Production VPS Deployment

> Deploy Block Buzz to production on your VPS using Docker Compose. Configure persistent storage and environment-based settings for a robust relay service with Postgres, Redis, and MinIO.

- Repository: [Block Open Source/buzz](https://github.com/block/buzz)
- Tags: how-to-guide
- Published: 2026-08-29

---

**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`](https://github.com/block/buzz/blob/main/docker-compose.yml) file intended strictly for local development. For production VPS deployments, you must use **[`deploy/compose/compose.yml`](https://github.com/block/buzz/blob/main/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.

```bash
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:

```text

# .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:

```bash
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:

```bash
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`](https://github.com/block/buzz/blob/main/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:

```bash
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`](https://github.com/block/buzz/blob/main/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:

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

```

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

```text
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`](https://github.com/block/buzz/blob/main/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`](https://github.com/block/buzz/blob/main/deploy/compose/compose.yml)** for production; the root [`docker-compose.yml`](https://github.com/block/buzz/blob/main/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`](https://github.com/block/buzz/blob/main/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`](https://github.com/block/buzz/blob/main/docker-compose.yml) configures a local development environment with simplified networking and volume setups. The [`deploy/compose/compose.yml`](https://github.com/block/buzz/blob/main/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.