Skip to main content
By default the installer runs a ClickHouse server next to Platinur on the same host. In external mode, no ClickHouse container runs at all — the control plane, worker, and Evidence connect to your warehouse over the network, with TLS by default. This page is about where the warehouse itself runs. For how source data gets into the warehouse — whoever runs it — see External ClickHouse Schemas.

​
When to choose external ClickHouse

  • You already operate a ClickHouse cluster, or use ClickHouse Cloud.
  • The data is too large to live in a Docker volume on the Platinur host.
  • Data locality: warehouse data stays in your cluster, region, or cloud account, and the Platinur host only orchestrates against it.

​
Configure .env

Set these in the installer’s .env before running install: 
EXTERNAL_CLICKHOUSE=true
CLICKHOUSE_HOST=your-warehouse.example.com
CLICKHOUSE_HTTP_PORT=8443
CLICKHOUSE_NATIVE_PORT=9440
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=<your warehouse password>
CLICKHOUSE_SECURE=true
  • EXTERNAL_CLICKHOUSE=true selects external mode.
  • CLICKHOUSE_HOST — the warehouse hostname, without a scheme or port.
  • CLICKHOUSE_HTTP_PORT (default 8443) and CLICKHOUSE_NATIVE_PORT (default 9440) — the HTTP(S) and native interfaces.
  • CLICKHOUSE_USER (default default) and CLICKHOUSE_PASSWORD — the warehouse credentials Platinur uses.
  • CLICKHOUSE_SECURE=true (the default) connects over TLS.
In the bundled profile CLICKHOUSE_PASSWORD is generated for you; in external mode you must set CLICKHOUSE_HOST and CLICKHOUSE_PASSWORD yourself — install refuses to proceed until both are present.

​
Warehouse permissions

The ClickHouse user needs CREATE DATABASE and full rights on Platinur’s output schemas — raw, stg, dw, and marts, plus their staging and validation variants. Platinur creates these databases and manages their contents; it also needs read access to whatever source schemas you load yourself.

​
Install and verify

./platinur install <version>
The same command as the bundled profile — EXTERNAL_CLICKHOUSE=true makes the CLI select the external-ClickHouse Compose file automatically, so no ClickHouse container is started. 
./platinur doctor
In external mode, doctor’s ClickHouse check runs a query from the worker against your warehouse; a failure there points at CLICKHOUSE_HOST/CLICKHOUSE_PASSWORD or network/TLS reachability. ./platinur backup covers Platinur state only — back up the warehouse with your cluster’s or ClickHouse Cloud’s own tooling (see Backup and Restore).

​
Network access

The Platinur host must reach the warehouse on both configured ports. If the warehouse sits behind a firewall or IP allowlist, allowlist the Platinur host’s egress IP; for managed deployments, ask Platinur for the hosting VM’s egress IP.

​
ClickHouse Cloud

The defaults match ClickHouse Cloud: HTTPS on 8443, native TLS on 9440, and CLICKHOUSE_SECURE=true. Set CLICKHOUSE_HOST to the hostname from your service’s connection details and use its credentials. One Cloud behavior to know: trial and development services idle when unused, and the first query after idling is slow while the service wakes — a sluggish first doctor check or source load after a quiet period is expected.

​
Loading source data

Nothing changes: one source maps to one ClickHouse schema, whether Platinur loads it or your own ingestion does. See External ClickHouse Schemas for how externally loaded schemas are discovered and selected for modeling.