Local development
Run the whole system locally: the HTTP API plus the queue worker and the scheduler. They are three processes started from the same binary, so a full local stack means three shells.
| Process | Command | Purpose |
|---|---|---|
| API | ims serve (or make dev) |
HTTP on :8080; make dev puts Vite HMR on :8080 and the API on :8081 |
| Worker | ims queue:work |
processes River jobs (critical/default/heavy) |
| Scheduler | ims schedule |
runs cron tasks (heartbeat, billing, cleanup) |
Exactly one scheduler and one (or more) worker per environment.
Prerequisites
- Go 1.26.11+ (older 1.26 patches have standard-library CVEs), PostgreSQL 16+, GNU Make
- Node.js 20.19+ with npm (developer dashboard dev/build)
- Optional: Docker (throwaway Postgres);
air+golangci-lintviamake tools
First-time setup
cp .env.example .env # .env is git-ignoredmake tools # install air + golangci-lintnpm --prefix web/dev ci # dashboard dependencies (Vite/React)git config core.hooksPath .githooks # enable pre-commit/pre-push hookschmod +x .githooks/pre-commit .githooks/pre-push # macOS/Linux only
make db-up # Postgres via docker compose: creates ims_go_api (app) and # ims_go_api_test (integration tests). With your own server: # createdb ims_go_api && createdb ims_go_api_test
make migrate # goose migrations AND River's tablesmake seed # permissions, roles, tenant+branch, admin + developer usersSeeded accounts (both use AUTH_DEFAULT_PASSWORD, default 123456):
| Account | Role | Purpose |
|---|---|---|
superadmin@ims.com |
Super-Admin | full API + dashboard access |
developer@ims.com |
hidden Developer | developer dashboard without using the super-admin account |
The default tenant/branch are 1 / 1. make seed is idempotent.
Set a shared cache driver so the three processes see the same counters and scheduler heartbeat:
CACHE_DRIVER=database # memory | file | redis | databaseQUEUE_DRIVER=river # river (durable, needs the worker) | sync (inline, no worker)database cache uses the cache table created by the migrations.
Run the full stack
Three shells, same working directory:
# Shell A — HTTP API + developer dashboard with hot reloadmake dev # = migrate + Vite HMR (:8080) + air API (:8081)# Open http://localhost:8080/dev/ for the dashboard (HMR). Vite proxies# /api, /dev/api, /storage and /docs to the API on :8081. `make dev-api`# still runs the API alone on :8080 with the embedded production build.
# Shell B — queue workermake queue # = go run ./cmd/app queue:work# go run ./cmd/app queue:work --queues=critical# go run ./cmd/app queue:work --once
# Shell C — scheduler daemonmake schedule # = go run ./cmd/app scheduleAfter make build-all the same roles are bin/ims serve, bin/ims queue:work, bin/ims schedule.
(make build alone assumes web/dev/dist was already built; use build-all for a release.)
make dev puts Vite on the canonical :8080 so the dashboard, API docs and proxied API all share
one origin and HMR works in the browser. Override the pair with IMS_WEB_PORT (default 8080) and
IMS_API_PORT (default 8081).
For the standalone SPA dev server on :5173, run make dev-api (API on :8080) in one shell and
make dev-web in another; IMS_API_ORIGIN defaults to http://127.0.0.1:8080. Do not combine
make dev-web with make dev, because make dev already uses :8080 for Vite.
Verify
curl http://localhost:8080/upcurl http://localhost:8080/api/health # DB, cache, queue, scheduler and backup checkscurl http://localhost:8080/api/v1/system/info# Dashboard: http://localhost:8080/dev/ (developer@ims.com or superadmin@ims.com)# API docs UI (enabled outside production): http://localhost:8080/docs
# log in and use the tokencurl -X POST http://localhost:8080/api/v1/login \ -H "Content-Type: application/json" \ -d '{"email":"superadmin@ims.com","password":"123456","device":"cli"}'curl http://localhost:8080/api/v1/user -H "Authorization: Bearer <id|secret>"
make health # or: go run ./cmd/app health:checkmake config # secrets maskedgo run ./cmd/app queue:stats # QUEUE / TOTAL / ACTIVE / FAILEDgo run ./cmd/app schedule:listgo run ./cmd/app schedule:run scheduler.heartbeatgo run ./cmd/app backup:listDEV_DASHBOARD_ENABLED defaults to true outside production; set it to false to make /dev and
/dev/api/* return 404. The hidden Developer account holds only the developer-dashboard
permissions (dev.view, dev.manage) — it cannot administer tenants, users or billing data
through the API. Still rotate its password outside local use.
To watch a job end-to-end, trigger a background user export (POST /api/v1/user/export-background),
watch Shell B process it, then check queue:stats and the job status.
Scheduled tasks
| ID | Spec | Description |
|---|---|---|
scheduler.heartbeat |
* * * * * |
heartbeat for the health check |
dataprocessing.cleanup-completed |
0 2 * * * |
prune completed import/export jobs |
billing.expire-subscriptions |
0 */6 * * * |
mark overdue subscriptions expired |
billing.send-renewal-reminders |
0 8 * * * |
7/3/1-day renewal reminders |
backup.run |
30 1 * * * |
database backup (when BACKUP_ENABLED=true) |
backup.clean |
30 2 * * * |
backup retention cleanup (when enabled) |
notifications.purge-expired |
30 3 * * * |
delete notifications expired for 7+ days |
activity.prune |
45 3 * * * |
activity log older than ACTIVITY_RETENTION_DAYS |
devdashboard.prune |
0 3 * * * |
dashboard telemetry and audit rows past their retention |
cache.purge-expired |
15 * * * * |
expired rows in the database cache (CACHE_DRIVER=database) |
Times use SCHEDULE_TIMEZONE (falls back to APP_TIMEZONE).
Everyday commands
make helpmake run # API once (no hot reload)make test # unit testsmake check # format-check + vet + lint + testsmake web-typecheck # dashboard TypeScriptmake build-all # SPA + Go binary (use for release)make migrate-status # goose + River migration statemake generate # sqlc + OpenAPI contract + generated regionsmake openapi-check # spec validity + route drift + region freshnessmake gen-check # fail on generated-code driftgo run ./cmd/app permission:syncgo run ./cmd/app settings:syncgo run ./cmd/app feature-flags:syncgo run ./cmd/app cache:cleargo run ./cmd/app backup:runMost of these are also one click away in the dashboard’s Commands page
(http://localhost:8080/dev/commands, or Ctrl+K → the command name), with their output and history.
Feature knobs (.env)
| Need | Set |
|---|---|
| Durable jobs | QUEUE_DRIVER=river + run the worker |
| Inline jobs, no worker | QUEUE_DRIVER=sync |
| Shared cache / counters / heartbeat | CACHE_DRIVER=database (or redis + REDIS_*) |
MAIL_DRIVER=log (default) or smtp + MAIL_HOST/MAIL_PORT/MAIL_USERNAME/MAIL_PASSWORD |
|
| Uploads | FILES_DISK=public (any disk: private, public, s3 or a STORAGE_DISKS name such as an R2/MinIO bucket); APP_STORAGE_DIR, STORAGE_* |
| Metrics / docs | METRICS_ENABLED=true (/metrics), DOCS_ENABLED=true (/docs) |
| Developer dashboard | DEV_DASHBOARD_ENABLED=true (default outside production); /dev |
| Billing gateways | BKASH_*, NAGAD_*, BANK_TRANSFER_* |
| Database backups | BACKUP_ENABLED=true, BACKUP_DIR, BACKUP_DESTINATIONS=local,s3 + S3_* (see backups.md) |
Use a specific file with ims --env-file /path/to/.env serve (flag → APP_ENV_FILE → ./.env;
real environment variables always override file values).
Troubleshooting
queue:workexits immediately: it requiresQUEUE_DRIVER=river. Withsync, jobs run inline and no worker exists.- Health shows a stale-scheduler warning:
CACHE_DRIVER=memoryis per-process — setdatabase/redis. migratefails: it creates the schema, not the database. Create the database first, or repointDATABASE_DSN.make devcannot find Vite: runnpm --prefix web/dev cionce (Node.js 20.19+)./devreturns 404: setDEV_DASHBOARD_ENABLED=true; the dashboard is off in production by default.- Dashboard login fails: run
make seed(it createsdeveloper@ims.comand the hidden role). - Integration tests: set
DATABASE_TEST_DSN(they skip, never fail, when it is unset). - New API routes answer 404/405 after an edit (Windows): air could not restart the API because the
old process still holds
:8081. Stop the oldimsprocess (Get-Process ims) and save a Go file with a real change, or restartmake dev. The worker and scheduler never hot-reload — restartmake queue/make scheduleafter changing jobs or tasks. backup:runfails: install PostgreSQL client tools and pointBACKUP_PG_DUMP_PATHat apg_dumpversion matching or exceeding the server; seebackups.md.
Production is a separate runbook: see deploy.md.