Step-by-step tutorial to launch Alexandria, its supporting services, and verify endpoints.

Quickstart Guide

This tutorial guides you through launching Alexandria, verifying local TLS certificates, bootstrapping the Zitadel IAM and cryptographic wallet, and running the node.

The Fast Path: One-Command Startup

For day-to-day development, Alexandria provides task dev:auto. It automatically:

Checks and generates the root Certificate Authority (CA) in /.certs/.
Terminates any stale node processes holding internal port 1234.
Starts all Docker containers (postgres, caddy, zitadel, fafnir-wallet).
Executes scripts/zitadel-bootstrap.sh to provision OIDC clients and update .env.
Executes scripts/fafnir-bootstrap.sh to provision the signing key and default DID.
Verifies local CA trust against the Zitadel discovery document.
Starts the Alexandria Go process with hot-reload enabled via air.

# 1. On a fresh machine, trust the local CA once (requires sudo):
task tls:trust

# 2. Start the full stack with automatic orchestration:
task dev:auto

Step-by-Step Manual Setup

If you prefer to understand each moving piece or start services independently, follow these granular steps:

1. Trust the Local Certificate Authority

Alexandria generates an internal root CA in /.certs/ so local HTTPS and mTLS work transparently across browsers, curl, and Go trust stores without security warnings:

task tls:trust

On macOS, this enrolls the certificate into the System Keychain. On Linux, it installs it into /usr/local/share/ca-certificates/ and runs update-ca-certificates.

2. Start PostgreSQL Database

Bring up the relational database:

task db:up

PostgreSQL 17 starts on port 1500 (user: alexandria, password: alexandria, db: alexandria). To open a psql shell at any time: task db:psql.

3. Start Caddy Reverse Proxy

Launch the TLS terminator in front of all services:

task tls:up

Caddy binds to port 8443 on your host and terminates TLS using wildcard resolution via 127.0.0.1.nip.io.

4. Bootstrap Zitadel IAM

Provision the identity provider and register Alexandria as an authorized relying-party application:

task auth:bootstrap

This task starts Zitadel on container port 8080 (published on host 1600), creates the default organization, registers the OIDC client, and writes ALEXANDRIA_AUTH_CONFIG_CLIENT_ID and ALEXANDRIA_AUTH_CONFIG_CLIENT_SECRET into .env.

Default Administrator: admin@alexandria.auth.127.0.0.1.nip.io
Default Password: Password1!
Zitadel Console: task auth:console -> opens http://127.0.0.1:1600/ui/console.

5. Bootstrap the Cryptographic Wallet

Start the default wallet backend (Fafnir) and provision its signing key:

task wallet:bootstrap

This starts Fafnir on port 7003 and runs scripts/fafnir-bootstrap.sh to generate the default Ed25519 signing key and DID (did:jwk).

6. Run the Alexandria Node

Start the Go application with hot-reloading:

task dev

The node connects to PostgreSQL, links with the wallet, registers routes under Gin, and binds to cleartext port 1234 behind Caddy.

Alternative Wallet Configurations

Alexandria supports Eclipse EDC IdentityHub for enterprise dataspace compliance:

# 1. Start the IdentityHub container on ports 8181 and 8182:
task identityhub:up

# 2. Launch Alexandria pointing to IdentityHub:
ALEXANDRIA_WALLET_CONFIG_WALLET=IdentityHub \
ALEXANDRIA_WALLET_CONFIG_API_HTTP_PORT=8181 \
task dev

To stop IdentityHub: task identityhub:down.

Verifying the Stack

Once services are running, verify each endpoint:

Open your browser and navigate to:

https://alexandria.127.0.0.1.nip.io:8443/api/v1/auth/login

Username: admin@alexandria.auth.127.0.0.1.nip.io
Password: Password1!

After successful authentication, you are redirected back to https://alexandria.127.0.0.1.nip.io:8443/ carrying a sealed, HttpOnly session cookie (alexandria_session).

2. User Info Endpoint

Verify your session claims:

curl -k https://alexandria.127.0.0.1.nip.io:8443/api/v1/auth/userinfo \
  -H "Cookie: alexandria_session=<YOUR_COOKIE>"

3. DID Document Resolution

Alexandria exposes its Decentralized Identifier document publicly without authentication:

curl -k https://alexandria.127.0.0.1.nip.io:8443/.well-known/did.json

4. Health & Readiness

Check node health directly:

curl -k https://alexandria.127.0.0.1.nip.io:8443/healthz
curl -k https://alexandria.127.0.0.1.nip.io:8443/readyz

Operational Cheat Sheet

Action	Command
View Caddy Logs	`task tls:logs`
View Zitadel Logs	`task auth:logs`
View Wallet Logs	`task wallet:logs`
View Database Logs	`task db:logs`
Open Postgres Shell	`task db:psql`
Open Zitadel Console	`task auth:console`
Reset Database Data	`task db:reset`
Reset Zitadel IAM Data	`task auth:reset`
Reset Wallet Data	`task wallet:reset`
EOF

Quickstart

On this page