Skip to content

Quick start

Prerequisites

Tool Version Why
Go 1.26.11 or newer builds and runs the API
PostgreSQL 16 or newer the only database (local install, Docker, or a managed one)
Node.js 20.19+ (22.23+ for the docs site) builds the developer dashboard
make any GNU make shortcuts; every target is also a plain go command

Run it

  1. Make it your repository. On GitHub, press Use this template → Create a new repository. You get your own repository with a clean history, not a fork that points back here. (Just trying it out? Clone this repository directly.)

  2. Clone and configure. Copy the example environment; every value has a working local default.

    Terminal window
    git clone <your-repository-url> ims-go-api && cd ims-go-api
    cp .env.example .env
  3. Install the tools once. air (hot reload) and golangci-lint, then the dashboard’s packages.

    Terminal window
    make tools
    npm --prefix web/dev ci
  4. Start Postgres — skip this if you already have one running.

    Terminal window
    make db-up # docker compose: creates ims_go_api and ims_go_api_test
  5. Create the schema and seed data. Migrations first, then permissions, the default tenant, roles and two accounts.

    Terminal window
    make migrate seed
  6. Run everything with hot reload.

    Terminal window
    make dev
make dev
$ make migrate seedgoose: successfully migrated database to version: 24River schema: v8 (0 pending)seeded permissions, tenant "Default", roles Admin + Developeraccounts: superadmin@ims.com, developer@ims.com$ make devvite  → http://localhost:8080/dev/air   → building ./cmd/app … running on :8081http server listening addr=:8081 env=local

Look around

Open localhost:8080/dev/ and sign in:

Account E-mail Password Can
Super Admin superadmin@ims.com 123456 everything, every tenant
Developer developer@ims.com 123456 the developer dashboard

The password comes from AUTH_DEFAULT_PASSWORD. The API reference (Scalar, from api/openapi.yaml) is at localhost:8080/docs.

The developer dashboard overview

Call the API from a terminal:

Terminal window
TOKEN=$(curl -s localhost:8080/api/v1/login -H 'Content-Type: application/json' \
-d '{"email":"superadmin@ims.com","password":"123456","device":"cli"}' | jq -r .data.token)
curl -s localhost:8080/api/v1/branch -H "Authorization: Bearer $TOKEN" \
-H "X-Acting-Tenant: 1" -H "X-Acting-Branch: 1" | jq

Background work

Queue jobs (mail, imports, backups) and scheduled tasks run in their own processes. Start them in two more terminals when you need them:

Terminal window
make queue # ims queue:work
make schedule # ims schedule

Next steps