Configuration Reference
Configuration of alexandria-server and alexandria-client in the section layout (YAML) and the flat specification layout (JSON), plus lifecycle parameters and command-line flags.
Configuration Reference
Both binaries read one configuration document, in YAML (.yaml, .yml) or JSON (.json), in either of two equivalent layouts (DP-11):
- the section layout used in
config/(common_config,auth_config,did_config,observability, plusvhub_configorclient_config), and - the flat layout of the specification (Appendix B for the server, Appendix A.3 for the client) used in
deploy/.
The document is validated at startup: the server against deploy/server.schema.json, the client against spec/schemas/config.schema.json. Paths written as file:… are resolved relative to the directory of the configuration file.
1. alexandria-server
common_config:
hosts:
http:
protocol: "https"
url: "127.0.0.1"
port: "8443"
internal_port: "8443"
db:
db_type: "SQLite"
database: "file:../var/hub/hub.db"
blobs: "file:../var/hub/blobs"
connection:
tls:
cert: "file:../var/tls/hub.crt"
key: "file:../var/tls/hub.key"
auth_config:
enabled: true
issuer: "http://127.0.0.1:9400"
audience: "alexandria-vhub"
algorithms: ["RS256", "ES256", "EdDSA"]
roles_claim: "roles"
admin_role: "vhub-admin"
jwks_refresh: "PT10M"
did_config:
type: "key"
signing_key: "file:../var/hub/hub.key"
observability:
log_level: "info"
log_format: "auto"
# otlp_endpoint: "http://127.0.0.1:4318"
vhub_config:
rdf_context: "self-hosted"
compiler: "dsl"
clock_skew: "PT5S"
vocab:
max_size: 10485760
proxy_timeout: "PT30S"
allow_insecure_localhost: trueFields (flat names)
| Field | Required | Description |
|---|---|---|
listen | Yes | Address the hub binds. |
base | Yes | Public base URL. It is the prefix of every IRI the hub emits ({base}/v1/namespaces/…, {base}/pub/…). |
did | No | Hub DID. Defaults to the did:key derived from the signing key; a did:web is also supported (DP-5). |
signing.key | Yes | Ed25519 key in PKCS#8 PEM. Generated on first start if absent (PoC). |
signing.verification_method | No | Verification method of the proofs; defaults to the did:key method of the key. |
rdf.context | No | self-hosted serves the Appendix A.5 context at /pub/_vhub/v1/context.jsonld and uses that URL as @context; referenced uses https://w3id.org/alexandria-vhub/v1. |
auth.issuers[] | Yes | Accepted token issuers, each with iss and discovery_url. |
auth.audience | Yes | Audience every access token must contain. |
auth.algorithms | No | Allowed asymmetric signature algorithms. |
auth.admin_claim | No | Claim and value that mark the hub admin (default roles containing vhub-admin). |
auth.jwks_cache | No | How long a JWKS is cached (ISO 8601 duration). |
vocab.max_size | No | Maximum size in bytes of a vocabulary revision. |
vocab.proxy_timeout | No | Timeout for fetching a proxy vocabulary upstream. |
vocab.proxy_allow | No | Host allow-list for proxy upstreams (SSRF protection). |
vocab.allow_insecure_localhost | No | Accept http://localhost upstreams. Laboratory only. |
did_resolver.allow_insecure_localhost | No | Accept http:// for a localhost did:web. Laboratory only. |
storage.database, storage.blobs | Yes | SQLite database and content-addressed blob directory. |
tls.cert, tls.key | No | Serve HTTPS. A self-signed laboratory certificate is generated when the files are absent. Omit both to serve plain HTTP behind a TLS proxy. |
compiler | No | Draft compiler: poc (JSON drafts, default) or dsl (alexandria.profiles/v1 YAML). |
vendor_dir | No | Local copies of vendored profiles for the dsl compiler. |
clock_skew | No | Tolerance applied to token and credential times. |
clock_file | No | Read the current instant from a file (PoC and tests). |
lifecycle | No | Hub-wide defaults of the lifecycle parameters below. |
observability.* | No | log_level, log_format, otlp_endpoint, otlp_insecure, service_name, environment. |
2. alexandria-client
common_config:
connection:
tls:
ca: "file:../var/tls/hub.crt"
did_config:
type: "key"
hub_did: "did:key:z6Mk…"
did_ttl: "PT6H"
observability:
log_level: "info"
log_format: "auto"
audit_window: 100
events_sink: "file:var/client/events.jsonl"
client_config:
trust:
hub: "https://127.0.0.1:8443"
namespace: "demo"
context: "https://127.0.0.1:8443/pub/_vhub/v1/context.jsonld"
upstreams:
dsp: "http://127.0.0.1:8282/dsp"
listeners:
dsp-ingress:
bind: "127.0.0.1:9080"
dsp-egress:
bind: "127.0.0.1:9081"
admin:
bind: "127.0.0.1:9090"
rules:
seed: "file:deploy/rules.seed.json"
default_action: "forward"
unknown_agreement: "forward"
retention:
gc_interval: "P1D"Fields (flat names)
| Field | Required | Default | Description |
|---|---|---|---|
trust.hub | Yes | — | Base URL of the hub. |
trust.namespace | Yes | — | Namespace slug the client follows. |
trust.hub_did | Yes | — | DID whose assertionMethod keys are trusted to sign listings and manifests. |
trust.context | No | https://w3id.org/alexandria-vhub/v1 | Expected JSON-LD context of the credentials. Set it to the hub's self-hosted URL when the hub uses rdf.context: self-hosted. |
trust.did_ttl | No | PT6H | How long the hub DID document is cached. |
mode | No | proxy | proxy: the client forwards the traffic itself. validator: an external proxy (for example Envoy ext_authz) forwards and the traffic listeners only answer its checks. See examples/. |
upstreams.dsp | In proxy mode | — | DSP endpoint of the connector. Not used in validator mode. |
upstreams.management | No | — | Management API of the connector; required by rules on mgmt-ingress. |
listeners.admin.bind | Yes | — | Admin API listener. |
listeners.dsp-ingress.bind | No | — | Reverse proxy for inbound DSP traffic (check endpoint in validator mode). |
listeners.dsp-egress.bind | No | — | Forward proxy for outbound DSP traffic (check endpoint in validator mode). |
listeners.mgmt-ingress.bind | No | — | Reverse proxy for the connector management API (check endpoint in validator mode). |
rules.seed | No | — | Initial rule set, loaded only when the persistent rule store is empty. |
default_action | No | forward | What to do with a request no rule matches: forward or reject. |
unknown_agreement | No | forward | What to do with a transfer whose agreement was never captured. |
audit.window | No | 100 | Number of catalog responses kept for the passive audit. |
retention.gc_interval | No | P1D | Interval of the package garbage collector. |
events.sink | Yes | — | Where events are written, for example file:var/client/events.jsonl. |
The client refuses to start on an invalid document (CONFIG_SCHEMA), an unreadable rule seed (CONFIG_RULES_SEED_UNREADABLE) or an inconsistent rule set (RULES_*), exiting with a non-zero status and the code (REQ-CLI-001).
3. Lifecycle Parameters
Lifecycle parameters travel inside every signed package manifest, so all clients of a version apply the same values. The hub defaults are:
| Parameter | Default | Meaning |
|---|---|---|
freshness.ttl | PT24H | Validity of a listing. The hub re-issues it at least every ttl / 2. |
freshness.max_staleness | P7D | How long a client may keep working on an expired listing before failing closed. |
propagation_window | P2D | Delay between publication and new_content_from. |
grace_window | P30D | Default coexistence of a breaking version with its predecessor. |
min_grace_window | P7D | Minimum grace window a steward may request. |
sync_interval | PT6H | Maximum interval between client synchronizations. |
clock_skew | PT5S | Tolerated clock difference between hub and client. |
lease_margin | PT10S | Margin the client adds around in-force boundaries. |
max_concurrent_versions | 4 | Maximum number of versions in force at once. |
degraded | {} | Per-gate behaviour (continue or reject) while the client is Degraded. |
Inconsistent values are rejected with LIFECYCLE_* codes when a draft is validated.
4. Command-Line Flags
| Binary | Flag | Description |
|---|---|---|
| both | -config <path> | Configuration file (default config/server.yaml or config/client.yaml). |
| both | -clock-file <path> | Read the current instant from a file (PoC and tests). |
| both | -log-level, -log-format | Override observability.log_level and log_format. |
| client | -state-dir <path> | Directory of the persistent state (database and packages). |
| client | -hub-ca <path> | PEM root certificate of a laboratory hub. |
| client | -did.allow_insecure_localhost | Allow http:// for a localhost did:web. |
Quickstart
Run the automated scenario in one command, or start the Alexandria lab yourself and walk through the GreenCity Mobility story.
Tutorials
Five hands-on guides following one cohesive story — the GreenCity Mobility Dataspace (mobility) — across CLI, Authoring Studio, and live Console walkthroughs.