Quickstart

AlphaVerification Required

Concordia Cache quickstart.

Run the local Concordia Cache binary, write and read keys, check count, TTL, stale-version behavior, placement diagnostics, and node-local binary persistence limits.

Current availability

Private Beta. Public beta is scheduled for December 7, 2026.

Result

You will have a local Concordia Cache service that accepts a key/value write, returns the value by key, keeps count at one after update and stale-write checks, expires a short TTL key, reports placement diagnostics with routing_enabled:false, and reloads the accepted value after restarting with the same node-local persistence file.

Maturity Status

Cache HTTP Workflow

Alpha

The workflow uses the local concordia-cache-bin HTTP surface and fixed local bearer-token admission.

Review Boundary

Verification Required

This tutorial proves local behavior only. Production identity, distributed routing, shared storage, replication, availability, support, security, performance, scale, and GA claims still need evidence review.

Prerequisites

Required tools

Required

cargo --version for the Rust toolchain
curl --version for HTTP requests
A local Service.Concordia source checkout

Product setup

Required

Service.Concordia source at /path/to/Service.Concordia or an equivalent local checkout.
concordia-cache-bin run through Cargo from the workspace root.
--bind set to a free loopback address, such as 127.0.0.1:9101.
--persistence-path set to a tutorial-scoped binary snapshot file.

Admission policy

Required

GET /health is open.
/v1/count, /v1/{key}, and /v1/{key}/placement require Authorization: Bearer local-cache-token.
Missing or invalid bearer tokens return stable admission error codes.

Optional helpers

Optional

jq can make JSON inspection easier, but the copy/paste path uses only shell and curl.
The broader Support/Validate-Local.sh script uses a separate Cache smoke port and is not required for this tutorial.

See local prerequisites for the shared tool baseline.

Start The Service

Use one terminal for the Cache service and a second terminal for the workflow commands. The persistence file is tutorial-scoped and can be removed during cleanup.

Run Concordia Cache locally

Service terminal

cd /path/to/Service.Concordia
export CONCORDIA_CACHE_BIND=127.0.0.1:9101
export CONCORDIA_CACHE_PERSISTENCE="${TMPDIR:-/tmp}/concordia-cache-docs-025.bin"
rm -f "$CONCORDIA_CACHE_PERSISTENCE"
cargo run -p concordia-cache-bin -- \
  --bind "$CONCORDIA_CACHE_BIND" \
  --persistence-path "$CONCORDIA_CACHE_PERSISTENCE"

Expected output

concordia-cache listening on http://127.0.0.1:9101

Keep this terminal open while you run the workflow commands.

Complete The Workflow

Configure tutorial values

Copy/paste

Run these values in the workflow terminal while the service terminal stays open.

export CONCORDIA_CACHE_ENDPOINT=http://127.0.0.1:9101
export CONCORDIA_CACHE_TOKEN=local-cache-token
export CONCORDIA_CACHE_KEY=customer:42
export CONCORDIA_CACHE_TTL_KEY=ttl-example

Expected output

The workflow terminal now points at the local Cache service, protected routes use the local bearer token, and customer:42 is the tutorial key.

Check open health

Copy/paste

Confirm the product binary is listening before sending protected Cache requests.

curl -s -i "$CONCORDIA_CACHE_ENDPOINT/health"

Expected output

HTTP/1.1 200 OK

{"status":"ok","product":"concordia-cache"}

Check protected-route admission

Copy/paste

Call a protected route without authorization so the local policy boundary is visible before writes.

curl -s -i "$CONCORDIA_CACHE_ENDPOINT/v1/count"

Expected output

HTTP/1.1 401 Unauthorized

{"error":"missing_authorization"}

Verify the cache starts empty

Copy/paste

Read the entry count with the local bearer token before writing tutorial state.

curl -s -i "$CONCORDIA_CACHE_ENDPOINT/v1/count" \
  -H "authorization: Bearer $CONCORDIA_CACHE_TOKEN"

Expected output

HTTP/1.1 200 OK

{"count":0}

Write a cache key

Copy/paste

Put one value with an explicit CRDT version. The first accepted write returns 201 Created and outcome:inserted.

curl -s -i -X PUT "$CONCORDIA_CACHE_ENDPOINT/v1/$CONCORDIA_CACHE_KEY" \
  -H "authorization: Bearer $CONCORDIA_CACHE_TOKEN" \
  -H "content-type: application/json" \
  --data '{"value":"cached value","crdt_version":10}'

Expected output

HTTP/1.1 201 Created

{"key":"customer:42","outcome":"inserted","crdt_version":10,"expires_at_micros":null}

Read the cache key

Copy/paste

Fetch the same key and verify that the value and version match the accepted write.

curl -s -i "$CONCORDIA_CACHE_ENDPOINT/v1/$CONCORDIA_CACHE_KEY" \
  -H "authorization: Bearer $CONCORDIA_CACHE_TOKEN"

Expected output

HTTP/1.1 200 OK

{"key":"customer:42","value":"cached value","crdt_version":10,"expires_at_micros":null}

Update with a newer version

Copy/paste

Write the same key with a higher CRDT version. The cache keeps one entry and reports an update.

curl -s -i -X PUT "$CONCORDIA_CACHE_ENDPOINT/v1/$CONCORDIA_CACHE_KEY" \
  -H "authorization: Bearer $CONCORDIA_CACHE_TOKEN" \
  -H "content-type: application/json" \
  --data '{"value":"updated value","crdt_version":11}'

Expected output

HTTP/1.1 200 OK

{"key":"customer:42","outcome":"updated","crdt_version":11,"expires_at_micros":null}

Reject a stale version

Copy/paste

Send an older CRDT version to prove the local version check preserves the newer value.

curl -s -i -X PUT "$CONCORDIA_CACHE_ENDPOINT/v1/$CONCORDIA_CACHE_KEY" \
  -H "authorization: Bearer $CONCORDIA_CACHE_TOKEN" \
  -H "content-type: application/json" \
  --data '{"value":"stale value","crdt_version":10}'

Expected output

HTTP/1.1 409 Conflict

{"key":"customer:42","outcome":"ignored_stale","crdt_version":11,"expires_at_micros":null}

Confirm count stays at one

Copy/paste

The update and stale-write check do not create extra cache entries.

curl -s -i "$CONCORDIA_CACHE_ENDPOINT/v1/count" \
  -H "authorization: Bearer $CONCORDIA_CACHE_TOKEN"

Expected output

HTTP/1.1 200 OK

{"count":1}

Write a short TTL key

Copy/paste

Create a second key with ttl_seconds:1 and wait for it to expire.

curl -s -i -X PUT "$CONCORDIA_CACHE_ENDPOINT/v1/$CONCORDIA_CACHE_TTL_KEY" \
  -H "authorization: Bearer $CONCORDIA_CACHE_TOKEN" \
  -H "content-type: application/json" \
  --data '{"value":"short lived","crdt_version":1,"ttl_seconds":1}'

sleep 2

curl -s -i "$CONCORDIA_CACHE_ENDPOINT/v1/$CONCORDIA_CACHE_TTL_KEY" \
  -H "authorization: Bearer $CONCORDIA_CACHE_TOKEN"

Expected output

The write returns 201 Created with an expires_at_micros value.

After the sleep, the read returns:

HTTP/1.1 404 Not Found

{"error":"not_found","key":"ttl-example"}

Inspect placement diagnostics

Copy/paste

Read the key placement diagnostic. The response shows the hash inputs and replica node IDs, while keeping runtime routing disabled.

curl -s -i "$CONCORDIA_CACHE_ENDPOINT/v1/$CONCORDIA_CACHE_KEY/placement" \
  -H "authorization: Bearer $CONCORDIA_CACHE_TOKEN"

Expected output

HTTP/1.1 200 OK

{
  "key":"customer:42",
  "tenant_id":"local",
  "dataset_id":"cache",
  "placement_hash_version":1,
  "partition_id":34823,
  "partition_count":65536,
  "replica_count":3,
  "replica_node_ids":[2,3,1],
  "routing_enabled":false
}

Verify binary persistence after restart

Copy/paste

Restart the Cache binary with the same persistence file, then re-read the tutorial key from the workflow terminal.

# In the service terminal, press Ctrl-C.
# Restart from /path/to/Service.Concordia:
cargo run -p concordia-cache-bin -- \
  --bind 127.0.0.1:9101 \
  --persistence-path "${TMPDIR:-/tmp}/concordia-cache-docs-025.bin"

# In the workflow terminal:
curl -s -i "$CONCORDIA_CACHE_ENDPOINT/v1/$CONCORDIA_CACHE_KEY" \
  -H "authorization: Bearer $CONCORDIA_CACHE_TOKEN"

Expected output

HTTP/1.1 200 OK

{"key":"customer:42","value":"updated value","crdt_version":11,"expires_at_micros":null}

Verify Success

The quickstart is successful when GET /health returns product:"concordia-cache", protected routes reject missing auth, the first write returns outcome:"inserted", the newer write returns outcome:"updated", the stale write returns outcome:"ignored_stale", count returns 1, the TTL key returns not_found after expiration, placement shows routing_enabled:false, and the post-restart read returns value:"updated value".

Clean Up

Stop the service

Copy/paste

Stop Concordia Cache with Ctrl-C in the service terminal before removing tutorial state.

# Press Ctrl-C in the terminal running cargo run.

Expected output

The local concordia-cache process exits.

Remove tutorial state

Copy/paste

Remove only the tutorial persistence file used by this quickstart.

rm -f "${TMPDIR:-/tmp}/concordia-cache-docs-025.bin"

Expected output

The tutorial binary snapshot file is gone. Do not remove a shared Cache persistence file.

Troubleshooting

Common first-run failures
Symptom	How to recognize it	Likely cause	Fix
Service does not start	`cargo run -p concordia-cache-bin` reports that the address is already in use or cannot bind.	Another local process is using `127.0.0.1:9101`.	Choose a different loopback port with `--bind` and update `CONCORDIA_CACHE_ENDPOINT` to match.
Health check cannot connect	`curl` reports connection refused or times out against `127.0.0.1:9101`.	The service terminal stopped, Cargo is still compiling, or the service is bound to a different address.	Wait for Cargo to finish, confirm the service terminal is still open, and re-check the endpoint value.
Protected route returns `missing_authorization`	The response status is `401 Unauthorized` and the JSON error is `missing_authorization`.	The authorization header was omitted.	Send `authorization: Bearer local-cache-token` on `/v1/count`, `/v1/{key}`, and `/v1/{key}/placement`.
Protected route returns `invalid_bearer_token`	The response status is `401 Unauthorized` and the JSON error is `invalid_bearer_token`.	The bearer token is present but does not match the local development token.	Set `CONCORDIA_CACHE_TOKEN=local-cache-token` and retry the request.
Stale write does not return `ignored_stale`	The stale write returns `inserted` or `updated` instead of `409 Conflict`.	The newer version was not written first, or the stale request used a version greater than the stored version.	Re-run the newer version write with `crdt_version:11`, then retry the stale write with `crdt_version:10`.
TTL key still reads successfully	The read for `ttl-example` returns `200 OK` after the sleep.	The sleep was interrupted, the request hit a different key, or the TTL write omitted `ttl_seconds`.	Re-run the documented TTL command and confirm the read uses `CONCORDIA_CACHE_TTL_KEY=ttl-example`.
Restart does not reload the key	The post-restart read returns `404 Not Found` for `customer:42`.	The service was restarted without the same `--persistence-path`, or the persistence file was removed before restart.	Restart with the exact tutorial persistence path and retry before running cleanup.

Evidence

Source-backed quickstart checks
Workflow step	Evidence	Status
Service startup and CLI	Service.Concordia/bins/concordia-cache/src/main.rs and docs/LOCAL_RUNBOOK.md	Source-backed; local run still needs reviewer acceptance
Admission and HTTP routes	Service.Concordia/bins/concordia-cache/src/http.rs route handlers and tests	Source-backed
Put, get, count, TTL, and version behavior	Service.Concordia/crates/concordia-cache/src/lib.rs and bins/concordia-cache/src/http.rs tests	Source-backed
Placement diagnostics	Service.Concordia/bins/concordia-cache/src/http.rs and concordia-cluster placement tests	Source-backed; routing remains disabled
Binary persistence reload	Service.Concordia/crates/concordia-cache/src/lib.rs binary persistence tests and docs/LOCAL_RUNBOOK.md	Source-backed; node-local only

Limits

Alpha Local Path

This quickstart exercises the local concordia-cache-bin HTTP service and does not broaden Concordia maturity.

Bearer Token Only

Protected routes require the fixed local token local-cache-token; production JWT parsing, signature verification, and key-source wiring are outside this workflow.

Placement Is Diagnostic

Placement responses show hash and replica diagnostics with routing_enabled:false; they do not prove owner forwarding or cross-node routing.

Node-Local Persistence

The optional binary snapshot can reload local accepted entries after restart; it is not a shared storage or replication guarantee.

Next Steps

Available now
Review Concordia evidence
Use the evidence index before strengthening Cache, Gateway, TSDB, Storage, or workflow claims.
Available now
Read tutorial prerequisites
Check the shared local tool baseline and product-specific setup expectations for first-success tutorials.
Available now
Try TSDB and Gateway alpha tutorial
The next tutorial covers local Time Series append/query and Gateway readiness boundaries.
Available: DOCS-061
Use local curl examples
Review tested curl examples for Cache, TSDB, Gateway alpha readiness, and active compatibility diagnostics.
Available now
Read runtime surface reference
Separate Cache HTTP, Gateway alpha, Storage validation, active service, and protocol fixture surfaces.
Available: DOCS-053
Use validation runbooks
Check Cache smoke, restart, placement, and local admission failures without broadening the validation claim.
Available: DOCS-041
Map runtime boundaries
Compare local, alpha, validation, fixture, future, and verification-required Concordia runtime surfaces.