Quickstart

This runs the whole platform on one machine with Docker only: PostgreSQL, the backend, scheduler, jobs, compiler and input-logs services, and the web shell, from the images a release publishes. No source checkout, no Python, no build.

Requirements#

• Docker with the compose plugin, v2 (Docker Desktop, or Docker Engine with docker compose).
• Memory for Docker: the stack runs nine containers, seven of them long-running. docker stats shows how much memory each one uses; if containers exit with code 137, give Docker more memory.
• curl and openssl for the two set-up lines below.
• The images are built for linux/amd64. On an arm64 machine (Apple silicon) Docker runs them emulated, which is slower.

Run it with Docker#

In an empty directory, with <version> the release you want (for example 1.0.0):

curl -fsSLO https://gitlab.com/nistor-io/nistor/-/releases/v<version>/downloads/docker-compose.yml
printf 'POSTGRES_PASSWORD=%s\n' "$(openssl rand -hex 16)" > .env
docker compose up -d --wait

The first line downloads the release's compose file, which already names that release's images. The second writes a random database password into .env, the only setting without a default; keep the file, the database uses that password from now on. The third pulls the images and returns once Postgres is healthy, the schema is migrated, the demo estate is seeded and the backend answers.

Open http://localhost:8080. There is no login in this stack: you act as admin@example.com, the platform admin it seeds. Every port is bound to 127.0.0.1, so nothing outside this machine reaches it; it is a local trial, not a server.

The backend answers its health checks on its own port: http://localhost:8000/health/live (the process is up), http://localhost:8000/health/ready (ready to serve; a 503 carries the reason) and http://localhost:8000/health/installed (the installed tools and their versions). /health alone is not one of them.

What you see is a synthetic estate of about 35 days: rules, action runs, incidents and a catalog with its lineage graph, all read from the local database. Nothing acquires data from a cloud here, and nothing fires the scheduled rules on its own; triggering a rule by hand runs it with the dummy executor. For that reason the stack turns off the check that opens an incident when the scheduler fires nothing (SCHEDULER_LIVENESS_ENABLED=false on the backend); a deployed environment keeps it on.

Stop and reset:

docker compose down      # stops the stack, keeps the database
docker compose down -v   # deletes the database too; the next start seeds it again

Settings go in .env beside the file: NISTOR_PORT (the web UI, default 8080), NISTOR_BACKEND_PORT (the API and its /docs, default 8000), NISTOR_ADMIN_EMAIL, and NISTOR_SEED=0 to start empty instead of with the demo estate. The repository's deploy/compose/.env.example lists every variable the file reads.

To move to a newer release, download that release's file over the old one and run docker compose up -d --wait again: the migrate service brings the schema to the new release before the services start. Read upgrading first.

From source (contributors)#

The repository's own docker-compose.yml runs the same services on images built from the checked-out source, with its ports bound to 127.0.0.1 as well, plus Postgres on 127.0.0.1:55432 (POSTGRES_HOST_PORT) for local tools:

git clone https://gitlab.com/nistor-io/nistor.git
cd nistor
make dev              # the nistor CLI and every package, into .venv
make runtime-image    # builds nistor-runtime:local from the committed code
docker compose up

It needs GNU make, Python 3.11, and Node.js 22 with npm besides Docker: make dev installs the CLI with its dist extra (uv, which locks the image), and the lock builds the UI remotes with npm. It builds only committed code: commit, then make runtime-image again. It needs no .env: the database password defaults to nistor, which is why nothing in it listens beyond this machine. Open http://localhost:8080; docker compose down and docker compose down -v work as above.

Hello world: a first tool#

examples/providers/hello_world is a complete tool that talks to a fake service and passes the conformance kit with no network:

. .venv/bin/activate   # from make dev; pip, pytest and nistor come from it
make test-example

Copy it to start your own: nistor tool new my_system writes the same shape. See Writing a tool.

Next#

Concepts, configuration, install on GCP.