Skip to main content

Deployment

This guide explains how to run the Arcane stack using the arcane-deployment repository and Docker Compose.

Prerequisites​

  • Docker and Docker Compose
  • Images are pre-built and published to a Docker registry; Compose pulls them automatically

Clone arcane-deployment​

Clone or navigate to the arcane-deployment repository:

git clone git@github.com:ArcaneTracing/arcane-deployment.git arcane-deployment
cd arcane-deployment

Choose a Compose​

Select a compose file based on your trace backend and message broker needs:

VariantTrace BackendMessage BrokerCompose File
BaseNoneRabbitMQbase/docker-compose.base.yml
TempoTempoRabbitMQtempo/docker-compose.tempo-rabbitmq.yml
TempoTempoKafkatempo/docker-compose.tempo-kafka.yml
JaegerJaegerRabbitMQjaeger/docker-compose.jaeger-rabbitmq.yml
JaegerJaegerKafkajaeger/docker-compose.jaeger-kafka.yml
ClickHouseClickHouseRabbitMQclickhouse/docker-compose.clickhouse-rabbitmq.yml
ClickHouseClickHouseKafkaclickhouse/docker-compose.clickhouse-kafka.yml
  • Base: Minimal run (postgres, rabbitmq, frontend, backend, worker). No trace backend.
  • Trace variants: Add Grafana Tempo, Jaeger, or ClickHouse for trace storage and querying.
  • RabbitMQ: Lightweight message broker.
  • Kafka: Distributed message broker for higher throughput.

Quick Start​

  1. Copy .env.example to .env and set values for production, or use defaults for local dev:
cp .env.example .env
# Edit .env as needed
  1. Run the compose of your choice:
# Base (minimal, no trace backend)
docker compose -f base/docker-compose.base.yml up -d

# Example: Tempo + RabbitMQ
docker compose -f tempo/docker-compose.tempo-rabbitmq.yml up -d

# Example: ClickHouse + Kafka
docker compose -f clickhouse/docker-compose.clickhouse-kafka.yml up -d

Access URLs​

ServiceURL
Frontendhttp://localhost:3000
Backend APIhttp://localhost:8085
Jaeger UIhttp://localhost:16686 (Jaeger variants only)
RabbitMQ Managementhttp://localhost:15672 (RabbitMQ variants)
Tempohttp://localhost:3200 (Tempo variants)
ClickHousehttp://localhost:8123 (ClickHouse variants)
Kafkalocalhost:9092 (Kafka variants)

Environment Variables​

All compose files use environment variables. Set them in .env or export before running.

Database​

VariableDescriptionDefault
DATABASE_URLPostgreSQL connection stringpostgresql://user:password@postgres:5432/arcanedb
DATABASE_SSLEnable SSL for DBfalse
POSTGRES_USERPostgres container useruser
POSTGRES_PASSWORDPostgres container passwordpassword
POSTGRES_DBPostgres database namearcanedb

Message Broker​

RabbitMQ variants:

VariableDescriptionDefault
RABBITMQ_URLRabbitMQ connection URLamqp://guest:guest@rabbitmq:5672/

Kafka variants:

VariableDescriptionDefault
KAFKA_BROKERSComma-separated broker listkafka:9092

Auth & Security (required in production)​

VariableDescriptionDefault
BETTER_AUTH_SECRETAuth token encryptiondev-secret-change-in-production
JWT_SECRETJWT signing keydev-jwt-secret
ENCRYPTION_KEY32+ char key for model config encryptiondev-encryption-key-32-chars!!
API_KEY_SALTSalt for API key hashingdev-api-key-salt

Generate secure values: openssl rand -base64 32

URLs​

VariableDescriptionDefault
BETTER_AUTH_URLBackend URL (auth callbacks)http://localhost:8085 or http://backend:8085
FRONTEND_URLFrontend URL (CORS, redirects)http://localhost:3000 or http://frontend:3000

SMTP (optional, for invite emails)​

VariableDescriptionDefault
SMTP_HOSTSMTP server host(empty)
SMTP_PORTSMTP port587
SMTP_SECUREUse TLSfalse
SMTP_USERSMTP username(empty)
SMTP_PASSSMTP password(empty)
MAIL_FROMFrom addressno-reply@example.com

Optional​

VariableDescription
ARCANE_ENTERPRISE_LICENSEEnterprise license key (base64)

Defaults in the compose files are suitable for local development only. For production, always set secure secrets and configure SMTP if you plan to send organisation invites.