Get Sluicio running

Sluicio is self-hosted — you run it on your own infrastructure. The fastest way to see it working is the quickstart: the whole stack (Postgres, ClickHouse and the Sluicio services) from a single Docker Compose file, no configuration. This page takes you from nothing to a running Sluicio with telemetry flowing.

Evaluation / local use only

The quickstart ships weak default passwords and no TLS — it’s for trying Sluicio on your machine, not for production. For a real deployment, see Going to production below.

Prerequisites

• Docker Engine with the Compose plugin — docker compose version should print v2 or newer.
• A couple of GB of free RAM for the stack (Postgres + ClickHouse + the services). For sizing beyond a quick trial, see the capacity planner.

1 · Bring up the stack

Save this as docker-compose.yml and run docker compose up -d:

docker-compose.yml

x-ch-env: &ch-env
  CLICKHOUSE_ENDPOINT: clickhouse:9000
  CLICKHOUSE_DATABASE: telemetry
  CLICKHOUSE_USERNAME: ${CLICKHOUSE_USER:-sluicio}
  CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-sluicio_dev}

services:
  postgres:
    image: docker.io/library/postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: controlplane
      POSTGRES_USER: ${POSTGRES_USER:-sluicio}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-sluicio_dev}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d controlplane"]
      interval: 10s
      timeout: 5s
      retries: 5

  clickhouse:
    image: docker.io/clickhouse/clickhouse-server:24.8
    restart: unless-stopped
    ulimits:
      nofile:
        soft: 262144
        hard: 262144
    environment:
      CLICKHOUSE_DB: telemetry
      CLICKHOUSE_USER: ${CLICKHOUSE_USER:-sluicio}
      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-sluicio_dev}
      CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: "1"
    volumes:
      - clickhouse_data:/var/lib/clickhouse
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8123/ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  cell-api:
    image: ${REGISTRY:-ghcr.io}/${NAMESPACE:-sluicio}/cell-api:${TAG:-latest}
    restart: unless-stopped
    depends_on:
      postgres: { condition: service_healthy }
      clickhouse: { condition: service_healthy }
    environment:
      <<: *ch-env
      CELL_API_ADDR: ":8081"
      POSTGRES_DSN: postgres://${POSTGRES_USER:-sluicio}:${POSTGRES_PASSWORD:-sluicio_dev}@postgres:5432/controlplane?sslmode=disable
      SLUICIO_APP_URL: ${SLUICIO_APP_URL:-http://localhost:8080}
      SLUICIO_INGEST_URL: ${SLUICIO_INGEST_URL:-http://localhost:4318}
      SLUICIO_LICENSE_KEY: ${SLUICIO_LICENSE_KEY:-}

  cell-ingest:
    image: ${REGISTRY:-ghcr.io}/${NAMESPACE:-sluicio}/cell-ingest:${TAG:-latest}
    restart: unless-stopped
    depends_on:
      postgres: { condition: service_healthy }
      clickhouse: { condition: service_healthy }
    environment:
      <<: *ch-env
      CELL_INGEST_ADDR: ":4318"
      POSTGRES_DSN: postgres://${POSTGRES_USER:-sluicio}:${POSTGRES_PASSWORD:-sluicio_dev}@postgres:5432/controlplane?sslmode=disable
    ports:
      - "${CELL_INGEST_PORT:-4318}:4318"   # OTLP/HTTP — point your OTel Collector here

  frontend:
    image: ${REGISTRY:-ghcr.io}/${NAMESPACE:-sluicio}/frontend:${TAG:-latest}
    restart: unless-stopped
    depends_on:
      - cell-api
    ports:
      - "${PORT:-8080}:80"                 # ← open http://localhost:8080

volumes:
  postgres_data:
  clickhouse_data:

What it starts:

• postgres — the control plane (orgs, users, integrations, alert rules).
• clickhouse — the telemetry store (traces, metrics, logs).
• cell-api — the API; it migrates Postgres and creates the ClickHouse tables on startup, so the first up is all you need.
• cell-ingest — OTLP/HTTP ingest, published on 4318.
• frontend — the web UI on 8080. It proxies /api to cell-api, so there’s no reverse proxy to configure — the browser talks to one port.

The images come from the public ghcr.io/sluicio registry; every value has a working default, so you don’t have to set anything.

2 · Create your admin account

Open http://localhost:8080. On the first-run screen, create your admin account — and you’re running Sluicio (Community edition).

Headless / scripted setups

Until someone completes the first-run screen or logs in, the cell also has a seeded admin@sluicio.local / admin account (use the “sign in with an existing account” path). The setup endpoint seals itself after the first login — change that password.

3 · Send it telemetry

Ingest is OTLP/HTTP on http://localhost:4318. Point an OpenTelemetry Collector — or any OTLP exporter — at it, authenticated with an ingest key:

1. Mint a key in Settings → Ingest keys.
2. Point your Collector at it — see Point the Collector at Sluicio — or instrument an app directly per Instrument a service.

Send some traffic and your services and traces show up within a few seconds. For what happens next, see What you get from your telemetry.

Stopping and resetting

docker compose down        # stop the stack, keep your data
docker compose down -v     # stop and delete all data (start fresh)

Enterprise features

Community edition is fully functional. To evaluate the Enterprise entitlements (advanced RBAC, audit log, long retention, …), set a license key before starting:

export SLUICIO_LICENSE_KEY="<your-license-key>"
docker compose up -d

Going to production

The quickstart is deliberately unhardened. For a real deployment, Sluicio ships two supported paths:

• Single host — a server Compose bundle behind Caddy (automatic HTTPS), with real secrets, your choice of bundled or external Postgres/ClickHouse, and scheduled Postgres backups.
• Kubernetes — a Helm chart for the cell.

Before you expose it: size the box with the capacity planner, and review the security model (ingest keys, API/MCP tokens, TLS).