Operate EUDIPLO

These guides cover running EUDIPLO yourself: choosing a deployment, configuring storage, keys and access, and keeping the instance observable. Before you expose an instance to real wallets and users, work through the production checklist.

Choose a deployment

Deployment	Use it when	What manages it	Guide
CLI-managed Compose on one VM	You run one instance on one server and want generated config, upgrades and checks from one tool	eudiplo init, up, upgrade, doctor	Cookbook: Production on one VM
Compose without the CLI	You keep your own Compose files, for example in an existing infrastructure repository	docker compose with the files in deployment/docker-compose	Compose without the CLI
Kubernetes	You deploy to a cluster with Kustomize and bring your own database, object storage and secrets	kubectl apply -k, optionally the CLI for checks	Kubernetes

All three run the same images, ghcr.io/eudiplo/eudiplo (backend) and ghcr.io/eudiplo/eudiplo-client (web client). The bundled manifests and Compose files run one backend replica. Several replicas can share one PostgreSQL database and one S3 bucket, but configuration changes of a tenant are serialized by a database lock (see configuration as code), and the bundled PostgreSQL, RustFS and Vault services are single-instance development services.

For a first local try, use eudiplo demo from the Foundation cookbook instead.

Presets and profiles

The CLI presets, the Compose profiles in deployment/docker-compose and the Kubernetes overlays in deployment/k8s/overlays share three names:

Name	Database	Object storage	Vault	CLI	Compose	Kubernetes
minimal	SQLite	Local filesystem	-	--preset minimal	no profile	overlays/minimal
standard	PostgreSQL	S3 (bundled RustFS)	-	--preset standard	--profile standard	overlays/standard
full	PostgreSQL	S3 (bundled RustFS)	Bundled Vault in dev mode	--preset full	--profile full	overlays/full

Vault serves a different purpose depending on where full comes from:

• CLI --preset full writes a vault provider to config/kms.json and makes it the default KMS provider for new signing keys.
• Compose .env.full.example and the Kubernetes full overlay set ENCRYPTION_KEY_SOURCE=vault, so Vault holds the encryption key for data at rest. Signing keys stay in the database unless you add a kms.json.

The CLI also accepts --database, --storage and --kms to mix components, and Compose accepts the single profiles postgres, s3 and vault.

The bundled Vault runs in development mode with the root token root and keeps everything in memory, so full is for evaluation only. When its container or pod restarts, its data is gone: the encryption key has to be written again from your copy (Compose, Kubernetes), and signing keys that EUDIPLO created in Vault with --preset full are lost, because they are not exportable. In production, use a Vault with persistent storage.

Configure the instance

Set these variables in every deployment. All others have defaults, listed in the environment variable reference.

Variable	Why
PUBLIC_URL	The URL wallets and browsers use. It appears in offers, metadata and redirects. Default http://localhost:3000.
MASTER_SECRET	Signs management tokens of the built-in OAuth2 server and, with the default ENCRYPTION_KEY_SOURCE=env, derives the encryption key. At least 32 characters.
AUTH_CLIENT_ID, AUTH_CLIENT_SECRET	The first management client, created with the tenants:manage role on the first start. Required unless you use Keycloak SSO (OIDC).

Without further settings, the backend uses SQLite and local file storage in FOLDER (/app/config in the image). A minimal container start:

MASTER_SECRET="$(openssl rand -base64 32)"
AUTH_CLIENT_SECRET="$(openssl rand -base64 24)"
echo "Store these: MASTER_SECRET=$MASTER_SECRET AUTH_CLIENT_SECRET=$AUTH_CLIENT_SECRET"

docker run -d --name eudiplo -p 3000:3000 \
  -e PUBLIC_URL=http://localhost:3000 \
  -e MASTER_SECRET="$MASTER_SECRET" \
  -e AUTH_CLIENT_ID=root \
  -e AUTH_CLIENT_SECRET="$AUTH_CLIENT_SECRET" \
  -v eudiplo-data:/app/config \
  ghcr.io/eudiplo/eudiplo:latest

curl http://localhost:3000/health

Keep MASTER_SECRET for the lifetime of the data: with the default key source it derives the key that decrypts private keys and session data.

Guides

Topic	Guide
HTTPS, reverse proxy, web client on a subpath	TLS and reverse proxy
WAF rules for wallet and management routes	Web application firewall
CLI install, instances and drivers	CLI
Export, validate and import configuration	Configuration as code
Tenants, API clients, users and SSO	Tenants and access, Keycloak
Database, migrations, session retention	Database
Encryption of data at rest	Encryption keys
Files, images and logos	Object storage
Signing keys in Vault, AWS KMS, HSM	Key management (KMS)
Logs, metrics, traces	Logging, Monitoring
Capacity tests	Load testing
Upgrades between major versions	Upgrade