Installation

Install Tokamak with Docker Compose. All commands below are run from the repository root.

1. Clone the repository

git clone https://github.com/janhq/tokamak.git
cd tokamak

2. Generate the environment file

make tokamak-setup

This writes tokamak-services/.env from the shipped template and scaffolds the supporting directories. Open the file and fill in your values.

At minimum you need a database DSN and a set of Compose profiles:

# Keep the generated local DSNs consistent with your configured database credentials.
COMPOSE_PROFILES=infra,api,web,full

Every Compose service is profile-gated. If COMPOSE_PROFILES is empty, docker compose up starts nothing at all.

See Configuration for the variables you should review before a production deploy.

3. Start services

make tokamak-up

On a completely fresh database, use the ordered bring-up instead. It starts infrastructure first, waits for the auth and core boot migrations to finish, seeds the internal service token, then brings up the remaining services:

make tokamak-up-dev

You can also start groups individually from the Compose directory:

make -C infra/docker/tokamak up-infra     # Postgres + Redis
make -C infra/docker/tokamak up-api       # gateway + core + auth + billing
make -C infra/docker/tokamak up-web       # web app + docs

4. Verify

make tokamak-health

The gateway is the public backend API listener:

curl http://localhost:8080/healthz

The web app is at http://localhost:3001. Core (8090), auth (8092) and billing (8093) are cluster-private and are not published to the host.

Database migrations

Core, auth and billing migrate their own schemas on boot — core when AUTO_MIGRATE=true (the default), auth and billing always. Migrations use golang-migrate and live in tokamak-services/services/core/migrations/, tokamak-services/services/auth/migrations/ and tokamak-services/services/billing/migrations/.

To re-run core's migrations, restart it:

make -C infra/docker/tokamak db-migrate

Troubleshooting

Problem	Fix
Nothing starts	Check `COMPOSE_PROFILES` is set in `tokamak-services/.env`
Service won't start	Run `make tokamak-health`; verify the `.env` file exists and has required values
Database errors	Check `DB_POSTGRESQL_WRITE_DSN`, then `make -C infra/docker/tokamak db-migrate`
Port conflicts	Check `docker ps` for containers already bound to 8080, 5432, 6379, or 3001

make tokamak-logs                                    # All service logs
make -C infra/docker/tokamak logs-api                # gateway, core, auth

See Troubleshooting for more.

For a development-only preview login, use the documented make tokamak-start-preview target after setup. Before inviting customers, configure production login, providers/models, email and payment services as needed; see Configuration.