cara-server

cara-server is the control-plane process for Caravanserai. It exposes the REST API that cara-agent instances and caractrl communicate with, runs the scheduler that assigns projects to nodes, and continuously drives workloads toward their desired state. It requires a PostgreSQL database for persistence.

Configuration precedence

cara-server merges configuration from four sources. Later sources override earlier ones:

config.yaml — file in the working directory
.env — dotenv file in the working directory
Environment variables
CLI flags

You do not need to use all four sources. A single .env file or a set of environment variables is sufficient for most deployments.

Configuration reference

boolean

default:"false"

Enable debug-level logging. Set to true to emit verbose structured log output. Env var: DEBUG.

string

default:"0.0.0.0"

IP address for the HTTP server to bind to. Use 127.0.0.1 to restrict access to localhost. Env var: HOST.

string

default:"8080"

TCP port for the HTTP server. Env var: PORT.

string

required

PostgreSQL connection string (DSN). Env var: DATABASE_URL.

database_url is required. cara-server will refuse to start if this value is missing or empty.

Accepted formats:

postgresql://USER:PASSWORD@HOST:PORT/DBNAME?sslmode=disable
postgresql://USER:PASSWORD@HOST:PORT/DBNAME?sslmode=require
postgres://USER:PASSWORD@HOST/DBNAME

string

OTLP gRPC endpoint for OpenTelemetry trace and metric export. Env var: OTEL_COLLECTOR_URL.

otel_collector_url is optional. When omitted, observability export is disabled and cara-server runs without tracing. Set this to the gRPC address of your OpenTelemetry Collector (for example, otel-collector:4317) to enable distributed tracing.

Configuration examples

config.yaml

Place config.yaml in the same directory as the cara-server binary:

config.yaml

debug: false
host: 0.0.0.0
port: 8080
database_url: postgresql://postgres:password@localhost:5432/caravanserai?sslmode=disable
otel_collector_url: otel-collector:4317

.env file

.env

DEBUG=false
HOST=0.0.0.0
PORT=8080
DATABASE_URL=postgresql://postgres:password@localhost:5432/caravanserai?sslmode=disable
OTEL_COLLECTOR_URL=otel-collector:4317

Environment variables (inline)

Pass configuration directly as environment variables when starting the server:

DATABASE_URL="postgresql://postgres:password@localhost:5432/caravanserai?sslmode=disable" \
  ./bin/cara-server

CLI flags

./bin/cara-server \
  -host 0.0.0.0 \
  -port 8080 \
  -database_url "postgresql://postgres:password@localhost:5432/caravanserai?sslmode=disable" \
  -debug

PostgreSQL connection strings

Local development

postgresql://postgres:password@localhost:5432/caravanserai?sslmode=disable

Production with TLS

postgresql://appuser:secret@db.example.com:5432/caravanserai?sslmode=require

Unix socket

postgresql:///caravanserai?host=/var/run/postgresql

Connection pooler (pgBouncer)

postgresql://appuser:secret@pgbouncer:6432/caravanserai?sslmode=require

Run PostgreSQL locally with Docker during development:

docker run -d \
  --name caravanserai-db \
  -e POSTGRES_DB=caravanserai \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=password \
  -p 5432:5432 \
  postgres:16

Get Started

Core Concepts

Manifests

Configuration

Guides

Configuration precedence

Configuration reference

Configuration examples

config.yaml

.env file

Environment variables (inline)

CLI flags

PostgreSQL connection strings

Local development

Production with TLS

Unix socket

Connection pooler (pgBouncer)

​Configuration precedence

​Configuration reference

​Configuration examples

​config.yaml

​.env file

​Environment variables (inline)

​CLI flags

​PostgreSQL connection strings

Local development

Production with TLS

Unix socket

Connection pooler (pgBouncer)

Configuration precedence

Configuration reference

Configuration examples

config.yaml

.env file

Environment variables (inline)

CLI flags

PostgreSQL connection strings