Running Mint¶

Prerequisites¶

Docker and Docker Compose
Node.js 22 + pnpm (for local development without Docker)
Python 3.12 + uv (for local development without Docker)

Development¶

Development uses docker-compose.dev.yml. Services run with hot reload. MailHog catches all emails locally.

1. Generate RSA keys (first time only)

sh scripts/generate-keys.sh

This creates keys/private_key.pem and keys/public_key.pem used by the auth service.

2. Start everything

docker compose -f docker-compose.dev.yml up -d --build

3. Create an admin user

docker exec -it mint-auth uv run python /app/apps/auth/src/create_admin.py \
  --email admin@mint.dev \
  --password adminpass \
  --name "Admin User"

Then set the returned user ID in ADMIN_USER_IDS in docker-compose.dev.yml and restart the admin service:

docker compose -f docker-compose.dev.yml up -d --build admin

4. Rebuild a single service after code changes

docker compose -f docker-compose.dev.yml up -d --build <service-name>

URLs¶

URL	Description
http://localhost	User app
http://localhost/app-admin	Admin console
http://localhost:4000	Grafana (traces)
http://localhost:8025	MailHog (dev email)
http://localhost:9001	MinIO console

Production¶

1. Generate RSA keys (first time only)

sh scripts/generate-keys.sh

2. Create .env

cp .env.example .env

Edit .env and set at minimum:

Variable	Description
`FASTAUTH_SECRET`	Secret for JWT session signing
`ADMIN_USER_IDS`	Comma-separated user IDs with admin access
`GRAFANA_PASSWORD`	Grafana admin password
`KYC_WEBHOOK_SECRET`	Shared secret for Persona webhook verification

3. Start everything

docker compose up -d

Migrations run automatically before each service starts.

4. Rebuild after a change

docker compose up -d --build <service-name>

Service Ports¶

Service	HTTP	gRPC
nginx (gateway)	80	—
web	3000	—
auth	4001	—
wallet	4002	50051
transactions	4003	—
kyc	4004	50053
analytics	4005	—
notifications	4006	—
social	4007	—
webhook	4008	—
admin	4009	—
audit	4010	—
fraud	—	50052
Grafana	4000	—
MailHog UI	8025	—

API Docs (Swagger)¶

Each backend service exposes Swagger UI at /api-docs.

Service	URL
auth	http://localhost:4001/api-docs
wallet	http://localhost:4002/api-docs
transactions	http://localhost:4003/api-docs
kyc	http://localhost:4004/api-docs
analytics	http://localhost:4005/api-docs
notifications	http://localhost:4006/api-docs
social	http://localhost:4007/api-docs
webhook	http://localhost:4008/api-docs
admin	http://localhost:4009/api-docs
audit	http://localhost:4010/api-docs

Database Migrations (manual)¶

Migrations run automatically on startup, but you can also run them manually:

Python services (auth, wallet)

docker compose exec auth uv run migrate
docker compose exec wallet uv run migrate

NestJS services

docker compose exec transactions npx prisma migrate deploy

Generating gRPC Stubs¶

After editing a .proto file in libs/proto/:

# Regenerate Python stubs (wallet service)
python scripts/generate_proto.py

# NestJS services read .proto files directly at runtime — no stub generation needed