Self-hosting

Run Koolbase on your own infrastructure with a single Docker Compose command. Full stack — API, database, cache, and object storage.

Requirements

Docker≥ 24.0

Docker Compose≥ 2.0

RAM≥ 1 GB

Disk≥ 5 GB

Quick Start

Clone the repository and spin up the full stack in one command:

git clone https://github.com/kennedyowusu/koolbase-api
cd koolbase-api
cp .env.example .env
docker compose up

That's it. The API will be available at http://localhost:8080 and the MinIO storage console at http://localhost:9001.

Services

Docker Compose starts the following services:

koolbase-api8080Go REST API

postgres5432Primary PostgreSQL database

redis6379Caching and session storage

minio9000S3-compatible object storage

minio console9001MinIO web UI for managing buckets

migrate—Runs database migrations on startup

Environment Variables

Copy .env.example to .env and update the values:

.envenv

# Database
DATABASE_URL=postgres://postgres:password@postgres:5432/koolbase?sslmode=disable

# Redis
REDIS_URL=redis://redis:6379

# JWT
JWT_SECRET=change-me-to-a-long-random-string

# Email (Resend)
RESEND_API_KEY=re_xxxx
EMAIL_FROM=Koolbase <noreply@yourdomain.com>

# Storage — MinIO (default for self-hosting)
S3_ENDPOINT=http://minio:9000
R2_ACCESS_KEY_ID=minioadmin
R2_SECRET_ACCESS_KEY=minioadmin
R2_BUCKET=koolbase
R2_PUBLIC_URL=http://localhost:9000/koolbase

# App
APP_URL=http://localhost:3001
PORT=8080

# Internal API key
INTERNAL_API_KEY=change-me-to-a-random-string

Storage Options

Koolbase uses any S3-compatible storage backend. Set S3_ENDPOINT in your .env to switch providers:

MinIO (self-hosted)http://minio:9000

Cloudflare R2https://<accountID>.r2.cloudflarestorage.com

AWS S3https://s3.<region>.amazonaws.com

Migrations

Database migrations run automatically on startup via the migrate service. No manual steps needed.

To run migrations manually:

docker compose run --rm migrate

Production Tips

Change default credentials

Update MINIO_ROOT_USER, MINIO_ROOT_PASSWORD, POSTGRES_PASSWORD, and JWT_SECRET before going live.

Use a reverse proxy

Put Nginx or Caddy in front of the API to handle SSL termination and domain routing.

Persist data volumes

Docker Compose creates named volumes for Postgres, Redis, and MinIO automatically. Back these up regularly.

Set up email

Auth flows (verification, password reset) require a valid RESEND_API_KEY. Get one free at resend.com.

Use external storage for scale

For production workloads, point S3_ENDPOINT to Cloudflare R2 or AWS S3 instead of local MinIO.

Connecting the Flutter SDK

Point the SDK to your self-hosted instance by setting baseUrl in your config:

main.dartDart

await Koolbase.initialize(const KoolbaseConfig(
  publicKey: 'pk_live_xxxx',
  baseUrl: 'http://your-server-ip:8080', // or your domain
));