Starting and stopping¶

Run these from deploy/, once .env and plintz.yaml are in place. See Configuring plintz.

Starting plintz¶

docker compose up -d --build

The first start builds the images. Open the Workbench at http://localhost:8080, or your PLINTZ_HTTP_PORT, or at the HTTPS address in front of it, and sign in through your provider.

The containers restart automatically unless you stop them, including after the host or Docker restarts.

What happens at startup¶

Compose starts postgres first, and the backend once Postgres is healthy. The Workbench starts after the backend. The backend then, in this order:

Reads plintz.yaml and checks it, and creates each Datasource's Connector. If anything is wrong, it stops here.
Creates cache_dir if it is missing, and applies the database migrations.
Evicts blocks from the block cache until it is within cache_disk_budget_gib, in case you lowered the budget since they were cached.
Starts serving. At the same time, it indexes, in the background, every Datasource that has never been indexed. Until that finishes, search finds nothing of that Datasource's Stored Signals. A restart doesn't index a Datasource again.
Schedules Indexing for every indexing_interval_seconds from then on. The first scheduled run is one interval after startup.

Users can sign in as soon as the backend starts serving requests. The frontend serves the Workbench while the backend starts, but requests to /api fail until the backend is up.

When startup fails¶

Docker restarts the backend after it exits, so its container remains in the Restarting state. Read its log (see Logs). The last line names the problem:

Last line of the log	What to do
`could not read deployment config at /etc/plintz/plintz.yaml`	`plintz.yaml` is missing from `deploy/` or is unreadable. If it was missing when you started the stack, Docker created a directory with that name. Remove the directory and copy `plintz.example.yaml` to `plintz.yaml`.
`deployment config at … is not valid YAML`, or `… must be a YAML mapping`	Fix the file's YAML.
`invalid deployment config at …: environment variable NAME is not set`	Add `NAME` to `.env`, and recreate the backend.
`invalid deployment config at …: <key>: <problem>`	Fix that key. See The deployment config.
`unrecognized Connector 'x' for Datasource 'y'`, `invalid Databricks Connector options for Datasource 'y': …` or `unknown Synthetic Connector options for Datasource 'y': …`	Fix the Datasource. See Datasources.
`the Databricks Connector's service principal needs DATABRICKS_CLIENT_ID and DATABRICKS_CLIENT_SECRET in the environment`	Add them to `.env`.
`Application startup failed. Exiting.`	Check the preceding log lines for the error. This happens during step 2. The error usually means Postgres is unreachable or plintz cannot write to `cache_dir`.

Checking the running stack¶

smoke-test checks that the Workbench loads, the API rejects requests without a session, login redirects to your provider, and a signed-in session can search and view a trend. It signs in automatically through the development stack's fake provider. With a real provider, sign in through a browser and copy the plintz_session cookie from the browser's developer tools. Find it under Cookies for the /api path, then pass its value to the command:

PLINTZ_SESSION='<cookie value>' ./smoke-test http://localhost:8080

Its search and trend steps use the Synthetic Datasource synthetic, searching for sine, so they need it in plintz.yaml, as the example has it. It counts the Samples through the backend container, so it must run on the Docker host, with one stack running from deploy/.

Stopping plintz¶

docker compose down

This stops and removes the containers. The volumes survive, so the next start finds all the app data and the block cache. docker compose down -v deletes the volumes too, including all app data.