Skip to content
Keelmint

Quickstart

This page takes you from your purchase to a running API and client with demo organizations and logins. Do it once before you change anything: it is the baseline every other page assumes.

Prerequisites

  • Node.js 24 and corepack (ships with Node).
  • Docker (Docker Desktop or any Docker daemon): Postgres 17 and Mailpit run in containers.
  • Free ports: 5433 (Postgres), 8025 and 1025 (Mailpit), 3000 (API), 4200 (client).

1. Get the code

After your purchase, GitHub sends you an invitation to the private keelmint/keelmint repository (you add your GitHub username on the claim page linked from your receipt). Accept it, then clone the repository into a repo of your own, keeping Keelmint as the upstream remote you take updates from:

Terminal window
git clone https://github.com/keelmint/keelmint.git my-product
cd my-product
git remote rename origin upstream
git remote add origin git@github.com:<you>/my-product.git   # an empty private repo you created
git push -u origin main

Clone, don’t fork: GitHub deletes a fork of a private repository when its owner loses access to the original, and your product would go with it. Your own repo stays yours. Updating explains how to take new releases.

2. Install

Terminal window
corepack enable   # picks up pnpm from package.json "packageManager"
pnpm install

3. Start Postgres and Mailpit

Terminal window
docker compose up -d db mailpit

The first start creates the keelmint and keelmint_test databases (tools/db/init/keelmint.sql). Postgres listens on host port 5433, so an already-installed local Postgres on 5432 is left alone. Mailpit catches every email the API sends; its inbox is at http://localhost:8025.

4. Configure the API

Each product API reads its own env file, apps/<product>/api/.env (gitignored). For Keelmint:

Terminal window
cp apps/keelmint/api/.env.example apps/keelmint/api/.env

The example works locally as it is: it points at the Compose Postgres and Mailpit and carries development-only secrets. Never use those secrets anywhere else; generate your own for any shared or production environment (openssl rand -base64 32 for JWT_SECRET, JOBS_ENCRYPTION_KEY and TWO_FACTOR_ENCRYPTION_KEY).

Keelmint has billing on, but you need no Stripe account to start: without Stripe keys the API runs with plans and limits, and only the Upgrade buttons answer “payments are not set up” until you add test keys (see Billing).

With Claude Code (or another agent) you can ask it to “configure the env”: the configure-env skill asks for each variable, generates the secrets and validates the file. Every variable is described in Configuration.

5. Create the schema and the demo data

Terminal window
pnpm nx run keelmint-db:migrate   # prisma migrate deploy
pnpm nx run keelmint-db:seed      # demo organizations and logins

The seed is for development only: it refuses production and non-local databases. Running it again is safe.

6. Run it

Terminal window
pnpm dev   # keelmint-api on :3000, keelmint-client on :4200

Open http://localhost:4200 and log in with one of the demo accounts below. The API answers at http://localhost:3000/api; its OpenAPI UI is at http://localhost:3000/api/docs.

Demo logins

Every password is keelmint-dev-password (set SEED_PASSWORD before seeding to use another).

EmailWho
admin@keelmint.localPlatform admin: every organization, users, roles, helpdesk, audit. In no organization
alice@keelmint.localAdmin of Acme Accounting (whole organization), member of Globex Partners
bob@keelmint.localMember of Acme Accounting and admin of its Manchester unit only (a unit admin)

The organizations, units and todos the seed creates are listed in Demo data. Demo organizations have the Business plan set by hand, so plan limits do not get in the way while you explore.

Language: Keelmint’s default language is English (defaultLanguage: 'en'); Greek is available from the language menu or the profile. Your own product picks its default in product.config.ts.

Things to try:

  • As alice, open Organization to see members, units and the org chart; switch to Globex Partners from the header.
  • As bob, notice that you manage only Manchester and its sub-unit.
  • Register a new account: the verification email lands in Mailpit. After verifying, create your own organization (it starts on a 14-day Pro trial).
  • As admin, open Administration for every organization and user.

Troubleshooting

  • The API refuses to boot and lists variables: the env file is missing a value or has an invalid one. Fix the listed variables; pnpm nx run core-api-env:check-env --file=apps/keelmint/api/.env checks a file without starting the API.
  • database "keelmint" does not exist: the Postgres volume was created before the init script was mounted. Run docker compose up -d db once more, then docker compose exec db psql -U postgres -f /docker-entrypoint-initdb.d/keelmint.sql.
  • No emails: check Mailpit is running (docker compose ps) and that SMTP_HOST/SMTP_PORT in the env file point at it (localhost, 1025).

Next