Skip to content

Quick-start

This guide builds Detent, starts a durable authority and a managed agent on your own machine, publishes a knob and reads it from the shell. The authority listens only on 127.0.0.1. DON’T PANIC, it takes just a few minutes.

Run the commands in order, in one terminal. The next pages continue in the same shell, with the same helpers and variables.


Terminal window
git clone https://github.com/Kronuz/Detent.git
cd Detent
cmake -B build -DDETENT_BUILD_TESTS=OFF -DDETENT_BUILD_EXAMPLES=OFF -DDETENT_BUILD_BENCHMARKS=OFF
cmake --build build -j 4
export PATH="$PWD/build/src:$PATH"

This builds the three programs the guide uses, in build/src: detent-authority, the authority; detent-agent, the managed agent; and detent, the shell reader. The Installation section covers compiler requirements, build options and platform notes.


The agent verifies the authority’s TLS certificate, so the authority needs one. The repository’s test fixture makes a throwaway CA and localhost leaf certificates with OpenSSL, valid for one day. Work in build/quickstart:

Terminal window
mkdir -p build/quickstart && cd build/quickstart
OPENSSL_CONF=../../tests/detent_authority/tls_ambient.cnf \
cmake -DOUTPUT="$PWD/certs" -DOPENSSL=openssl \
-P ../../tests/detent_authority/tls_certificates.cmake

Then pick an authority identity and two tokens: one for the publisher, one for the agent. Identities are 32 hexadecimal characters; tokens are at least 32 characters:

Terminal window
CLUSTER=$(openssl rand -hex 16)
IDENTITY="\"cluster\":\"$CLUSTER\",\"group\":\"$(openssl rand -hex 16)\",\"epoch\":\"$(openssl rand -hex 16)\""
WRITER_TOKEN=$(openssl rand -hex 24)
READER_TOKEN=$(openssl rand -hex 24)

Terminal window
cat > authority.json <<EOF
{
$IDENTITY,
"directory": "authority-data",
"publisher_tls": {
"certificate": "certs/one.pem", "key": "certs/one.key", "ca": "certs/ca.pem"
},
"credentials": [
{ "token": "$WRITER_TOKEN", "producer": "writer",
"namespaces": ["search", "checkout", "payments"] },
{ "token": "$READER_TOKEN", "producer": "agent", "principal": "agent-reader",
"publish": false, "namespaces": ["search", "checkout", "payments"] }
]
}
EOF
chmod 600 authority.json
detent-authority --authority authority.json --runtime-dir run --daemonize

With no voters, the authority is a single voter. It listens on 127.0.0.1 port 8317 and keeps its durable store in authority-data. The writer credential may publish to the three namespaces; the agent credential may only read them, as principal agent-reader.


Every request carries the writer’s token and the authority identity. Define a helper and open a publishing session:

Terminal window
api() {
curl --fail-with-body -sS -w '\n' --cacert certs/ca.pem \
-H "Authorization: Bearer $WRITER_TOKEN" -H 'Content-Type: application/json' \
--data "{$IDENTITY,$2}" "https://localhost:8317/v2/$1"
}
api open '"expected_generation":0,"nonce":"00000000000000000000000000000001"'

--daemonize returns once the authority has a leader, so the open succeeds on its first attempt. The reply looks like this, with the identity elided:

{"authority":{...},"status":"applied","revision":0,"namespace_revision":0,"generation":1,"sequence":0}

The reply’s "generation":1 is this producer’s session. Each transaction in it carries the next sequence number. A second helper publishes one knob definition per transaction, in the namespace before the colon:

Terminal window
sequence=0
publish() {
sequence=$((sequence + 1))
api transactions "\"generation\":1,\"sequence\":$sequence,\"namespace\":\"${1%%:*}\",\"operations\":[{\"key\":\"$1\",\"value\":$2}]"
}

Terminal window
cat > managed.json <<EOF
{
"cluster": "$CLUSTER",
"namespaces": ["search", "checkout", "payments"],
"token": "$READER_TOKEN",
"ca": "certs/ca.pem"
}
EOF
chmod 600 managed.json
detent-agent --managed managed.json --generation-dir agent-state --runtime-dir run \
--initialize-managed --daemonize
export DETENT_GENERATION_DIR="$PWD/agent-state"

The agent connects to localhost:8317 over TLS, checks the certificate against certs/ca.pem, and publishes immutable generations in agent-state. --initialize-managed creates that store on the first start; later starts leave it out. detent get reads the newest generation from DETENT_GENERATION_DIR and never opens managed.json.


Publish an integer knob and read it:

Terminal window
publish search:max_results '{"default":25}'
sleep 1
detent get search:max_results
# 25

Each transaction replies with its outcome and the authority’s new revision:

{"authority":{...},"status":"applied","revision":1,"namespace_revision":1,"generation":1,"sequence":1}

Now change the value without restarting anything:

Terminal window
publish search:max_results '{"default":100}'
sleep 1
detent get search:max_results
# 100

sleep 1 gives the agent time to deliver the update. Your applications see it the same way: the next read after the update lands returns the new value, with no restart and no redeploy.


The next pages walk through each idea in turn, in the same shell and directory:

  1. Basic Concepts: knobs, snapshots, versions and defaults.
  2. Settings and Flags: numeric settings and on/off switches.
  3. Gradual Rollouts: percentage ramps with stable buckets.
  4. Group Overrides: forcing or ramping specific groups.
  5. Next Steps: stopping the daemons, and where to go from here.