ClickHouse

This guide walks you through deploying ClickHouse to Magic Containers, either as a standalone container or as part of a multi-container app alongside your application. You’ll need a bunny.net account with Magic Containers enabled.

Quickstart

Create a new app

Go to the bunny.net dashboard, select Magic Containers, and click Add App. Select Single region deployment.

Databases should use single region deployment with a single instance. Each pod gets its own dedicated volume with no data replication — this applies both across regions and within the same region. Scaling to multiple pods or regions would result in separate, isolated databases each with their own data.

Add the ClickHouse container

Click Add Container and configure the image:

Registry: Docker Hub
Image: clickhouse/clickhouse-server
Tag: latest

Magic Containers will automatically detect the required endpoint and environment variables for the image. Configure the environment variables as needed:

CLICKHOUSE_DB = app
CLICKHOUSE_USER = app
CLICKHOUSE_PASSWORD = a strong password
CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT = 1

Add persistent volumes

In the Volumes section of the container settings, add two volumes:

Name: clickhouse-data, Mount path: /var/lib/clickhouse
Name: clickhouse-logs, Mount path: /var/log/clickhouse-server

This ensures your database files and logs persist across restarts and redeployments. Without volumes, all data is lost when the container stops.See persistent volumes for more details on volume behavior and pricing.

Deploy

Review your settings and click Confirm and Create.

Always set a strong CLICKHOUSE_PASSWORD, even if ClickHouse is not exposed externally. Other containers in the same pod can access the network, and a password protects against accidental or unauthorized access.

Environment variables

The official ClickHouse image supports these environment variables:

Variable	Description	Default
`CLICKHOUSE_DB`	Default database created on start	`default`
`CLICKHOUSE_USER`	Username to create	`default`
`CLICKHOUSE_PASSWORD`	Password for the user	-
`CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT`	Enable SQL-driven access management	`0`

Connect from your app

In a multi-container setup, your app and ClickHouse share the same localhost network. ClickHouse exposes two interfaces:

HTTP: port 8123
Native: port 9000

HTTP
Node.js
Go
Python

http://app:YOUR_PASSWORD@127.0.0.1:8123/?database=app

import { createClient } from "@clickhouse/client";

const client = createClient({
  url: "http://127.0.0.1:8123",
  username: "app",
  password: process.env.CLICKHOUSE_PASSWORD,
  database: "app",
});

const result = await client.query({ query: "SELECT now()" });

import "github.com/ClickHouse/clickhouse-go/v2"

conn, err := clickhouse.Open(&clickhouse.Options{
	Addr: []string{"127.0.0.1:9000"},
	Auth: clickhouse.Auth{
		Database: "app",
		Username: "app",
		Password: os.Getenv("CLICKHOUSE_PASSWORD"),
	},
})
if err != nil {
	log.Fatal(err)
}
defer conn.Close()

import clickhouse_connect

client = clickhouse_connect.get_client(
  host="127.0.0.1",
  port=8123,
  username="app",
  password=os.environ["CLICKHOUSE_PASSWORD"],
  database="app",
)

result = client.query("SELECT now()")

Multi-container example

A typical setup pairs ClickHouse with your application. When configuring the app, add two containers:

App container

Image: your app image (e.g. ghcr.io/<your-username>/my-app:latest)
Endpoint: the port your app listens on
Environment variables:
- CLICKHOUSE_PASSWORD = a strong password

ClickHouse container

Image: clickhouse/clickhouse-server:latest
Volumes: /var/lib/clickhouse and /var/log/clickhouse-server
Environment variables:
- CLICKHOUSE_DB = app
- CLICKHOUSE_USER = app
- CLICKHOUSE_PASSWORD = a strong password
- CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT = 1

Both containers share the same localhost network, so your app connects to ClickHouse at 127.0.0.1:8123 (HTTP) or 127.0.0.1:9000 (native). See multi-container apps for more details.

External access

To connect to ClickHouse from outside Magic Containers (e.g. from your local terminal), add an Anycast endpoint:

Go to your app’s Endpoints tab and click Add New Endpoint
Select Anycast as the type
Set Container Port to 8123
Set Exposed Port to 8123
Click Add Endpoint

Then connect using the Anycast IP and the exposed port:

curl "http://<anycast-ip>:<exposed-port>/?query=SELECT+1&user=app&password=YOUR_PASSWORD"

Or using the ClickHouse client:

clickhouse-client --host <anycast-ip> --port <exposed-port> --user app --password YOUR_PASSWORD

The exposed port and container port may differ. When connecting externally, always use the exposed port shown in your endpoint configuration.

The clickhouse-client uses the native protocol (port 9000). If you want to use the native client externally, add a second Anycast endpoint for port 9000.

Exposing your database to the internet means anyone with the credentials can connect. Use a strong password and consider removing the Anycast endpoint when external access is no longer needed.

Documentation

Deployment

Managing Apps

Observability

Platform

Reference

Tutorials

Quickstart

Environment variables

Connect from your app

Multi-container example

App container

ClickHouse container

External access

Documentation

Deployment

Managing Apps

Observability

Platform

Reference

Tutorials

​Quickstart

​Environment variables

​Connect from your app

​Multi-container example

​App container

​ClickHouse container

​External access

Quickstart

Environment variables

Connect from your app

Multi-container example

App container

ClickHouse container

External access