Deploy ClickHouse with Dokploy

Dokploy is an open-source server management platform that simplifies deploying Docker Compose applications on your VPS. It handles reverse proxy configuration, SSL certificates, and deployment management — making it straightforward to run ClickHouse as a high-performance analytics database.

This guide walks you through deploying ClickHouse with persistent data storage, user authentication, and HTTPS access to the HTTP interface. ClickHouse is a column-oriented OLAP database designed for real-time analytics on large datasets.

Prerequisites

• A VPS with at least 2 vCPUs, 4 GB RAM, and 50 GB storage (scales with data volume)
• Dokploy installed and running on your server (installation docs)
• A domain name (e.g., clickhouse.yourdomain.com) with DNS A record pointing to your server's IP

Docker Compose Configuration

Create a new Compose project in Dokploy and paste the following configuration:

version: "3.8"

services:
  clickhouse:
    image: clickhouse/clickhouse-server:latest
    restart: unless-stopped
    ports:
      - "8123:8123"
      - "9000:9000"
    environment:
      - CLICKHOUSE_DB=${CLICKHOUSE_DB:-default}
      - CLICKHOUSE_USER=${CLICKHOUSE_USER:-default}
      - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD}
      - CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1
    volumes:
      - ../files/clickhouse-data:/var/lib/clickhouse
      - ../files/clickhouse-logs:/var/log/clickhouse-server
    ulimits:
      nofile:
        soft: 262144
        hard: 262144
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8123/ping || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3

Note: ClickHouse exposes two ports: 8123 for HTTP queries (used by web clients and REST APIs) and 9000 for the native TCP protocol (used by clickhouse-client and BI tools). The ulimits setting is required — ClickHouse needs a high file descriptor limit to operate correctly.

Environment Variables

Set these in Dokploy's Environment tab for your compose project:

Variable	Purpose	Example
CLICKHOUSE_DB	Default database name	default
CLICKHOUSE_USER	Default username	default
CLICKHOUSE_PASSWORD	User password	a-strong-password

In Dokploy, environment variables are set via the Environment editor in the project settings. Do not create a .env file manually — Dokploy manages this for you. Setting CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 enables SQL-driven user management for creating additional users and roles.

Volumes & Data Persistence

This setup uses Dokploy's ../files convention for bind-mounted volumes:

• ../files/clickhouse-data — Database tables, indexes, and metadata
• ../files/clickhouse-logs — ClickHouse server and query logs

The ../files path is relative to the compose file inside Dokploy's project directory. This ensures your data persists across redeployments. Avoid using absolute paths (e.g., /opt/clickhouse) because Dokploy may clean them during redeployment.

If you need S3 backup support, consider using named Docker volumes instead. Named volumes can be backed up with Dokploy's built-in backup features. ClickHouse also supports S3-backed storage natively via its s3 table engine.

Domain & SSL Setup

1. In your Dokploy project, navigate to the Domains tab
2. Click Add Domain and enter your domain (e.g., clickhouse.yourdomain.com)
3. Set the container port to 8123 (HTTP interface)
4. Enable HTTPS — Dokploy automatically provisions a Let's Encrypt SSL certificate
5. Save and wait for the certificate to be issued (usually under a minute)

Dokploy's built-in Traefik reverse proxy handles TLS termination and routes traffic to ClickHouse's HTTP interface. The native TCP port (9000) is accessible directly via the server's IP for client connections.

Verifying the Deployment

1. In Dokploy, go to your project's Deployments tab and click Deploy
2. Watch the build logs — you should see the clickhouse container pull and start
3. Check the Logs tab for the clickhouse service. Look for: Ready for connections
4. Open https://clickhouse.yourdomain.com/ping — you should see Ok.
5. Test a query: curl "https://clickhouse.yourdomain.com/?query=SELECT%201" --user default:your-password
6. Optionally connect with clickhouse-client --host your-server-ip --port 9000 --user default --password your-password

Troubleshooting

ClickHouse fails to start with file descriptor errors ClickHouse requires a high nofile ulimit (at least 262144). Ensure the ulimits section is present in the compose file. On some systems, the Docker daemon itself may need its ulimit increased in /etc/docker/daemon.json.

Authentication errors Ensure CLICKHOUSE_PASSWORD is set before the first run. If the container was started without a password, the default user has no password. You may need to remove the data volume and redeploy, or manually edit the user config inside the container.

Slow queries or high memory usage ClickHouse is designed for analytical workloads and can consume significant memory for large queries. Monitor memory via system.query_log and consider setting max_memory_usage limits in ClickHouse's user profile configuration.

SSL certificate not issuing Ensure your domain's DNS A record points to your server's IP and has propagated. Dokploy uses Let's Encrypt HTTP-01 challenges, so port 80 must be accessible. Check Traefik logs in Dokploy for certificate-related errors.

---

Learn more about ClickHouse in our complete overview.

Need a VPS? Hostinger VPS starts at $4.99/mo — perfect for running ClickHouse.

---

For more on Docker Compose deployments in Dokploy, see the Dokploy Docker Compose documentation.

App data sourced from selfh.st open-source directory.