Upgrading EUDIPLO
Minor and patch releases are drop-in: change the image tag and restart. A new major version can need changes to your configuration, integration or deployment; its upgrade guide lists every one of them.
Upgrade guides
Upgrade one major version at a time and read every guide on the way.
| From | To | Guide |
|---|---|---|
| 9.x | 10.0 | 9.x to 10.0: callers grant only their own roles to clients and people, credentials:status instead of issuance:offer for credential status changes, unique client IDs, webhook time and size limits, checked webhook redirects, stricter inline webhook validation, sandbox registrar integration removed, new configuration file formats, key chain imports remove an omitted description and rotation settings, key chain rotation needs intervalDays, unchanged key chain documents are not applied again, unchanged !generate clients keep their secret |
| 8.x | 9.0 | 8.x to 9.0: object storage, outbound URL and schema synchronization defaults, TLS fails closed, stricter OAuth and OID4VP, role-scoped sessions, key export and KMS configuration, session expiry, presentation webhooks, new configuration file formats |
| 7.x | 8.0 | 7.x to 8.0: canonical $schema envelopes for configuration files |
| 6.x | 7.0 | 6.x to 7.0: verifier material for wallet-provider trust lists |
| 5.x | 6.0 | 5.x to 6.0 (at tag v8.1.0): authorizationServers model |
| 4.x | 5.0 | 4.x to 5.0 (at tag v8.1.0): field-based credential configuration |
| 3.x | 4.0 | 3.x to 4.0 (at tag v8.1.0): /api prefix, key chains, attribute providers |
| 2.x | 3.0 | No action; the migration system was introduced and runs automatically. |
Upgrade procedure
- Read the guide of every major version you cross and the release notes of the versions in between.
- Back up everything you would need to go back:
- the database (for PostgreSQL
pg_dump; for SQLite a copy of the database file taken while EUDIPLO is stopped), - the configuration folder (
CONFIG_FOLDER;config/in a CLI project) and the env file, - uploaded files (
LOCAL_STORAGE_DIRor the S3 bucket), - the key material behind encrypted columns:
MASTER_SECRETwhenENCRYPTION_KEY_SOURCE=env, otherwise the key in Vault, AWS or Azure. A database backup cannot be read without it.
- the database (for PostgreSQL
- Export the tenant configuration if you manage it as files:
eudiplo config export --output <bundle>, theneudiplo config upgrade <bundle> --dry-runshows the format migrations the new release applies (Configuration as code). - Apply the changes the guide lists for your environment variables, configuration and integrations.
- Deploy the new version.
- Compose project created with the CLI: update the CLI to the target release first (install), then run
eudiplo upgrade --image-tag X.Y.Z. It rewritesEUDIPLO_IMAGEandEUDIPLO_CLIENT_IMAGEin the instance's env file, pulls these two images, recreates the services and prints the upgrade guide for every major version it crosses. It changes nothing else: the Compose file and the other variables stay as they are. - Any other deployment: set the tag of
ghcr.io/eudiplo/eudiploandghcr.io/eudiplo/eudiplo-clientto the new version and redeploy. Use the same version for both; the client shows a warning when it talks to a backend from a different release. - Start one backend instance first; it applies the database migrations on startup (
DB_MIGRATIONS_RUN=true, the default). Scale out after it is healthy.
- Compose project created with the CLI: update the CLI to the target release first (install), then run
- Verify.
GET /healthreports"status": "ok", the startup log shows no migration or configuration import errors,eudiplo doctor --strictpasses for CLI-managed instances, andGET /api/versionreports the new version. Run one issuance and one presentation end to end.
Pin a full version tag (:9.0.0) in production. The release images are also tagged :9.0, :9 and :latest.
Database migrations are not reverted when you start an older image. To go back, restore the backup taken in step 2.
:main imagesImages tagged :main are development builds. Their database migrations can still change before the release, so upgrading a :main database to a later snapshot or to a release is not supported. Use a fresh database for every :main snapshot, or run a release.
Compatibility policy
EUDIPLO follows Semantic Versioning:
- Breaking changes only in major versions. Removed or renamed API fields and endpoints, changed defaults, stricter validation, new required environment variables and changed configuration formats wait for a major release, which comes with an upgrade guide. A breaking change in a minor or patch release is a bug; please report it.
- Deprecation before removal where feasible: a minor release deprecates, the next major removes.
- Database migrations are automatic. No manual SQL is needed.
- Configuration files are versioned per resource. A release imports files of its own and older format versions and upgrades them; it rejects files with a newer version. Files exported from a new major can therefore not be imported into the previous one.
- Client and backend of the same release work together; releases that differ only in the patch version are compatible.
Verifying release artifacts
The standalone CLI archives and SHA256SUMS.txt of every release carry a signed GitHub build provenance attestation; the Sigstore bundle is attached to the release as provenance.sigstore.json. Download the archive for your platform and the bundle from the same release, then verify with the GitHub CLI:
gh attestation verify ./eudiplo-vX.Y.Z-linux-x64.tar.gz \
--repo EUDIPLO/eudiplo \
--signer-workflow EUDIPLO/eudiplo/.github/workflows/release.yml \
--bundle ./provenance.sigstore.json
Releases up to v8.1.0 were built before the repository moved from openwallet-foundation/eudiplo to EUDIPLO/eudiplo; verify them with openwallet-foundation/eudiplo in both --repo and --signer-workflow. For v8.0.1, which has no attached bundle, omit --bundle to fetch the attestation from GitHub; earlier releases have none. The attestation proves which workflow built the artifact; a checksum alone only detects changes relative to the checksum file.
If the upgrade fails
- Read the startup log: migrations, configuration import and environment validation report their errors there.
- Compare your env file with the
.env.exampleof the target release. - Check the upgrade guide again for the area that fails.
- If the guide does not cover your case, open an issue. Restore the backup if you need the old version back.