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 |
|
Tens of thousands of vectors |
8 GB |
|
Hundreds of thousands of vectors |
16 GB |
|
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.