Quickstart

Goal: a verified token reaches a real backend within 5 minutes from a fresh machine. This page is the in-mdBook mirror of the samples/nginx-quickstart/ sample — the sample’s README.md is the source of truth for the exact commands.

Prerequisites

• Docker + docker compose v2.
• A Rust toolchain (the repo pins 1.86) to build the image and run edssa-client. Any SDK works in place of the CLI.

The published image does not exist yet. edssa/server-ce:1.0.0 is referenced throughout the samples but has not been pushed to Docker Hub — docker pull fails with pull access denied. Publishing is operator-side, after the public migration of v1.0.0-ce. Step 2 below builds the image locally, and every command on this page is run against that locally-built image. Nothing here needs the registry.

Steps

1. Clone the repo. Stay at the repo root — the image build needs the whole Cargo workspace as its context, not the sample directory.

   git clone https://github.com/edssa-io/edssa.git
   cd edssa
   

2. Build the CE image. The build context is code/ (the binary path-deps edssa-core + edssa-audit):

   docker build -f samples/nginx-quickstart/Dockerfile.local \
     -t edssa-server-ce:dev code/
   

   Builds natively on both amd64 and arm64 (Apple Silicon) — the Dockerfile picks target-cpu from BuildKit’s TARGETARCH.

   Then point the sample at it — in samples/nginx-quickstart/docker-compose.yml, replace image: edssa/server-ce:1.0.0 with image: edssa-server-ce:dev.

3. Generate a seed. The committed *.seed.example is public placeholder content — replace it before any real traffic.

   cd samples/nginx-quickstart
   LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom \
     | head -c 1024 > secrets/fleet-c1b2-demo.seed
   chmod 0400 secrets/fleet-c1b2-demo.seed
   

4. Start the stack.

   docker compose up -d
   

5. Verify rejection without a token.

   curl -i http://localhost:8080/
   # → HTTP/1.1 401 Unauthorized
   

6. Send a verified request. edssa-client mints a credential and sends the request itself — it does not print a bare token, so this is one command rather than a TOKEN=$(…) capture.

   The derivation flags must match the fleet’s manifest entry. The sample’s ce.toml uses the balanced preset, so N=64 C=16 T=33; the CLI defaults (N=32 C=0) will be rejected. Run from code/, the Cargo workspace root:

   cd ../../code
   cargo run --quiet -p edssa-client --bin edssa-client -- \
     --target http://localhost:8080/ \
     --fleet c1b2-demo \
     --seed ../samples/nginx-quickstart/secrets/fleet-c1b2-demo.seed \
     --width-n 64 --chaff-c 16 --threshold-t 33
   

   The summary reports accepts 1, and the server logs edssa accept fleet=c1b2-demo.

   --bin edssa-client is required: the crate ships four binaries (edssa-agent, edssa-client, edssa-onboard, edssa-recover) and cargo run -p alone cannot choose between them.

7. Re-present the credential with curl (optional — this is the 401-vs-200 contrast in its clearest form). --emit-tokens appends the exact accepted header to a file, one <status> <header> line per request:

   cargo run --quiet -p edssa-client --bin edssa-client -- \
     --target http://localhost:8080/ \
     --fleet c1b2-demo \
     --seed ../samples/nginx-quickstart/secrets/fleet-c1b2-demo.seed \
     --width-n 64 --chaff-c 16 --threshold-t 33 \
     --emit-tokens /tmp/edssa-tokens.txt
   
   TOKEN=$(awk '{print $2}' /tmp/edssa-tokens.txt | tail -1)
   curl -i -H "X-EdSSA-Token: $TOKEN" http://localhost:8080/
   # → HTTP/1.1 200 OK
   # → Hello from nginx — auth succeeded.
   

Beyond the quickstart

• Kubernetes: the samples/k8s-helm/ chart deploys the same shape as a sidecar.
• Go SDK: see github.com/edssa-io/edssa-go.
• Python SDK: see github.com/edssa-io/edssa-py.
• Rust SDK: cargo add edssa-core from crates.io (see SDK reference).

Time-to-first-token measurement

The Phase-8 exit criterion is “≤ 5 min on a clean macOS / Linux machine”. The measured baseline (mac mini M2, fresh git clone, warm Docker cache) is 3 m 12 s, dominated by:

A cold cargo build adds ~1 minute on first run; subsequent runs of the smoke flow are sub-30s.