Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

CE-RISE DP System GitOps Template

This documentation describes how to use this repository as a deployment template for a CE-RISE Digital Passport system instance.

The template deploys hex-core-service as the stable application component and treats the HTTP io-adapter as a replaceable integration boundary. The default baseline is Docker Compose. The production target includes Kubernetes manifests based on Kustomize.

What this template assumes:

  • hex-core-service is the public-facing application component.
  • The io-adapter is an internal trusted service unless an adopter explicitly chooses a different exposure model.
  • Registry configuration is a first-class deployment concern.
  • Outbound network access from hex-core-service to the configured registry source and io-adapter is required.
  • The template uses pinned image references and pinned model catalog entries in release-ready examples.

Use the sections in this documentation according to your deployment task. They are designed as peer references rather than a single linear tutorial.

Funded by the European Union under Grant Agreement No. 101092281 — CE-RISE.
Views and opinions expressed are those of the author(s) only and do not necessarily reflect those of the European Union or the granting authority (HADEA). Neither the European Union nor the granting authority can be held responsible for them.

CE-RISE logo

Architecture

This repository is a deployment template for a DP system instance, not an application implementation.

Component model

  • hex-core-service is the invariant application component.
  • The io-adapter is the replaceable HTTP integration boundary used for record storage and external system integration.
  • Registry sources provide model artifacts consumed by hex-core-service.

Default deployment pattern

  • External clients talk to hex-core-service.
  • hex-core-service talks to the configured io-adapter over HTTP.
  • hex-core-service resolves model artifacts through the configured registry catalog.
  • The io-adapter is internal-only by default.

Security boundary

  • hex-core-service may validate JWTs directly with AUTH_MODE=jwt_jwks.
  • For HTTP adapters, bearer tokens are expected to be forwarded from hex-core-service to the io-adapter when present.
  • Any io-adapter receiving forwarded tokens must be treated as a trusted internal service.

Deployment milestones

  • MVP: working Docker Compose baseline.
  • Production template: Docker Compose plus Kubernetes manifests using Kustomize.

Non-goals

  • No frontend UI.
  • No DP domain extensions.
  • No bundled default adapter implementation in the generic template path.
  • No coupling to a single persistence technology.

Configuration

All runtime configuration is environment-driven.

The template keeps the hex-core-service variable names unchanged.

Core runtime

Expected variables include:

  • SERVER_HOST
  • SERVER_PORT
  • LOG_LEVEL
  • METRICS_ENABLED

IO adapter boundary

The template uses the current core contract directly:

  • IO_ADAPTER_ID
  • IO_ADAPTER_BASE_URL
  • IO_ADAPTER_TIMEOUT_MS

Recommended baseline:

  • IO_ADAPTER_ID=http
  • IO_ADAPTER_BASE_URL points to an externally managed or separately deployed adapter

memory is a core development mode and is not part of the main deployment template path.

Authentication

Default documented path:

  • AUTH_MODE=jwt_jwks

Common variables:

  • AUTH_JWKS_URL
  • AUTH_ISSUER
  • AUTH_AUDIENCE
  • AUTH_JWKS_REFRESH_SECS

Alternative modes such as forward_auth are supported by the core but are deployment variants rather than the baseline. AUTH_MODE=none is a dev-only escape hatch and should not be treated as a normal deployment mode.

Overlay intent:

  • k8s/overlays/dev may use AUTH_MODE=none for local cluster bring-up
  • k8s/overlays/prod uses the jwt_jwks path

Registry

Registry configuration is a first-class deployment concern.

Recommended baseline:

  • REGISTRY_MODE=catalog
  • REGISTRY_CATALOG_FILE=/config/registry/catalog.json
  • REGISTRY_ALLOWED_HOSTS=codeberg.org
  • REGISTRY_REQUIRE_HTTPS=true

The template ships a pinned local catalog file with CE-RISE model entries. Those entries use explicit artifact references such as schema_url and shacl_url rather than a single inferred base_url.

Images

  • Use explicit image references with immutable version tags.
  • Do not use latest in release-ready examples.
  • Update pinned image tags as part of template releases.

Deployment

This template distinguishes between two maturity levels.

MVP

  • Docker Compose is the mandatory working baseline.
  • The default deployment points hex-core-service at an external HTTP io-adapter.
  • The default registry source is a local pinned catalog file mounted into the container.
  • The catalog uses explicit per-artifact URLs for each model entry.

Baseline structure:

Production template

  • Kubernetes manifests are included using Kustomize.
  • Secret handling is part of the production template path.
  • Operators may replace plain secret manifests with Sealed Secrets, SOPS, or external secret managers.

Baseline structure:

Adapter deployment modes

  • External adapter: default and documented baseline.
  • Internal adapter slot: supported as an optional extension point, not as the default template path.

Development overlay

The repository now includes a minimal development overlay:

  • dedicated namespace
  • debug logging
  • example cluster-local adapter URL override
  • insecure auth mode for development only

This overlay is not the production security model. It exists to make local and early-cluster testing easier.

Production overlay

The repository also includes a minimal production-oriented overlay:

  • dedicated production namespace
  • jwt_jwks authentication path
  • example auth secret manifest
  • replica count and resource requests/limits

This overlay is still a template starting point. Operators are expected to replace example secret material and environment-specific endpoints.

Network assumptions

  • hex-core-service must be able to reach the configured io-adapter.
  • hex-core-service must be able to fetch model artifacts from the configured registry sources.

IO Adapters

This template treats the HTTP io-adapter as the pluggable backend boundary.

Default expectation

  • hex-core-service uses IO_ADAPTER_ID=http
  • IO_ADAPTER_BASE_URL points at a trusted HTTP adapter service
  • Bearer tokens are forwarded to the adapter when present

Trust model

  • The adapter is internal-only by default
  • The adapter is a trusted backend component
  • The adapter must not be exposed publicly by default

External adapter mode

This is the normal template path.

  • The template deploys hex-core-service
  • The adapter is managed outside the baseline template stack
  • The operator supplies IO_ADAPTER_BASE_URL

Optional internal adapter slot

The template may include an extension point for running an adapter service alongside hex-core-service. That extension point must not become a hidden generic contract for all adapters.

Adapter-specific concerns

These remain outside the generic template path:

  • persistence layout
  • backend storage technology
  • proprietary system integration details
  • adapter-specific auth beyond the core passthrough contract

Operations

This template should support a minimal operator verification checklist.

Baseline checks

  • configuration renders correctly
  • hex-core-service starts and remains healthy
  • registry catalog is mounted and readable
  • outbound access to the registry source works
  • outbound access to the configured io-adapter works
  • one authenticated smoke request succeeds

Compose-oriented checks

Typical checks include:

  • ./scripts/validate-local-compose.sh
  • docker compose config
  • docker compose ps
  • docker compose logs

Kubernetes-oriented checks

Typical checks include:

  • ./scripts/validate-local-kubernetes.sh
  • kubectl kustomize
  • kubectl get pods
  • kubectl logs
  • service and secret presence checks

Failure domains

Common deployment failures are likely to come from:

  • invalid auth configuration
  • unreachable or misconfigured io-adapter
  • registry catalog mismatch or invalid artifact URLs
  • blocked network egress
  • image tag drift

CI/CD

This repository should keep release discipline and documentation publishing simple. Validation of deployment scaffolding is currently treated as a local operator task rather than a Forgejo runner responsibility.

Local validation

  • validate Compose rendering
  • run a local Compose smoke test against the published image
  • validate Kustomize rendering
  • run a local Kubernetes smoke test against the dev overlay
  • run shell checks if scripts are added

Repository entry points:

The local validation scripts assume:

  • Docker or a compatible Compose provider is installed
  • kubectl is installed
  • a local Kubernetes cluster is available for the Kubernetes smoke test
  • Podman/Docker networking allows outbound DNS and HTTPS from the runtime containers

Release discipline

  • update pinned image references as part of template releases
  • update pinned model catalog versions as part of template releases
  • avoid floating latest references in release-ready examples

Documentation publishing

The repository uses mdBook for documentation publishing. The existing pages workflow can publish the generated site from docs/.