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.

Availability today

The Community Edition — edssa-server-ce, the self-hosted verifier binary — is not publicly distributed yet. Two consequences, both of which you will hit as concrete errors rather than as a notice:

• The repository is private. github.com/edssa-io/edssa is not public, so git clone fails with a permission error unless your account has been granted access. Access is arranged per customer, because the code is BSL 1.1 and part of it is under a patent filing hold — write to support@edssa.io.
• The CE image is not on Docker Hub. edssa/server-ce:1.0.0 is referenced throughout the samples but has not been pushed, so docker pull fails with pull access denied. Publishing is operator-side, after the public migration of v1.0.0-ce. Every command in these docs runs against an image you build locally from the source tree, so none of them needs the registry.

Autopliance, the hosted product, is live and needs none of the above — no source access, no image, no self-hosting. If you want verified traffic and compliance reports today, that is the path that is open: see Autopliance — getting started.

On this page specifically: step 1 clones the tree (so it is the step that needs the granted access above) and step 2 builds the image locally. Everything after those two works offline against that image.

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.
• SDKs: Rust, Go, Python and Node bindings exist in-tree. None is published to a public registry yet, so none can be installed with cargo add / go get / pip install — see the availability note at the top of the 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.