Operations

Running the evaluation image beyond a first look: persistence, backup, monitoring and upgrades.

Storage and volumes

Everything the engine owns lives under /data - storage files, indices and the seeded credentials. Mount a volume there or lose it on container exit:

-v cyrock-db-data:/data

A named volume is the simplest choice. A host directory works too and is easier to back up or inspect:

-v "$PWD/cyrock-data:/data"

The container runs as a non-root user, so a host directory must be writable by it. A named volume avoids the question entirely, which is why the examples use one.

/data/bootstrap-state.properties holds the seeded API key and project ID. It is why a restart keeps the same credentials - and why deleting it forces a re-seed.

Backup

Storage is a set of files under /data, so a backup is a copy of that directory. Take it with the container stopped, so no commit is in flight:

docker stop cyrock-db

docker run --rm \
  -v cyrock-db-data:/data:ro \
  -v "$PWD:/backup" \
  busybox tar czf /backup/cyrock-db-backup.tar.gz -C /data .

docker start cyrock-db

Restore into a fresh volume:

docker run --rm \
  -v cyrock-db-restored:/data \
  -v "$PWD:/backup" \
  busybox tar xzf /backup/cyrock-db-backup.tar.gz -C /data

Then run the container against cyrock-db-restored. Verify a restore at least once before you rely on it - an untested backup is a hypothesis.

Restoring somewhere else, or mounting the volume at a different path, is fine. The engine notices that its vector indices were built under the old path and rebuilds them on the first start, saying so in the log; nothing is lost, and the files left behind at the old path are not touched, in case the original is still running. Starts after that one load normally. Budget for that first start the way you would for an upgrade (see Upgrading for the cost), and keep the whole directory in the archive, indices included, so a restore to the same path has nothing to rebuild.

Health

Two unauthenticated endpoints, so orchestrators can reach them:

curl http://localhost:7282/actuator/health
{"groups":["liveness","readiness"],"status":"UP"}

The image also declares its own HEALTHCHECK, so docker ps reports health: starting and then healthy without you polling anything. First start allows 90 seconds before health is enforced, because seeding takes 30-60.

The platform server has the same endpoints on 7281.

Metrics

Prometheus format, no configuration needed:

curl http://localhost:7282/actuator/prometheus

Alongside JVM and HTTP metrics you get engine-level ones - query latency, index sizes, commit counts. A minimal scrape config:

scrape_configs:
  - job_name: cyrock-db
    metrics_path: /actuator/prometheus
    static_configs:
      - targets: ['localhost:7282', 'localhost:7281']

What is worth watching first: heap used against heap max (the metric that most often explains a slowdown in this single-JVM image), query latency percentiles, and storage size on disk.

For traces, set OTEL_EXPORTER_OTLP_ENDPOINT to a collector - see Configuration.

Logs

docker logs cyrock-db              # everything
docker logs -f cyrock-db           # follow
docker logs --tail 200 cyrock-db   # recent

The startup banner is at the top of the log, which is where to look for the API key and project ID if you have lost them:

# macOS / Linux
docker logs cyrock-db | head -40
# Windows
docker logs cyrock-db | Select-Object -First 40

Resource sizing

One JVM runs the whole engine here. A vector index lives in a file that the operating system maps into memory rather than on the Java heap, so it does not need heap room to be searched - but the pages it touches still count against the container’s memory limit, which is why vector count and dimension drive the figures below more than document count does.

Use Memory JAVA_OPTS

Sample data, exploring

4 GB

-Xmx3g

Tens of thousands of vectors

8 GB

-Xmx6g

Hundreds of thousands of vectors

16 GB

-Xmx12g

Leave headroom - -Xmx is the heap, and the JVM needs more than the heap. Setting -Xmx above what Docker will grant moves the failure rather than preventing it, so raise Docker’s own memory limit alongside it.

CPU: index building is the parallel part, and it sizes its own thread pool from the cores it can see. In a container with a CPU limit that limit is the bound, so there is nothing to do. Without one, on a large host, it will use as many threads as the host has physical cores - which is what you want while building an index and more than you want if the machine is shared. Cap it by adding -Djvector.physical_core_count=N to JAVA_OPTS. This pool is now sized from the detected core count rather than from half the visible processors, so an uncapped instance on a big host uses roughly twice the threads it used to, and correspondingly more memory bandwidth during the index rebuild described under Upgrading.

Disk: storage grows with your data plus index overhead. Vectors dominate - 384 floats per vector is about 1.5 KB before indexing.

Upgrading

Releases are tagged. Substitute the tag you are moving to for <new-version> below, then pull it and restart against the same volume:

docker stop cyrock-db && docker rm cyrock-db
docker pull cyrockai/db:<new-version>
docker run -d --name cyrock-db \
  -p 7280:7280 -p 7281:7281 -p 7282:7282 -p 7285:7285 -p 7290:7290 \
  -v cyrock-db-data:/data -e JAVA_OPTS=-Xmx6g \
  cyrockai/db:<new-version>

Take a backup first. Storage usually carries over between releases, but a release may change the on-disk format when backward compatibility is not worth the cost. When that happens the engine detects it at startup and refuses to serve the old storage, logging a banner and reporting storage health DOWN with a message that tells you to start with an empty storage directory (back up and remove the volume, then restart on the new version). This is pre-release software and a rollback is only as good as your last copy.

Separately from that, and much less drastic, a release may change the format of the vector indices alone. This is not the refusal above: the engine starts and serves your data as usual. Nothing is lost, because an index is derived from the vectors in the store and can always be rebuilt from them. What you see is a slower first start while each index is rebuilt once, and it is written back immediately, so the second start is quick again.

Budget for it. Rebuilding 50,000 vectors of 768 dimensions measured about three and a half minutes, against a third of a second for the same index once written - so plan on roughly four seconds per thousand vectors, scaled by your dimension, and on needing more memory during the rebuild than the finished index occupies. Two things follow: give the container headroom beyond what it normally needs, and do not kill it because the first start takes longer than usual. An instance killed mid-rebuild has lost nothing, but it will start the rebuild again from the beginning.

Pin an exact version rather than tracking latest, so an upgrade is something you choose.

Stopping

Give it a longer grace period than Docker’s default:

docker stop -t 90 cyrock-db

stop sends SIGTERM, which reaches the JVM directly - the entrypoint runs it as PID 1. The engine then drains in-flight requests, flushes the vector indices and closes storage, which takes around 40 seconds. Docker’s default grace period is 10, so a plain docker stop sends SIGKILL partway through and the container exits 137.

No committed data is at risk either way, in any durability mode: every statement commits atomically, and the engine writes through to the operating system rather than buffering in the JVM, so a committed write survives the process being killed. (A power cut is the different question, and the one the durability modes are about - see Configuration.) What a killed shutdown does cost you is the vector indices. Closing a store writes each index’s graph to disk so the next start can load it; a SIGKILL partway through leaves nothing to load, and the next start rebuilds every index in memory from the stored vectors instead. That is correct but slow, and on an instance holding several large collections the rebuilds are the biggest memory demand the engine makes - enough to exhaust the heap and leave the container restarting into the same rebuild each time. Passing -t 90 lets the shutdown finish and exit 143, which is what keeps the next start cheap. Raise it further if your indices are large enough that the log still shows a 137 exit.

Confirm a clean shutdown in the log:

# macOS / Linux
docker logs cyrock-db 2>&1 | grep "Storage system stopped"
# Windows
docker logs cyrock-db 2>&1 | Select-String "Storage system stopped"

One thing to avoid: stopping while the container is still starting. The health status turns healthy once the engine and the MCP endpoint are up, so wait for that before stopping - a SIGTERM that lands mid-startup produces a Shutdown in progress stack trace in the log. It is harmless, and no data is at risk, but it looks alarming.