Skip to content
BurnerByte

getting-started

Docker Setup

Running BurnerByte with Docker Compose.

Full Stack with Docker Compose

The included docker-compose.yml runs the entire stack with no configuration file at all — every setting has a working default and the images boot purely from environment variables:

bash
docker compose up -d

This starts seven services — three published to the host, three internal, plus a one-shot migration job:

ServiceHost portDescription
frontend3000Next.js UI
api8080Go API server + workers
smtpd2525SMTP inbound server
postgres—PostgreSQL 16 database
redis—Redis 7 cache
minio—S3-compatible object storage
migrate—Applies schema migrations, then exits
Note

Postgres, Redis and MinIO publish no host ports. api and smtpd reach them over the compose network, and binding 5432, 6379 or 9000 on the host would make docker compose up fail for anyone already running those locally. Use the dev overlay below when you need them reachable from the host.

Customizing Ports and Credentials

All ports and credentials are configurable via environment variables. Create a .env file:

.env
# DatabasePOSTGRES_USER=burnerbytePOSTGRES_PASSWORD=a-strong-passwordPOSTGRES_DB=burnerbytePOSTGRES_PORT=5432        # dev overlay only — the base stack publishes no DB port # RedisREDIS_PORT=6379           # dev overlay onlyREDIS_PASSWORD=a-strong-redis-password # MinIOMINIO_ROOT_USER=minioadminMINIO_ROOT_PASSWORD=a-strong-passwordMINIO_BUCKET=burnerbyteMINIO_PORT=9000           # dev overlay onlyMINIO_CONSOLE_PORT=9001   # dev overlay only # Service portsAPI_PORT=8080SMTPD_PORT=2525FRONTEND_PORT=3000 # ApplicationJWT_SECRET=change-me-to-a-random-64-char-stringFRONTEND_URL=http://localhost:3000API_BASE_URL=http://localhost:8080   # baked into the frontend image at build timeSMTP_HOSTNAME=mail.example.com        # BB_SMTP_HOSTNAME on both api and smtpdWS_BASE_URL=ws://localhost:8080       # baked into the frontend image; wss:// behind TLSCORS_ALLOWED_ORIGINS=http://localhost:3000  # CORS + WebSocket origins; defaults to FRONTEND_URL

Infrastructure Only

To run just the infrastructure (database, cache, storage) while developing locally:

bash
make docker-infra# equivalently:# docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d postgres redis minio

docker-compose.dev.yml is the overlay that publishes the infrastructure ports to the host; without it those services stay on the internal network only.

Then run the API and frontend locally with make run-api and cd web && pnpm dev.

Careful

make docker-up / make docker-down map to docker compose up -d / down and start or stop the entire stack (api, smtpd, and frontend included), not just infrastructure.

Using a Managed Database

The bundled postgres and redis services are a convenience, not a requirement. To run against a managed instance, set these in .env:

bash
EXTERNAL_DATABASE_URL=postgres://user:pass@db.example.com:5432/burnerbyte?sslmode=requireEXTERNAL_REDIS_URL=rediss://:password@cache.example.com:6380

api, smtpd and the one-shot migrate job all honour them, so the schema is applied to your database rather than the bundled one. The bundled containers then go unused — start only what you need with docker compose up -d api smtpd frontend.

Careful

These are deliberately not called DATABASE_URL / REDIS_URL. That pair is read by the binaries when you run them directly (make run-api) and points at localhost; .env is shared between both modes, and localhost inside a container resolves to the container itself.

Health Checks

Postgres, Redis, MinIO and the API define health checks. The API and SMTP servers wait for healthy database, Redis and MinIO and for the one-shot migrate job to complete successfully; the frontend waits for a healthy api.

Verify everything is running:

bash
# API healthcurl http://localhost:8080/healthz # Readiness (checks DB + Redis)curl http://localhost:8080/readyz # MinIO console (requires the dev overlay — see "Infrastructure Only")open http://localhost:9001

Volumes

Data is persisted in Docker volumes:

  • pgdata — PostgreSQL data
  • redisdata — Redis data
  • miniodata — MinIO object storage
  • attachments — local-filesystem attachment fallback, used when MinIO is unreachable at boot

To reset everything: docker compose down -v