Run it

One command, with Go installed and nothing else:

go run github.com/septagon-oss/platformkit/apps/platformkit@main start

@main names the branch because the last tagged release, v1.0.0, predates start; once a later version is tagged, @latest works too. start runs its own PostgreSQL 16 — downloaded once into your user cache, its data under ./data in the directory you ran it from — creates the application role, migrates, bootstraps the first tenant and administrator when there is none, and serves on :8080. The generated administrator password is printed once; keep it private. A second start in the same directory finds the tenant and serves it again. Ctrl+C stops the application and its database.

It prints three addresses. http://platformkit.localhost:8080/ is the public site, empty until you publish a page; http://platformkit.localhost:8080/admin/login is the operator’s admin; http://platformkit.localhost:8080/docs is the API documentation. The request host selects the tenant, so use platformkit.localhost and not localhost or an arbitrary alias. The component gallery is at /admin/_gallery.

--data moves the data directory and --addr the listening address. The source is apps/platformkit/start.go; what it does not need is NATS, because the combined role carries events in memory. A deployment never uses start: it has a config.yaml and a database of its own, and uses run.

What you are looking at

  • /admin is the dashboard: one card per resource you may read, with its count, and the instance’s health.

  • Every entity a module registers has seven generated pages under /admin/<module>/<entities>: list, detail, create form, edit form, the two writes and delete. Nothing about them was written by hand; see Components, pages and screens.

  • GET /api/v1/admin/resources is the same knowledge as JSON, for a shell that is not a browser; see The native shell.

  • GET /health and GET /ready are the probes. /openapi.json exists only when server.docs is enabled in config.yaml, which the example leaves off.

The development loop

make up     # Postgres and NATS, waiting for both
make run    # the application, on config.yaml

make run creates config.yaml from config.example.yaml when it is missing and never overwrites an edited one. A loader that finds no configuration says where to get one rather than what the file system saw. The first tenant comes from platformkit bootstrap; see the Makefile for the full list of targets.

Verify a change

make check

builds, vets and format-checks the Go, runs the tests against the real Postgres and NATS, and checks the source and package budgets, the import boundary and tenant-setting ownership. make e2e drives the admin shell with a browser and needs Node, npm, psql, curl and a Playwright-managed Chromium:

npm --prefix e2e ci
npm --prefix e2e run install:browsers
make e2e

The e2e script recreates a fixed platformkit_e2e database on the configured development server; it is disposable there and must not be run against anything else. make down removes the local Compose volumes as well as stopping the services: it is a data deletion, not a test step. The full list of targets is the Makefile.