--- title: "Deploy Clickhouse" description: "Columnar database for fast analytics queries over very large tables" category: "Analytics" url: https://railway.com/deploy/clickhouse-analytics --- # Deploy Clickhouse Columnar database for fast analytics queries over very large tables **[Deploy Clickhouse on Railway](https://railway.com/template/clickhouse-analytics)** - **Creator:** A3A - **Category:** Analytics - **Total deploys:** 1 ## Template content ### clickhouse-2 https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/clickhouse.svg - **Source:** https://github.com/gridalpha/clickhouse-railway ### keeper-2 https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/clickhouse.svg - **Source:** https://github.com/gridalpha/clickhouse-railway ### clickhouse-1 https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/clickhouse.svg - **Source:** https://github.com/gridalpha/clickhouse-railway ### keeper-1 https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/clickhouse.svg - **Source:** https://github.com/gridalpha/clickhouse-railway ### proxy - **Source:** https://github.com/gridalpha/clickhouse-railway - **Public domain:** Yes ### keeper-3 https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/clickhouse.svg - **Source:** https://github.com/gridalpha/clickhouse-railway ## Documentation ![ClickHouse logo](https://media.holistics.io/cc879e35-2025-12-clickhouse.jpg) # Deploy and Host ClickHouse on Railway ClickHouse is an open-source columnar database built for analytical queries over very large tables. It stores each column separately, compresses it hard, and scans billions of rows per second on ordinary hardware — which is why it sits underneath Plausible, PostHog, Langfuse and most self-hosted event pipelines. Teams reach for it when Postgres starts timing out on a `GROUP BY` over a year of events. Deploy ClickHouse on Railway as a replicated cluster rather than a single container. This template runs upstream's *replication for fault tolerance* topology: one shard held by two servers, `clickhouse-1` and `clickhouse-2`; a three-node ClickHouse Keeper ensemble, `keeper-1` to `keeper-3`, coordinating them; and a Caddy `proxy` owning the only public domain. Rows written to either replica appear on both, and the proxy routes to the first healthy one, failing over when it stops answering. Self-host ClickHouse on Railway and all five stateful nodes keep a volume at `/var/lib/clickhouse`. ![Diagram of ClickHouse, Keeper and proxy services on Railway](https://res.cloudinary.com/rroe4rtk/image/upload/v1787126364/clickhouse-architecture.png) ## Getting Started with ClickHouse on Railway Set a password for the `default` user at deploy time — the server refuses to start without one and stores it as a SHA-256 hash, never plaintext. Wait for all six services to go green: the Keeper nodes elect a leader within seconds, and the servers register once a quorum exists. Open the public URL and you land on **ClickHouse Play**, the built-in SQL console. Sign in as `default` with your password, run `SELECT 1`, then create your first replicated table. `ON CLUSTER default_cluster` is the part that matters — it applies the DDL to both replicas instead of one: ``` CREATE TABLE page_views ON CLUSTER default_cluster (ts DateTime, path String, country String) ENGINE = ReplicatedMergeTree ORDER BY (ts, path); ``` Insert a few rows, then check `SELECT active_replicas, absolute_delay FROM system.replicas` — `2, 0` means replication is healthy. Applications use the same URL over the HTTP interface, so any ClickHouse client, `curl` or the JDBC/ODBC drivers work. Note `/dashboard` is broken in current upstream builds and renders no charts; `/play` is the usable interface. ![ClickHouse Play running a page-views aggregation over 200,000 rows](https://res.cloudinary.com/rroe4rtk/image/upload/v1787126368/clickhouse-play-page-analytics.png) ![ClickHouse Play showing identical row counts on both replicas](https://res.cloudinary.com/rroe4rtk/image/upload/v1787126371/clickhouse-play-replica-row-counts.png) ## About Hosting ClickHouse ClickHouse answers analytical questions — counts, sums, percentiles, funnels — over tables too big for a row store to scan interactively. It does not replace a transactional database; it goes beside one when reporting queries start hurting. Self-host it when per-query cloud pricing turns unpredictable, or when the data cannot leave your infrastructure. Key features: - **Columnar storage with aggressive compression** — often 10x or better on event data - **Vectorised execution** scanning hundreds of millions of rows per second per core - **`ReplicatedMergeTree`** — multi-master replication, either replica taking writes - **Materialised views** that roll data up as it is inserted, not on a schedule - **Table engines** reading Kafka, S3, Postgres and MySQL directly Each service has one job. **clickhouse-1** and **clickhouse-2** are full copies of the same shard, each with its own volume, serving HTTP on 8123 and the native protocol on 9000, and exchanging data parts on 9009. **keeper-1** to **keeper-3** hold the replication log and decide which replica merges which part. **proxy** is Caddy, holding the public HTTPS endpoint and health-checking both replicas on `/ping`. ## Why Deploy ClickHouse on Railway Railway removes the setup work that makes a replicated cluster a project of its own. - Six services, five volumes and the cluster topology in one deploy - Keeper ensemble and replica registration configured at boot - Private networking between nodes; only the proxy is public - Automatic failover to the second replica if the first goes unhealthy - Vertical scaling per service, so Keeper stays small while servers grow ## Common Use Cases - **Product and web analytics** — the storage layer behind self-hosted Plausible, PostHog or a homegrown event pipeline - **Observability data** — logs, traces and metrics at volumes that make per-GB ingest pricing painful - **Customer-facing dashboards** where each page load aggregates over millions of rows - **AI and LLM telemetry** — token usage, latency and cost per request, as Langfuse stores it ## Dependencies for ClickHouse - `clickhouse/clickhouse-server:26.3` — the database, run twice as two replicas of one shard - `clickhouse/clickhouse-keeper:26.3` — coordination, run three times as a raft ensemble - `caddy:2-alpine` — the public HTTPS front door and health-checking load balancer - Five Railway volumes at `/var/lib/clickhouse`, one per stateful service Both images are pinned to `26.3`, the current long-term-support line, supported until March 2027. Server and Keeper must run the same version, and the tag keeps moving within `26.3.x`, so patch releases still arrive on redeploy while the on-disk format stays put. ### Environment Variables Reference | Variable | Service | Purpose | |---|---|---| | `CLICKHOUSE_PASSWORD` | servers | Password for the `default` user; required | | `CLICKHOUSE_DB` | servers | Optional database created on first boot | | `CLICKHOUSE_REPLICA_ID` | servers | The `{replica}` macro; must differ per replica | | `CLICKHOUSE_CLUSTER` | servers | Cluster name used by `ON CLUSTER` | | `KEEPER_HOSTS` | servers, Keeper | Ensemble members, in raft id order | | `KEEPER_SERVER_ID` | Keeper | Raft id; matches the node's place in `KEEPER_HOSTS` | | `CLICKHOUSE_UPSTREAMS` | proxy | Replica addresses the proxy balances across | | `CLICKHOUSE_LOG_LEVEL` | servers, Keeper | `information`; `trace` exceeds Railway's log cap | ### Deployment Dependencies - Source: [ClickHouse/ClickHouse](https://github.com/ClickHouse/ClickHouse) (Apache-2.0) - Docker Hub: `clickhouse/clickhouse-server`, `clickhouse/clickhouse-keeper`, `caddy` - Docs: [clickhouse.com/docs](https://clickhouse.com/docs) — SQL reference, table engines, replication ## Hardware Requirements for Self-Hosting ClickHouse Sized per ClickHouse server; Keeper nodes are far lighter. | Resource | Minimum | Recommended | |---|---|---| | CPU | 2 vCPU | 4–8 vCPU per replica | | RAM | 2 GB (low ingest only) | 8–32 GB, more for interactive queries | | Storage | 10 GB volume | 50 GB+, sized by retention after compression | | Runtime | x86-64 with SSE 4.2, or ARM64 | SSD-backed storage | ClickHouse reads its cgroup limits on Railway, sizing thread pools and memory to the plan you pick. Keeper nodes run in 512 MB — they hold coordination metadata, not table data. ## Self-Hosting ClickHouse A single node is one container, with a password set and the HTTP interface published: ``` docker run -d --name clickhouse \ -e CLICKHOUSE_PASSWORD=your-password \ -p 8123:8123 -p 9000:9000 \ -v clickhouse-data:/var/lib/clickhouse \ clickhouse/clickhouse-server:26.3 ``` Replication needs Keeper too, plus `remote_servers` and `zookeeper` config blocks on each server — that XML is what this template renders at boot. Once running, the HTTP interface takes SQL as a plain POST body, which is how most ingestion works: ``` curl -u default:your-password --data-binary \ "INSERT INTO page_views FORMAT JSONEachRow {\"path\":\"/pricing\"}" \ https://your-clickhouse-host/ ``` ## Is ClickHouse Free to Self-Host? ClickHouse is open source under Apache-2.0, with no paid tiers, seat limits or feature gates — replication, materialised views and every table engine ship in the same build. ClickHouse Cloud is the managed offering, billed on compute and storage. Self-hosting replaces that bill with infrastructure: on Railway you pay for the compute and the five volumes. ## FAQ **What is ClickHouse?** An open-source columnar OLAP database. It stores data by column and runs queries in a vectorised engine, so aggregations over hundreds of millions of rows return in well under a second. **What does this Railway template deploy?** A replicated ClickHouse cluster: two servers holding one shard, a three-node Keeper ensemble coordinating them, and a Caddy proxy as the only public service, plus five volumes. **Why does the template include ClickHouse Keeper?** Replicated tables need a consensus store for the replication log and for deciding which replica performs each merge. Keeper is ClickHouse's ZooKeeper-compatible implementation, and three nodes form a quorum that survives losing one. **How do I connect to self-hosted ClickHouse on Railway from my application?** Point your client at the public HTTPS URL with the `default` user and your password — the HTTP interface is what most drivers use. Services in the same project can skip the proxy and reach a replica privately on 9000 (native) or 8123 (HTTP). **Do I have to create tables with ON CLUSTER?** For anything replicated, yes. A plain `MergeTree` created without it exists only on the replica that received the statement — that is ClickHouse's design. Pair `ON CLUSTER default_cluster` with `ReplicatedMergeTree` and both replicas stay in step. To add a third replica later, copy the server service with the next `CLICKHOUSE_REPLICA_ID` and add it to `CLICKHOUSE_REPLICAS`. ## Similar templates - [Betterlytics](https://railway.com/deploy/betterlytics) — Betterlytics is a cookieless analytics platform GDPR-compliant. - [Finance Tracker](https://railway.com/deploy/finance-tracker-1) — Private multi-user household finance ledger with budgets and CSV import. - [Matomo Analytics + MariaDB](https://railway.com/deploy/matomo-analytics-mariadb) — Privacy-friendly analytics with MariaDB and persistent volumes. Open this page in a browser: https://railway.com/deploy/clickhouse-analytics