Documentation

Deployment

Run Cleave as a compiled server or a container. In either case, supply a TOML configuration, repository credentials, and the network access needed to reach that repository.

Binary installation

Get the build for your platform from the Cleave distribution repository. Follow the release README for extraction, verification, and platform requirements.

The server accepts the configuration file as a positional argument. For an extracted executable named cleave, start it with:

./cleave /path/to/Cleave.toml

Keep the configuration outside the installation directory so a binary upgrade does not overwrite your deployment settings. Run the service with a dedicated operating-system account and repository credentials scoped to its application.

Client libraries are separate from the server. Find them in Cleave clients.

Docker deployment

Docker Compose v2 is sufficient to run the compiled server; no host Rust toolchain or server source checkout is required.

docker pull ghcr.io/cleaveio/cleave:latest

If your package requires private registry access, sign in with your own GitHub username and a token authorized to read the package:

docker login ghcr.io -u YOUR_GITHUB_USERNAME

Enter the token at the password prompt. A public package does not require login.

Mount the server configuration

Save this as compose.yaml, alongside your configured Cleave.toml:

services:
  cleave:
    image: ghcr.io/cleaveio/cleave:latest
    command: ["/etc/cleave/Cleave.toml"]
    volumes:
      - ./Cleave.toml:/etc/cleave/Cleave.toml:ro
    ports:
      - "127.0.0.1:27896:27896"
    restart: unless-stopped
    ulimits:
      nofile:
        soft: 65535
        hard: 65535
    pids_limit: 4096

In Cleave.toml, listen on the container's network interfaces:

[tcp]
address = "0.0.0.0"
port = 27896

[interface]
adapter = "jsonapi"
path_prefix = "/api/0.0/"

These settings are part of the configuration, not a complete deployment file. Add repository access and JWT verification for your application. See Access Control and JWT Authentication.

The port mapping admits connections through the Docker host's loopback address, which suits a same-host backend or reverse proxy. A backend container on the same Compose network can use http://cleave:27896/api/0.0 directly. Its source address will be a container-network address, so any Cleave IP allow-list must match that network arrangement.

Start, inspect, and stop

docker compose up -d
docker compose ps
docker compose logs -f cleave

Ctrl+C exits the log viewer without stopping the service. After changing the mounted TOML configuration, restart Cleave:

docker compose restart cleave

Stop and remove the containers and network with:

docker compose down

Named volumes are retained. Adding -v deletes them; omit it when preserving database or log history. Use persistent storage for repositories and log collectors that you run alongside Cleave.

Repository network access

Cleave must be able to reach its reader and writer endpoints. Use hostnames that resolve from the server's environment and permit the relevant TCP port:

RepositoryAdapterTypical container hostname and port
MySQL / MariaDBmysqlmysql:3306
PostgreSQLpostgrespostgres:5432
MongoDBmongodbmongo:27017

On a shared Compose network, use the database service name. 127.0.0.1 inside the Cleave container identifies Cleave's own container, not the database or host. Database ports do not need to be published to the host for containers on the same network to communicate. See Docker networking.

Choose one of the following repository configurations. Replace the example credentials with an existing application account; these settings do not create a database or user.

MySQL

[dbms]
adapter = "mysql"
address = "mysql"
port = 3306
writer_endpoint = "mysql:3306"
reader_endpoint = "mysql:3306"
user = "cleave_app"
passwd = "replace-with-your-database-password"
schema = "my_application"

PostgreSQL

[dbms]
adapter = "postgres"
address = "postgres"
port = 5432
writer_endpoint = "postgres:5432"
reader_endpoint = "postgres:5432"
user = "cleave_app"
passwd = "replace-with-your-database-password"
schema = "my_application"

MongoDB

[dbms]
adapter = "mongodb"
address = "mongo"
port = 27017
writer_endpoint = "mongo:27017"
reader_endpoint = "mongo:27017"
user = "cleave_app"
passwd = "replace-with-your-database-password"
schema = "my_application"
mongo_auth_source = "admin"

Set mongo_auth_source to the database where that user was created. Use a server build containing the repository adapter you select. Reader and writer endpoints can initially be the same; separate them when your repository topology calls for it.

For managed or remote repositories, replace service names with their reachable DNS names and allow connections from the Cleave deployment. Keep repository credentials in a protected deployment configuration, not frontend code. See Repositories for adapter considerations.

Health checks

Check both the running process and its ability to serve a small resource request. A running container alone does not establish that repository access works.

For a deployment with a person resource, set CLEAVE_TOKEN to an authorized service token and run this from the Docker host:

curl --globoff --fail-with-body --max-time 5 \
  'http://127.0.0.1:27896/api/0.0/person?page[$limit]=1' \
  -H "Authorization: Bearer $CLEAVE_TOKEN" \
  -H 'Accept: application/vnd.api+json'

Replace person with an existing, permitted resource. This checks the HTTP path, authentication, and repository reads without changing data. An empty authorized collection is a valid result. Investigate token expiry and access policy separately from connection failures.

Use your orchestrator or an external probe to run the check. A container health check needs an HTTP client available in its image; do not assume the server image contains curl. Gate startup on repository readiness when the database is part of the same deployment.

Logging and syslog

Start with console logging for Docker's log viewer:

[logging]
type = "console"
level = "notice"

For persistent collection, run a syslog receiver such as rsyslogd as a separate Docker service on the same network. Mount its receiver configuration read-only, persist its output directory in a volume, and run it in the foreground (rsyslogd -n). For example, an rsyslog configuration can receive UDP on port 514 and write a file:

module(load="imudp")
input(type="imudp" port="514")
action(type="omfile" file="/var/log/cleave/cleave.log")

Ensure the receiver can write to the mounted output directory. This follows rsyslog's UDP input configuration. If its Compose service is named rsyslog, point Cleave to it:

[logging]
type = "syslog"
level = "notice"
transport = "udp"
endpoint = "rsyslog:514"

Keep the receiver on the private service network. UDP is a simple local-network option but does not guarantee delivery; select a supported reliable transport when log delivery requirements call for it. Log rotation and retention belong to the collector. See Logging and Metrics.

Throughput and latency metrics

Enable server snapshots separately from operational logging. For the Metrics example's Logstash receiver on the same Docker network:

[metrics]
enabled = true
type = "syslog"
transport = "udp"
endpoint = "logstash:5515"
interval = 10
send_sparse = true
request_latency = true

Replace the endpoint with your metrics receiver. These settings do not install Logstash or its dashboard. The Metrics example and README provide the complete collection and visualization setup; see also Metrics on Download.

Watch request counts, read/write mix, response times, and latency distributions. A ten-second count is not itself TPS: divide the interval count by ten for an average requests-per-second rate. Request throughput is not necessarily the same as completed database transactions or changed rows.

Compare those measurements with repository latency, CPU, I/O, and pool pressure before changing vCPU capacity or reader/writer sizing. Use a representative workload to see whether a change improves latency and useful throughput.

TLS and reverse proxies

See Security: TLS and Reverse Proxies for the current deployment choices.

Detailed certificate provisioning and proxy configuration examples will be added here.

Service management

Platform-specific service units, startup dependencies, and restart policies will be documented here. Docker's basic restart policy is shown above.

Upgrade and rollback

Version-pinning, configuration compatibility checks, staged upgrades, and rollback procedures will be documented here. Use a recorded image tag or digest when you need to reproduce an installed version rather than follow latest.

Backup and recovery

Repository backup, restore testing, configuration backup, and retention procedures will be documented here.