Quick Start

This guide takes you from git clone to a signed passport that resolves from its digital link and verifies without Odal. You run seven commands and two API calls.

Most of the time goes into the first build: about 2 minutes for the odal CLI and 15 to 20 minutes for the node and resolver images on a 6-core machine. Later starts take seconds.

1. Build the CLI

You use odal for setup and operations. The engine builds against the core’s published crates on crates.io, so you do not need to clone dpp-core.

git clone https://github.com/odal-node/dpp-engine
cd dpp-engine
cargo build -p dpp-cli --release
export PATH="$PWD/target/release:$PATH"

2. Configure

cp .env.example .env
openssl rand -base64 32    # use as KEY_STORE_PASSPHRASE
openssl rand -hex 16       # use as ADMIN_PASSWORD

In .env, set KEY_STORE_PASSPHRASE, then uncomment ADMIN_USERNAME and ADMIN_PASSWORD and give them values. The node refuses to start if a required secret is missing. The example database passwords are accepted on a local dev profile, and a prod profile refuses them.

3. Start the stack

odal up
odal status

odal up starts PostgreSQL, Redis, NATS, the node (port 8001) and the resolver (port 8003). When it finishes, odal status shows each service as OK:

SERVICE      URL                                    STATUS
vault        http://localhost:8001/vault/health     OK
identity     http://localhost:8001/identity/health  OK
resolver     http://localhost:8003/health           OK

4. Register your operator identity

odal does not read .env, so export the admin credentials first. EU registry registration needs the operator’s legal name, and product groups whose passport obligation is in force also need a default facility and a primary operator identifier before they publish. The values below are valid test values.

set -a; . ./.env; set +a
odal bootstrap --legal-name "Example Textiles GmbH" --country DE \
  --address "Musterstrasse 1, 10115 Berlin" --contact-email ops@example.com
odal facility add --name "Berlin plant" --value 4012345000009 --country DE --default
odal operator-id add --scheme vat --value DE123456789 --primary

bootstrap prints your first API key once and saves it for the CLI. Export it for the API calls below:

export ODAL_API_KEY=odal_sk_...

With a key configured, odal status also lists the trust adapters (rule checking, sealing, registry sync, back-up copy, credential issuers). On a laptop every one is a stand-in, reported as ghost: passports work end to end, and nothing the node signs is fit for compliance use. Under the production profile the node refuses to start this way. See Operating securely.

5. Create and publish a passport

Create a draft with the REST API. The product group data is validated against the textile schema before anything is stored.

curl -s -X POST http://localhost:8001/vault/api/v1/dpp \
  -H "Authorization: Bearer $ODAL_API_KEY" -H 'Content-Type: application/json' \
  -d '{
    "productName": "Organic cotton T-shirt",
    "productGroup": "textile",
    "manufacturer": { "name": "Example Textiles GmbH", "address": "Musterstrasse 1, 10115 Berlin" },
    "productGroupData": {
      "productGroup": "textile",
      "productIdentifier": { "scheme": "gs1", "gtin": "09506000134352" },
      "fibreComposition": [{ "fibre": "organic cotton", "pct": 100.0 }],
      "countryOfOrigin": "PT",
      "careInstructions": "Machine wash 30°C",
      "chemicalComplianceStandard": "OEKO-TEX Standard 100"
    }
  }'

The response is the draft: a UUID v7 id, "status":"draft" and the schema version it was validated against. Publish it:

export DPP_ID=<id from the response>
curl -s -X POST "http://localhost:8001/vault/api/v1/dpp/$DPP_ID/publish" \
  -H "Authorization: Bearer $ODAL_API_KEY"

The passport is now "status":"active". It carries a jwsSignature made with your Ed25519 key, and a qrCodeUrl of the form http://localhost:8003/01/09506000134352/21/<serial>: the digital link that goes on the product label. The passport has a GTIN, so its digital link is a GS1 Digital Link. A passport identified by an identification link or a DID gets http://localhost:8003/dpp/<id> instead.

6. Resolve it like a scanner

curl -si http://localhost:8003/01/09506000134352 | head -n 3
curl -s -H 'Accept: application/ld+json' "http://localhost:8003/dpp/$DPP_ID"
curl -s http://localhost:8001/identity/.well-known/did.json

The GS1 route answers 307 and redirects to /dpp/<id>. The resolver returns the public view as JSON-LD, as HTML (open the same URL in a browser), or as an Asset Administration Shell environment, depending on the Accept header. The DID document holds the public key anyone can use to verify the signature.

7. Verify the evidence dossier

An evidence dossier bundles the passport, its signatures, the issuer’s DID document and the hash-chained audit trail into one signed document that can be checked offline.

odal passport evidence "$DPP_ID"   # prints the stored dossier; its "id" is the last field
odal verify <dossier-id>

  [PASS] manifest_signature
  [PASS] content_integrity
  [PASS] full_view_signature
  [PASS] public_view_signature
  [PASS] audit_chain
  [N/A ] transfer_chain — no transfer chain on this passport
  ...
VERIFIED — every check passed.

odal down stops the stack. Your data and signing key stay in Docker volumes.

The Console

Running odal with no arguments opens the Console, an interactive menu that covers the same tasks. Every section is also a direct command, so the same actions can run in CI:

Console section	What it does	Command
Infrastructure	Start, stop, check status, update the node	`odal up` · `odal down` · `odal status` · `odal update`
Passports	Import, validate, publish, export	`odal passport import` · `validate` · `publish` · `export`
Operator	View and edit your operator identity	`odal operator show` · `set`
Registry identity	Facilities and operator identifiers stamped on new passports	`odal facility` · `odal operator-id`
Dossiers	Check an evidence dossier against the node	`odal verify`
API keys	Create, list and revoke keys for CI or integrations	`odal key create` · `list` · `revoke`
Environment	Switch or create profiles for more than one node (dev and prod)	`odal profile use` · `create` · `list`
Schema	Check for product-group schema updates	`odal schema check` · `list` · `show`
Setup / Reconfigure	Reconnect, re-onboard or mint a first key	`odal --reconfigure` · `odal bootstrap`

Next steps

Importing product data: spreadsheets in, draft passports out, with row-by-row findings.
A passport’s lifecycle: amend, supersede, suspend, retire and end of life.
API reference: every route the node serves. Its “Test request” button calls your node from the browser, so add this site’s origin to CORS_ALLOWED_ORIGINS first.
Self-Hosting: what changes for a real deployment.

Information on this site is not legal advice. Legal notice Privacy policy