Skip to main content
This guide walks you through building Caravanserai, starting all components, and deploying an nginx project from scratch.
1

Build the binaries

Clone the repository and run make build from the project root. This compiles all three binaries into the bin/ directory.
make build
# Outputs: bin/cara-server  bin/cara-agent  bin/caractrl
2

Start PostgreSQL

cara-server requires a PostgreSQL database. Start a local instance with Docker:
docker run -d \
  --name caravanserai-db \
  -e POSTGRES_DB=caravanserai \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=password \
  -p 5432:5432 \
  postgres:16
3

Start cara-server

Pass the PostgreSQL connection string via DATABASE_URL and start the control-plane server. It listens on 0.0.0.0:8080 by default.
DATABASE_URL="postgresql://postgres:password@localhost:5432/caravanserai?sslmode=disable" \
  ./bin/cara-server
# Listening on 0.0.0.0:8080
4

Start cara-agent

On the same machine (or a different one), start the agent. Provide the server address with SERVER_URL and give the node a name with NODE_NAME.
SERVER_URL=http://localhost:8080 \
NODE_NAME=my-node \
  ./bin/cara-agent
# Agent registers itself, begins heartbeating and polling for work
The agent self-registers with cara-server and immediately begins polling for projects to reconcile.
5

Apply the nginx project manifest

Use caractrl apply to submit the example nginx project. Caravanserai schedules it onto the available node and the agent starts the container.
./bin/caractrl apply -f examples/nginx-project.yaml
# project/nginx-demo created
The manifest at examples/nginx-project.yaml looks like this:
nginx-project.yaml
apiVersion: caravanserai/v1
kind: Project
metadata:
  name: nginx-demo
spec:
  services:
    - name: web
      image: nginx:alpine
6

Verify the project is running

List all projects to confirm nginx-demo reached the Running phase:
./bin/caractrl get projects
Expected output:
NAME         PHASE     NODE      CONDITIONS          AGE
nginx-demo   Running   my-node   ContainersRunning   5s
7

Inspect and clean up

Explore the cluster state and tear down the project when you are done.
# List all registered nodes
./bin/caractrl get nodes

# Get full project details as JSON
./bin/caractrl --output json get projects nginx-demo

# Delete the project — the agent tears down all containers
./bin/caractrl delete project nginx-demo
The examples/ directory contains additional sample manifests, including a multi-service WordPress + MySQL project with volumes. Use them to explore more of what Caravanserai supports.