getting-started

Installation

Prerequisites and initial setup for BurnerByte.

Prerequisites

Requirement	Version
Go	1.25+
Node.js	20.9+ (images build on 22) with pnpm 10.30.3 via corepack
golang-migrate	v4.18.3 — only for the `make migrate-*` targets; Docker runs migrations for you
Docker & Docker Compose	Latest
PostgreSQL	16 (or use Docker)
Redis	7 (or use Docker)

Clone the Repository

bash

git clone https://github.com/AmJaradat01/burnerbyte.gitcd burnerbyte

Configuration (optional)

No configuration file is required. The images boot entirely from environment variables, and every operational key has a default, so a fresh clone runs as-is.

If you would rather configure by file — running the binaries directly, for instance — copy the example and mount or point at it:

bash

cp config.example.yaml config.yaml

config.yaml is gitignored and never baked into an image; set BB_CONFIG_PATH to load it from elsewhere. For Docker Compose, environment variables are the normal route — see Configuration.

Starting the API with no database configured — DATABASE_URL unset and no config.yaml — boots a token-gated installer instead of the API. Every other path answers 503 BurnerByte is not configured yet until it completes.

The startup log prints a one-time URL:

text

open http://<host>:8080/install?token=<token>

The form collects the database URL, Redis URL, JWT secret and (strongly recommended) an encryption key, verifies the connections, writes config.yaml, and re-execs into a normal boot. BB_CONFIG_PATH changes where that file is written. An already-configured instance never exposes the installer.

Setting DATABASE_URL and REDIS_URL in the environment skips it entirely, which is what Docker Compose does.

Which Database Am I Configuring?

Database and Redis are the only settings the setup wizard cannot change — its own state (the owner account, the organization, setup_state, system_configs) is stored in that database, so the connection has to be resolved before the API can serve step one. They come from the environment, config.yaml, or the first-run installer.

So that you can confirm you are configuring the intended instance, GET /api/v1/setup/status reports the connection targets with credentials stripped, and the wizard shows them above the admin form:

json

{  "completed": false,  "datastores": { "postgres": "postgres:5432/burnerbyte", "redis": "redis:6379" }}

The datastores field is withheld once setup completes.

Start the Stack

make docker-up starts the full stack — PostgreSQL 16, Redis 7, MinIO, the API server, SMTP server, and the Next.js frontend — via docker compose up -d.

bash

make docker-up

Careful

The stack starts with development-grade defaults. Before exposing it to anything beyond localhost, copy .env.example to .env and set JWT_SECRET (32+ chars, or the API refuses to boot) and ENCRYPTION_KEY — without the latter, SSO, SMTP and storage credentials are stored unencrypted. See Docker Setup for the full variable list.

To stop the stack: make docker-down

Local development only: If you want only the infrastructure services (postgres, redis, minio) and intend to run the API and frontend locally, run make docker-infra — it layers docker-compose.dev.yml over the base file to publish 5432/6379/9000/9001 on the host, which the base file deliberately does not. Then use make run-api and cd web && pnpm dev.

Environment Configuration

bash

cp .env.example .env

Edit .env with your values. At minimum, configure:

DATABASE_URL — PostgreSQL connection string
REDIS_URL — Redis connection string
JWT_SECRET — A random 64-character string for signing tokens

See Configuration for all available options.

Run Migrations

bash

make migrate-up

This applies all 47 database migrations, creating tables for users, organizations, teams, domains, inboxes, emails, attachments, webhooks, API keys, audit logs, sessions, SSO, analytics, and more.

Install Frontend Dependencies

bash

cd web && pnpm install

Build (Optional)

For production builds:

bash

# Backendmake build # Frontendcd web && pnpm build

This produces bin/api, bin/smtpd, and the Next.js standalone output.