Skip to content

Deploying plintz

Deploy one Docker Compose stack per company on a single host. The stack's files are in the deploy/ directory of the plintz repository. Run every command on these pages from that directory.

Prerequisites

  • A host with Docker and Docker Compose, and a checkout of the plintz repository. The stack builds its images from the repository: there is no prebuilt image to pull.
  • An OpenID Connect provider that you can register plintz with as a client, using the Authorization Code Flow. plintz has no passwords of its own. See Sign-in.
  • For each Datasource, whatever its Connector needs. A Databricks Datasource needs a SQL warehouse and a service principal that can read its two tables. See Datasources.
  • Free disk space on the host for the two volumes below. The block cache's share is the budget you set, which must be below the free space of its volume.
  • A way to serve the Workbench over HTTPS. See Network and HTTPS.

Services and volumes

The stack has three services:

Service What it is
frontend nginx. It serves the Workbench and proxies /api to the backend, so the Workbench and the API share one origin. It is the only service that publishes a port.
backend The FastAPI application, on port 8000 inside the stack. It applies the database migrations at startup.
postgres PostgreSQL 16, for app data and the block index.

Data lives in two named volumes:

Volume What it holds
postgres-data The app data: users, sessions, Analyses and their Worksheets, Calculated Items, Grants, the Stored Signal index that Indexing fills, the Administrators' overrides, the Audit Trail, and the block index.
block-cache The block cache's files, in cache_dir: the Samples and Rollups of Stored Signals, and the blocks of Calculated Items, as Arrow IPC files.

If you lose block-cache, plintz fetches missing blocks from their Datasources again. Losing postgres-data removes the app data, the Audit Trail and the block index. plintz keeps the Audit Trail in Postgres forever: nothing in it can be changed or deleted through plintz, and it has no purge, so it grows with the changes made. Flushing it to S3 is a later change.

Network and HTTPS

  • One published port. frontend publishes its port 80 on the host port PLINTZ_HTTP_PORT (8080 unless you set it in .env), on all of the host's interfaces. The backend and Postgres are reachable only from inside the stack.
  • HTTP only. nginx serves plain HTTP. Serve the Workbench over HTTPS in production, by putting a TLS-terminating reverse proxy or load balancer in front of the published port. Use the HTTPS address as the Workbench URL and as the redirect_uri registered with your provider. When it is https, plintz's session cookies are Secure. See Sign-in.
  • One origin. The proxy must send both the Workbench and /api to the published port, on the same address. The frontend proxies /api itself.
  • Outbound traffic. The backend calls your OpenID Connect provider's discovery and token endpoints. It also calls the provider's UserInfo endpoint if one is available, and each Datasource's system. For Databricks, that system is the SQL warehouse at server_hostname. The host must be able to reach these services. Users' browsers also need access to the provider to sign in.