Docker Compose

Docker Compose lets you run Breadcrumb on any machine with Docker installed - a VPS, a cloud instance, or your own hardware.

Prerequisites

• Docker and Docker Compose installed
• Git installed

Setup

Clone the repository

git clone https://github.com/joshuaKnauber/breadcrumb.git
cd breadcrumb

Configure environment variables

cp services/server/.env.example services/server/.env

Open services/server/.env and update the following values:

# Generate a random secret for authentication
BETTER_AUTH_SECRET=your-random-secret-here

# Set this to the public URL where you'll access Breadcrumb
APP_BASE_URL=https://your-domain.com

# Use the Docker service names for database connections
DATABASE_URL=postgres://postgres:postgres@postgres:5432/breadcrumb
CLICKHOUSE_URL=http://clickhouse:8123
CLICKHOUSE_DB=breadcrumb

# Generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
ENCRYPTION_KEY=your-generated-key

# Production settings
PORT=3100
NODE_ENV=production

ClickHouse sandbox user

Breadcrumb uses a dedicated ClickHouse user with row-level security to isolate user-provided SQL queries. The sandbox user, role, and row policies are created automatically by the server on first startup.

If you're using the provided Docker Compose setup, this works out of the box — the required custom_settings_prefixes configuration is mounted automatically.

If you're connecting to an external ClickHouse instance, you need to add the following to your ClickHouse server config (e.g. config.d/custom.xml):

<clickhouse>
    <custom_settings_prefixes>SQL_</custom_settings_prefixes>
</clickhouse>

The ClickHouse user specified by CLICKHOUSE_USER must have permission to create roles, users, and row policies (this is the default for the default user).

You can override the sandbox credentials in your .env:

CLICKHOUSE_SANDBOX_USER=breadcrumb_sandbox
CLICKHOUSE_SANDBOX_PASSWORD=breadcrumb_sandbox_local

Start the services

The repo includes a docker-compose.prod.yml with healthchecks and restart policies preconfigured.

docker compose -f docker-compose.prod.yml up -d --build

Breadcrumb will be available at http://your-server-ip:3100.

Updating

Pull the latest changes and rebuild:

git pull
docker compose -f docker-compose.prod.yml up -d --build

Next Steps