Skip to main content
Caravanserai is distributed as source code. You build the three binaries yourself using the Go toolchain.

​
Prerequisites

Before you build, ensure the following are installed and accessible on your PATH:
  • Go 1.22 or later — go version should report go1.22 or higher
  • Docker — the Docker daemon must be running; the agent connects to unix:///var/run/docker.sock by default
  • PostgreSQL 16 — required by cara-server; you can run it locally with Docker
  • Make — used to invoke the build targets in the Makefile

​
Build from source

Clone the repository, then run make build from the project root: 
git clone https://github.com/NYCU-SDC/caravanserai.git
cd caravanserai
make build
make build compiles all three binaries and places them in bin/: 
bin/cara-server
bin/cara-agent
bin/caractrl
To build a single binary, target its subdirectory directly: 
make -C cmd/cara-server build
make -C cmd/cara-agent  build
make -C cmd/caractrl    build
Verify your installation by running ./bin/caractrl version. A successful output confirms the binary is built and executable.

​
What each binary does

cara-server

The control-plane API server and controller manager. Accepts project manifests, runs the scheduler, and exposes a REST API at /api/v1/. Requires PostgreSQL.

cara-agent

The per-node reconciler. Registers with cara-server, sends periodic heartbeats, and creates or removes Docker containers to match the desired state.

caractrl

The command-line client. Sends requests to cara-server. Supports apply, get, delete, port-forward, and version subcommands.

​
Environment configuration

Each component is configured through environment variables (or a config.yaml / .env file in the working directory). Environment variables take precedence.
VariableDefaultDescription
DATABASE_URL(required)PostgreSQL DSN, e.g. postgresql://user:pass@host:5432/db?sslmode=disable
HOST0.0.0.0Address the server listens on
PORT8080Port the server listens on
DEBUGfalseEnable verbose debug logging
OTEL_COLLECTOR_URL(optional)OTLP gRPC endpoint for OpenTelemetry traces
Minimal startup example:
DATABASE_URL="postgresql://postgres:password@localhost:5432/caravanserai?sslmode=disable" \
  ./bin/cara-server
# Listening on 0.0.0.0:8080
DATABASE_URL has no default value. cara-server will refuse to start if this variable is not set or points to an unreachable PostgreSQL instance.