Getting Started
Prerequisites
System requirements, runtime dependencies, and local network port allocations for Alexandria.
Prerequisites
Before developing or running Alexandria locally, ensure your workstation meets the runtime and tooling requirements detailed below.
Required Tooling
| Dependency | Minimum Version | Purpose |
|---|---|---|
| Go | 1.26+ | Compiles the node binary and executes unit/integration test suites. |
| Docker & Compose | 24+ / v2 | Manages containerized services (PostgreSQL, Zitadel, Caddy proxy, wallets). |
| Task | 3+ | Project task runner coordinating certificate trust, secret loading, and orchestration. |
| OpenSSL | 3+ | Generates the local Certificate Authority (CA) and server certs (preinstalled on macOS/Linux). |
task is mandatory: commands in Taskfile.yaml automate certificate trust, load .env secrets, and coordinate multi-container dependencies.
Local Network & DNS (nip.io)
Alexandria terminates TLS even in local development using Caddy (documented in ADR 0005). All services bind locally using subdomains routed through 127.0.0.1.nip.io:
- Node Portal & API:
https://alexandria.127.0.0.1.nip.io:8443 - Zitadel IAM:
https://auth.127.0.0.1.nip.io:8443 - Wallet Service (Fafnir): Bound to
http://127.0.0.1:7003
nip.io automatically maps any wildcard IP prefix directly back to loopback 127.0.0.1 without requiring manual edits to /etc/hosts.
Port Allocation Map
Ensure the following TCP ports are available on your machine:
| Port | Service | Bound To | Protocol | Notes |
|---|---|---|---|---|
8443 | Caddy Reverse Proxy | Host | HTTPS | Primary TLS entrypoint for external callers and browser navigation. |
1234 | Alexandria Node Core | Internal | HTTP | Listens in the clear behind the Caddy TLS reverse proxy. |
1500 | PostgreSQL 17 | Host | TCP | Relational persistence for node state and credentials. |
1600 | Zitadel Console & API | Host | HTTP/gRPC | Direct container access for bootstrap automation and admin console. |
7003 | Fafnir Wallet | Host | HTTP | Default wallet backend providing key custody and DID signing. |
8181 / 8182 | Eclipse EDC IdentityHub | Host | HTTP | Alternative enterprise wallet backend (task identityhub:up). |
8200 | HashiCorp Vault | Host | HTTP | Optional backend for Fafnir key storage (task vault:up). |
2112 | Prometheus Metrics / pprof | Internal | HTTP | Observability endpoints (/metrics, /debug/pprof). |
3000 | Documentation Server | Host | HTTP | Local Fumadocs preview server (task docs:dev). |
| EOF |