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:
| Repository | Adapter | Typical container hostname and port |
|---|---|---|
| MySQL / MariaDB | mysql | mysql:3306 |
| PostgreSQL | postgres | postgres:5432 |
| MongoDB | mongodb | mongo: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.