Deploy the platform
The Tenzir Platform manages nodes and the pipelines running on them, offering a visual interface to explore data, manage nodes, and pipelines, and create dashboards.
Tenzir offers a free and cloud-hosted version of the Tenzir Platform on app.tenzir.com for all users of the Community Edition. This guide explains how to run the platform on your own premises as a user of the Sovereign Edition.
Configuration
The platform requires some external infrastructure that must be installed and configured separately.
HTTP Reverse Proxy
The platform uses four URLs that require a HTTP reverse proxy to be set up. These URLs may be mapped to the same or different hostnames.
- The URL that the user's browser connects to, e.g.,
app.platform.example.org
. This serves a web frontend where the user can interact with the platform. - The URL that the nodes connect to, e.g.,
nodes.platform.example.org
. Tenzir Nodes connect to this URL to establish long-running WebSocket connections. - The URL that the platform's S3-compatible blob storage is accessible at,
e.g.,
downloads.platform.example.org
. When using the 'Download' button the platform generates download links under this URL. - The URL that the Tenzir Platform CLI connects to, e.g.,
api.platform.example.org
.
You must provide the following environment variables for the platform:
# The domain under which the platform frontend is reachable. Must include the
# `http://` or `https://` scheme.
TENZIR_PLATFORM_DOMAIN=https://app.platform.example.org
# The endpoint to which Tenzir nodes should connect. Must include the `ws://`
# or `wss://` scheme.
TENZIR_PLATFORM_CONTROL_ENDPOINT=wss://nodes.platform.example.org
# The URL at which the platform's S3-compatible blob storage is accessible at.
TENZIR_PLATFORM_BLOBS_ENDPOINT=https://downloads.platform.example.org
# The URL at which the platform's S3-compatible blob storage is accessible at.
TENZIR_PLATFORM_API_ENDPOINT=https://api.platform.example.org
Identity Provider (IdP)
The platform requires an external Identity Provider (IdP) supporting the OIDC protocol. The IdP must provide valid RS256 ID tokens. The platform must be able to access the IdP's issuer URL.
You must provide the following environment variables for the OIDC provider configuration used for logging into the platform:
TENZIR_PLATFORM_OIDC_PROVIDER_NAME=YOUR_OIDC_PROVIDER_NAME
TENZIR_PLATFORM_OIDC_PROVIDER_CLIENT_ID=YOUR_OIDC_PROVIDER_CLIENT_ID
TENZIR_PLATFORM_OIDC_PROVIDER_CLIENT_SECRET=YOUR_OIDC_PROVIDER_CLIENT_SECRET
TENZIR_PLATFORM_OIDC_PROVIDER_ISSUER_URL=YOUR_OIDC_PROVIDER_ISSUER_URL
You must provide the following environment variable containing a JSON object containing the OIDC issuer and audiences that should be accepted by the platform.
TENZIR_PLATFORM_OIDC_TRUSTED_AUDIENCES='{"keycloak.example.org": ["tenzir_platform"]}'
You must provide the following environment variable containing a JSON list of
rules granting access to the admin API. The example rule grants admin access to
all users with a valid and signed id_token
containing the fields
{"connection": "google-oauth2", "tenzir/org": "TenzirPlatformAdmins"}
.
TENZIR_PLATFORM_OIDC_ADMIN_RULES='[{"connection": "google-oauth2", "organization_claim": "tenzir/org", "organization": "TenzirPlatformAdmins", "auth_fn": "auth_organization"}]'
PostgreSQL Database
A PostgreSQL database for storing the state of the platform.
You must provide the following environment variables:
TENZIR_PLATFORM_POSTGRES_USER=YOUR_POSTGRES_USER
TENZIR_PLATFORM_POSTGRES_PASSWORD=YOUR_POSTGRES_PASSWORD
TENZIR_PLATFORM_POSTGRES_DB=YOUR_POSTGRES_DB
TENZIR_PLATFORM_POSTGRES_HOSTNAME=YOUR_POSTGRES_HOSTNAME
Docker
The Tenzir Platform is shipped as a Docker Compose file. To run it, Docker and Docker Compose must be installed.
As part of your distribution, you were provided an authentication token to be able to fetch the Docker images. On the machine on which you want to run the Docker Compose stack, log in with the token like this:
echo YOUR_DOCKER_TOKEN | docker login ghcr.io -u tenzir-distribution --password-stdin
Run the Platform
Once you went through all the prerequisites, and have filled in the required
variables in your .env
file, you should be in a directory with the following
files:
.
├── localdev
│ ├── docker-compose.yaml
│ └── env.example
└── onprem-integrated
├── docker-compose.yaml
└── env.example
From one of these directories, run docker compose up
to start the platform in
the foreground, or docker compose up --detach
to run it in the background:
[+] Running 5/5
✔ Container compose-app-1 Running
✔ Container compose-websocket-gateway-1 Running
✔ Container compose-seaweed-1 Running
✔ Container compose-platform-1 Running
Attaching to app-1, platform-1, postgres-1, seaweed-1, websocket-gateway-1
platform-1 | {"event": "connecting to postgres", "level": "debug", "ts": "2024-04-10T10:13:20.205616Z"}
platform-1 | {"event": "connected to postgres", "level": "debug", "ts": "2024-04-10T10:13:20.210667Z"}
platform-1 | {"event": "created table", "level": "info", "ts": "2024-04-10T10:13:20.210883Z"}
platform-1 | {"event": "connecting to postgres", "level": "debug", "ts": "2024-04-10T10:13:20.217700Z"}
platform-1 | {"event": "connected to postgres", "level": "debug", "ts": "2024-04-10T10:13:20.221194Z"}
platform-1 | {"event": "creating a table", "level": "info", "ts": "2024-04-10T10:13:20.221248Z"}
platform-1 | {"event": "connecting to postgres", "level": "debug", "ts": "2024-04-10T10:13:20.221464Z"}
platform-1 | {"event": "connected to postgres", "level": "debug", "ts": "2024-04-10T10:13:20.224226Z"}
app-1 | Listening on 0.0.0.0:3000
websocket-gateway-1 | {"event": "connecting to postgres", "level": "debug", "ts": "2024-04-10T10:15:37.033632Z"}
websocket-gateway-1 | {"event": "connected to postgres", "level": "debug", "ts": "2024-04-10T10:15:37.038510Z"}
websocket-gateway-1 | {"event": "created table", "level": "info", "ts": "2024-04-10T10:15:37.042555Z"}
websocket-gateway-1 | {"host": "0.0.0.0", "port": 5000, "common_env": {"base_path": "", "tenzir_proxy_timeout": 60.0}, "local_env": {"store": {"postgres_uri": "postgresql://postgres:postgres@postgres:5432/platform"}, "tenant_manager_app_api_key": "d3d185cc4d9a1bde0e07e24c2eb0bfe9d2726acb3a386f8882113727ac6e90cf", "tenant_manager_tenant_token_encryption_key": "CBOXE4x37RKRLHyUNKeAsfg8Tbejm2N251aKnBXakpU="}, "event": "HTTP server running", "level": "info", "ts": "2024-04-10T10:15:37.045244Z"}
...
It takes up to a minute for all services to be fully available.
Update the Platform
Pull the latest images to update the platform:
docker compose pull
Manage the Platform
Install the tenzir-platform
package from PyPI.
The tenzir-platform
command-line utility makes it simple to manage users,
organizations, and their workspaces and nodes.
You must provide the following environment variables for interacting with the platform through the CLI:
TENZIR_PLATFORM_CLI_API_ENDPOINT=api.platform.example.org:5000
TENZIR_PLATFORM_CLI_OIDC_ISSUER_URL=YOUR_OIDC_ISSUER_URL
TENZIR_PLATFORM_CLI_OIDC_CLIENT_ID=YOUR_OIDC_CLIENT_ID
TENZIR_PLATFORM_CLI_OIDC_AUDIENCE=YOUR_OIDC_AUDIENCE
Read our documentation on the Tenzir Platform CLI to learn more about managing your platform deployment.