Running ClickHouse in Docker for production: what changes after the quick start
A team that ran the official ClickHouse quick-start container for a proof of concept needs to change its assumptions before that container holds real event or log data. The production work centers on five areas: persistent state for data and logs, layered configuration through config.d and users.d, process limits such as ulimits, network exposure, and upgrades by image tag. The server itself is open source under the Apache License 2.0, so the licensing question is settled, and the remaining decisions are operational. Docker is a sound choice when one team owns a small number of hosts, has container experience, and can keep the image, volumes and host tuning under its own change control. When the organization already runs Kubernetes, the ClickHouse operator path and cluster tooling may fit better, and when hosts are managed as plain Linux servers, native packages are often simpler to patch.
Image tags decide what you are running and how long it stays supported. ClickHouse documents that stable releases ship roughly monthly, that the three latest stable releases receive diagnostics and bug fix backports, and that LTS releases ship twice a year and are supported for a year. Its security policy lists 26.9, 26.8, 26.7 and 26.3 as currently supported. Before you pin a tag, confirm against the security policy which lines are still supported, choose either a stable or an LTS line deliberately, and plan an upgrade cadence that stays inside that window. Pin exact tags rather than latest, so a pull on a new host never changes the server version without a change record.
Plan the container around state from the start. Mount a host or storage volume at the data directory and a separate one for logs, so that replacing the container does not discard parts or force a full resync. Keep every server setting in override files mounted read-only into config.d and users.d, not in edits inside the container. Set file-descriptor and process ulimits explicitly on the container runtime, because the defaults are often too low for a server with many parts and connections. Publish only the ports your clients need, and confirm the default user is restricted before the service is reachable from any other network. Finally, rehearse an image upgrade and a restore on a non-production copy with representative data, since replication does not protect against bad data or operator error.
Which container options fit which production requirement
This table compares the container choices that matter most when a quick-start ClickHouse container becomes a production service. Read each row as a decision: the option, when it fits, what you give up, and what to confirm in your own environment before you commit.
| Decision | When it fits | Operational trade-off and what to confirm |
|---|---|---|
| Named volumes for data and logs | Teams that want Docker to manage storage location and ownership on a single host with no custom host paths | Data survives container replacement, but backup and disk monitoring depend on Docker's storage location. Confirm the host filesystem, free space headroom and that backups read from the volume. |
| Bind mounts for data and logs | Teams that need data on a specific disk, RAID set or filesystem they already monitor and back up | Ownership and permissions must match the UID the ClickHouse process runs as. Confirm the host path, filesystem type and that log directories are rotated. |
| config.d drop-in files | Standard changes such as listen addresses, logging, cluster definitions and storage policies layered over the packaged defaults | Smaller diffs and easier upgrades because the base config stays intact. Confirm that each override file is mounted read-only and tracked in version control. |
| Full config.xml override | Environments that must control every server setting explicitly, or that have a reviewed, complete configuration baseline | Upgrades can silently miss new defaults or deprecated keys. Confirm who reviews the release changelog before each image tag change and who merges new defaults. |
| users.d files for access | Static accounts and profiles defined once at deploy time, with the default user locked down through configuration | Accounts are versioned with the deployment but changes need a container restart or reload. Confirm the password handling path and that secrets are not baked into the image. |
| SQL-driven access control | Environments where accounts, roles, row policies and quotas change often and must be audited | Changes are made at runtime and must be stored durably. Confirm where access objects are kept, how they are backed up and how changes are logged. |
| Host networking | Single-host setups where the container should bind directly to host interfaces and performance or simplicity matter most | Port conflicts and exposure are harder to control because the container shares the host network stack. Confirm firewall rules and which interfaces the server listens on. |
| Published ports with a defined network | Hosts where ClickHouse ports (HTTP, native, interserver replication) must be exposed selectively through a bridge or overlay network | Each published port is an exposure to review. Confirm which ports are reachable from application subnets, which from other replicas and that TLS is applied to exposed interfaces. |
Setup sequence for a production ClickHouse container
This sequence turns a quick-start ClickHouse container into a pinned, configured and tested service with persistent data, controlled access and a verified restore path before any production data is loaded.
Choose and pin a supported image tag
Pick a tag from a release line that is still supported under the ClickHouse security policy, and check it against the production FAQ guidance on stable versus LTS releases. Pin the full tag in your deployment manifest or compose file rather than using a floating tag such as latest, so that every restart runs the same binary. Confirm the tag exists on the official releases page and read the changelog for backward-incompatible changes before you deploy. Done when the tag is written into version control and the running container reports that exact version in a query against the server.
Create persistent volumes for data and logs
Mount separate persistent volumes for the server data directory and the log directory, backed by storage your platform keeps across container restarts and host replacement. Keep the data path on a volume you can snapshot and size for growth, and confirm the filesystem and disk choices against your storage design. Run the container with a test write and restart it to confirm that data and logs survive. Done when a table created before the restart is still present afterward and the log files are written to the log volume.
Mount config.d and users.d overrides
Place server overrides in a config.d directory and user, profile and quota definitions in a users.d directory, both mounted read-only from files kept under version control. Keep the image defaults untouched so that upgrades only need to review your own override files. Include the listen addresses, logging and any cluster settings in these files rather than editing inside the container. Done when the server starts with the mounted files, and a settings query returns the values you set in your override files.
Set file descriptor and memory limits
Set the container's open file limit and memory limit explicitly, using the ulimit and resource settings your container runtime or orchestrator supports, and confirm the values the server reports after startup. ClickHouse opens many files for parts and connections, so a low default can cause failures under load. Size the memory limit against the server settings for maximum memory usage so the server does not exceed what the container allows. Done when a query against the system settings and the runtime limits show the intended values inside the running container.
Publish only the required ports
Expose the HTTP interface, the native TCP interface and the inter-server replication port only where a known client or peer needs them, and keep the rest bound to the container network. Use host or network policy to restrict source addresses, and do not publish the Keeper ports to the wider network unless your cluster design requires it. Confirm the port list in the manifest matches the design document for that environment. Done when a scan from outside the permitted network cannot reach the server, and the allowed clients can still connect.
Restrict the default user
Create named administrative and application users through the SQL access control workflow, assign roles with the least privileges each job needs, and then restrict or disable the default user, which starts with all permissions. Store generated passwords in your secrets manager, not in the mounted files. Test that the new administrative account can log in and that the default user is refused. Done when a login attempt as the default user fails, and a named account can run the expected administrative and read queries.
Start the container and verify with a health query
Start the container with the pinned tag, volumes, mounts, limits and ports in place, then wait for the server to accept connections. Run a simple health query such as SELECT 1 through the HTTP interface and a version query, and check the server log volume for startup errors. Record the version, the health result and the configuration checked in your change record. Done when the health query returns the expected result, the version matches the pinned tag and the logs show no startup errors.
Test a restore before loading data
Before any production data is loaded, create a small test database, take a BACKUP to your chosen destination, drop the test objects, and RESTORE from that backup. The backup documentation warns that a backup never test-restored will probably not restore when needed, so this rehearsal is part of the setup, not an optional extra. Confirm the backup destination and its access permissions in the same run. Done when the restored table returns the same row count and checksum as before the backup, and the result is recorded for the runbook.
Security and operational considerations for a containerized ClickHouse
A container makes ClickHouse easy to start, and easy to start insecurely. The cards below cover the controls to settle before production: who can log in, how secrets and ports are handled, and how data survives mistakes that replication cannot catch.
Restrict the default user
The default user starts with all permissions, so a container exposed with it left active gives any caller full control of the server. Create named administrative users with roles, then disable or restrict default through the users configuration. Test the change in a pre-production container before rollout, because applications and health checks may depend on the default account. Confirm the exact steps for your release against the access control documentation.
Choose external authenticators
ClickHouse supports LDAP authentication and directories, Kerberos, SSL X.509 certificates, an HTTP authenticator and JWT authentication as external authenticators. In a container, these usually mean mounting configuration and reaching the identity service from the container network. Decide which method matches your directory and client tooling, then confirm the required settings, certificate trust and failure behavior with your identity team before you pick one.
Keep secrets out of images
Passwords, certificates and tokens should never be baked into the image or committed to a Dockerfile. Supply them at runtime through a secrets mechanism of your orchestrator or a read-only mount, and keep password hashes out of files that are copied into the image. Plan how secrets rotate and how a container restart picks up the new value. Ask your team which secret store and rotation process applies to your environment.
Limit HTTP and native port exposure
ClickHouse listens on an HTTP port for clients and tools and a native TCP port for the client protocol, and both can be published from a container. Publish them only to the networks that need them, keep inter-node and Keeper traffic on a private network, and encrypt the paths that carry credentials. Review published ports after every compose or manifest change, since a single -p flag can expose a server to the whole host network.
Replication is not a backup
Replicated tables keep copies of data on several nodes, but a bad DELETE, a dropped table or corrupted parts are replicated too. The backup documentation states that replication alone does not protect against human error or corruption. Configure BACKUP to storage outside the container volumes, and schedule restore tests on a spare cluster, since a backup that has never been restored will probably not restore when needed.
Track versions and upgrades
Pin the image to an explicit version tag rather than a floating tag, and read the changelog before each change because minor backward-incompatible changes can occur. Check the security policy to confirm your tag is still supported before you run it. Keep a pre-production container with representative data to rehearse each upgrade and to confirm rollback steps.
Upgrading by image tag without breaking production
Pin every ClickHouse container to an explicit version tag and treat each tag change as a planned release, not a routine pull. The ClickHouse security policy currently lists versions 26.9, 26.8, 26.7 and 26.3 as supported with security updates, and all other versions are unsupported, so confirm your running tag appears on that list before you schedule any work. Stable releases ship roughly every month, and LTS releases ship twice a year with one year of support, so choose a line deliberately: stable for faster access to fixes, or LTS for a slower cadence with a longer support window per release.
Before you change a production tag, read the changelog for every version between your current tag and the target. The ClickHouse production FAQ warns that minor releases can contain backward-incompatible changes, so check settings defaults, removed features and query behavior that your dashboards or ingestion jobs depend on. Then upgrade a pre-production copy that holds representative data and runs your real queries and inserts. Keep the previous image tag, the matching config.d and users.d files and a recent backup, so a failed upgrade can return to the old tag with a known-good configuration.
A single standalone container can be stopped, moved to the new tag and checked in one change window. A replicated cluster cannot, because taking every replica down at once removes availability. Plan a rolling sequence that upgrades one replica at a time, confirms it rejoins and catches up, and only then moves on, with the ClickHouse Keeper nodes handled as their own step. That procedure, including LTS jumps and rollback order, is covered in the ClickHouse upgrades topic, so use it before you touch any replicated environment.
Limits to confirm before you run ClickHouse in containers
A production container inherits the limits of the host, the storage under it and the replicas around it. The cards below cover the items to confirm before go-live, so the container configuration in this guide rests on checked facts rather than assumptions.
Container memory against server needs
ClickHouse sizes its query memory and caches from the memory it can see, so a container memory limit that is set too low causes failed merges and killed queries under load. Confirm the limit your orchestrator enforces, the memory the host keeps for the operating system and page cache, and the query memory settings your workload needs. Run a representative query set in pre-production and watch peak usage before you set the final limit. Ask your platform team who owns the limit when a node is shared with other workloads.
Storage performance and filesystem choice
The data directory sits on a volume that the container writes to constantly, and merge and insert speed depend on how that volume performs. Confirm the storage class, the IOPS and latency your disks deliver under a merge-heavy load, and the filesystem the volume uses. Avoid network filesystems for the data path unless you have tested them against your ingest rate. Record which volume holds data and which holds logs so each can be sized and backed up separately.
Single container availability
One container on one host protects against process crashes, not against host failure, disk loss or a bad upgrade. Decide whether a single instance meets your availability target or whether you need replicas on separate hosts. If you need replicas, the data must live in ReplicatedMergeTree tables, so plan the shard and replica layout before you extend the single-container design. Be explicit about the recovery time you can accept if the one node is lost.
Keeper placement for replication
ClickHouse Keeper coordinates replicated tables, and the replication guide recommends at least three Keeper nodes on dedicated hosts with about 4 GB of RAM each in production. Do not co-locate Keeper with a busy ClickHouse data node if you can avoid it, because they compete for memory and disk. Confirm which hosts run Keeper, how their storage is protected, and how quorum is kept during maintenance. A two-node Keeper setup cannot keep a quorum if one node fails.
Image and tag support status
Before you pin an image tag, check that the version is still supported under the security policy, because only some release lines receive security updates. Confirm the tag you plan to run, whether it is a stable or LTS line, and the date you will need to move to the next line. Record the tag in your configuration management so upgrades are deliberate, and check the changelog for backward-incompatible changes before each move. Ask your security team to confirm the policy applies to the image you pull.
Questions teams ask before running ClickHouse in Docker in production
Is Docker suitable for running ClickHouse in production, or do we need Kubernetes?
Docker is a workable production runtime for a single ClickHouse server, provided the container has persistent volumes, controlled configuration, correct ulimits and a tested upgrade method. Kubernetes becomes the better fit when you need scheduling across many hosts, automated failover, or a standard platform your teams already operate. Replication also changes the answer, because ClickHouse Keeper nodes and replicas must be placed on separate failure domains whichever runtime you choose. Decide the runtime from your operating model, then confirm the storage, networking and restart behavior in a pre-production environment.
What drives the cost of a ClickHouse container deployment?
Cost follows the scope agreed in writing before work starts. The main drivers are the number of servers and shards, whether replication and Keeper are included, how many data sources and integrations must connect, the compliance evidence required, and how much of the existing infrastructure must be built or changed. One-time costs cover design, build, configuration, testing and handover. Recurring costs cover hosting, storage, monitoring, patching, upgrades and any retainer for ongoing support. Ask for a quote that separates these items and states the environments it covers.
How long does a single-node move from a quick-start container take?
The duration depends on scope rather than on a fixed figure. A single node with one data volume, a defined configuration layout and a test environment is a much smaller piece of work than a replicated cluster with Keeper, backups, authentication against LDAP or SSO, and log retention rules. Timing is also affected by how quickly your team can provide hosts, storage, network rules and representative test data. A written scope gives the timeline for your environment, so ask for it to be stated alongside the deliverables.
What must our team provide before the work starts?
You provide the infrastructure and the people who approve decisions. That means hosts or virtual machines with agreed CPU, memory and disk, persistent storage with known performance characteristics, network paths and firewall changes for the ClickHouse ports, DNS and TLS certificates where used, and access to your secret store. You also need a pre-production environment with representative data and queries, because the ClickHouse production guidance recommends testing before upgrades and rollouts. Confirm who owns each item, since most delays come from waiting on these inputs.
Can our internal team set this up without outside help?
Yes, a team with Linux, container and database operations experience can build a single container deployment from the official documentation. The harder parts are the ones teams often underestimate: restricting the default user, configuring external authentication, sizing storage, designing backups and restore tests, and planning upgrades against the supported release lines. Check whether your team has time to run restore tests and monitor the server after go-live. A partner is most useful when the scope is large, the deadline is fixed, or the compliance evidence must be prepared alongside the build.
Which ClickHouse version should a production container use?
Most production use should start from a stable release, with the image tag pinned to a specific version rather than a floating tag. The ClickHouse security policy lists which versions receive security updates, so confirm that your chosen version is on that list before you deploy. Long-term support releases are an alternative for teams that want fewer upgrades. Read the changelog before each upgrade, since minor backward-incompatible changes can occur, and test the new image with your own data and queries first.
Does a Docker deployment meet our compliance requirements?
A container deployment can support compliance work, but it does not satisfy a framework on its own. Controls such as access management, encryption, audit logging, backups and change management must be designed and evidenced in your environment. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports, attestations or certifications; independent auditors and certification bodies do that. Ask early which framework applies, because it changes the logging, retention and access evidence the build must produce.
How DeployOpen scopes and delivers a production ClickHouse container
DeployOpen plans, builds, tests and documents a production ClickHouse container inside infrastructure you control, starting from a written scope that names the images, mounts, ports and upgrade method. Each engagement ends with a container definition, a restore-tested backup path and runbooks your team can operate.
How we scope
- Written scope names the ClickHouse image tag, the release channel and the upgrade policy you will follow.
- Scope lists persistent volumes for data and logs, config.d and users.d mounts, and the ulimits your hosts must allow.
- Scope records the network ports, TLS requirements and which clients or services can reach each port.
How we build
- Build pins the image by tag in your registry, with the container runtime, orchestration and host settings documented.
- Configuration is split into config.d and users.d files so server settings and access control are versioned separately.
- Test cycle runs on a pre-production environment with representative data and queries before any change reaches production.
How we hand over
- Handover includes the container definition, configuration files, an upgrade runbook and a rollback procedure.
- Backup and restore steps are rehearsed on a spare environment, with the results recorded in the handover documents.
- Your team receives documented ownership of image updates, changelog review and restore test schedules.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Retainer work can cover reviewing each stable release changelog before your planned image tag change.
- Confirm with DeployOpen the support hours, response expectations and escalation path in the written agreement.
