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.
• Service images and model catalog entries are pinned to published versions. Image settings remain configurable for the deployment.
• Optional downstream services may be layered on top through isolated Compose profiles or Kustomize overlays.

The supplied optional extensions deploy RE Indicators, SEE Impacts, or both alongside the same core service. Their deployment references cover service selection, configuration, network access, resource settings, and readiness checks.

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.

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.
• Optional downstream application services may depend on hex-core-service without becoming part of the io-adapter boundary.
• 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.

Optional application services

RE Indicators and SEE Impacts are optional HTTP services. They use HEX Core for data-model validation without changing the core-to-adapter contract. They can run separately or together, with one shared core deployment.

The template provides their image references, internal core endpoint, environment configuration, and deployment resources. Optional Extensions lists the profiles, overlays, ports, probes, and storage settings.

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.
• Application-service endpoints are separate entry points from HEX Core. Apply access controls to any exposed service; core authentication does not automatically protect other containers’ ports.
• SEE is reachable through the Compose network and a loopback-only host port, or a Kubernetes ClusterIP service. Its bearer token authenticates outgoing HEX Core requests, not incoming API calls. Remote access requires an authenticated reverse proxy or ingress.

Deployment targets

• Docker Compose baseline with optional calculation-service profiles.
• Kubernetes manifests using Kustomize, with development, production, and optional calculation-service overlays.

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.

The Compose catalog (compose/registry/catalog.json) and Kubernetes catalog (k8s/base/registry-configmap.yaml) register these model versions:

Schema and SHACL URLs point to the corresponding versioned pages-v tags on Codeberg. When updating registry configuration, keep the model identifiers, versions, and artifact URLs aligned in both catalogs. HEX Core needs outbound HTTPS access to the configured artifact hosts.

Optional downstream services

The baseline template does not require any downstream application service beside hex-core-service.

RE Indicators

The re-indicators Compose profile reads these settings from compose/.env or the shell environment:

Compose maps the connection settings to HEX_CORE_BASE_URL, ARTIFACT_BASE_URL_TEMPLATE, and HTTP_TIMEOUT_SECS. Kubernetes uses these native names in the re-indicators-env ConfigMap.

SEE Impacts

The see-impacts Compose profile reads these settings from compose/.env or the shell environment:

Compose maps the prefixed variables to the service’s native variables: HEX_CORE_BASE_URL, HEX_CORE_BEARER_TOKEN, HTTP_TIMEOUT_SECS, CALCULATION_TIMEOUT_SECS, and MAX_CONCURRENT_CALCULATIONS.

The bearer token authenticates SEE’s requests to HEX Core; it does not authenticate callers of SEE. Compose publishes SEE on 127.0.0.1 only, while Kubernetes uses a ClusterIP service. Provide an authenticated reverse proxy or ingress for remote access rather than exposing SEE directly.

Kubernetes uses those native names in the see-impacts-env ConfigMap and the optional see-impacts-auth Secret. Put HEX_CORE_BEARER_TOKEN in the Secret, not the ConfigMap. The prefixed Compose variables do not configure Kubernetes deployments.

Both deployments set BRIGHTWAY_WORKSPACE_DIR=/var/lib/see-impacts/brightway. This is writable temporary working storage, not record persistence. Kubernetes mounts an emptyDir; Compose uses the container’s writable layer. Allow enough temporary disk space for the configured concurrency. No persistent volume is required by the supplied extension.

Keep .env files and token material out of version control. If requests pass through a reverse proxy, configure its response timeout to accommodate calculations up to the configured worker time limit.

Images

The supplied image references select these published releases:

Compose defines these defaults in .env.example; Kubernetes deployment manifests use the same versions. The JSONDB image belongs only to the optional Compose adapter slot, not the baseline or Kubernetes deployment.

Existing compose/.env files are not updated automatically. Set their image variables to the selected release tags when adopting this template version. Image overrides remain supported; use explicit release tags or digests rather than floating latest references, and keep Compose and Kubernetes references aligned.

Deployment

The template supports Docker Compose and Kubernetes with Kustomize. Both use the same model catalog and default to an external HTTP IO adapter.

Docker Compose

• 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.

Configuration lives in compose/docker-compose.yml, compose/.env.example, and compose/registry/catalog.json.

From the repository root, create compose/.env from compose/.env.example if it does not already exist. Configure the adapter endpoint and authentication before starting services:

cd compose
docker compose config
docker compose up -d

Select optional application services with profiles, from compose/:

The default host ports are 8080 for HEX Core, 8083 for RE Indicators, and 8084 for SEE Impacts. SEE is bound to 127.0.0.1, so its published port is accessible only from the deployment host. Other containers reach it through the Compose network. Use the corresponding port variables in .env to change the port numbers. When inspecting or stopping optional services, select the same profiles.

For remote SEE access, configure an authenticated reverse proxy. The service’s HEX Core bearer token protects its outgoing validation requests, not incoming requests to the calculation API.

Kubernetes

• 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.

The baseline resources are in k8s/base, with environment configuration in k8s/overlays/dev and k8s/overlays/prod. Render the selected overlay before applying it. From the repository root, for the baseline development deployment:

kubectl kustomize k8s/overlays/dev
kubectl apply -k k8s/overlays/dev

Choose application-service overlays from Optional Extensions. Each combines the selected environment’s core deployment with the requested services. Application services use ClusterIP networking; configure authenticated ingress or a reverse proxy separately for external access.

Adapter deployment modes

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

Optional downstream services

The template may also host optional services that sit beside hex-core-service and use it as an application dependency.

• RE Indicators Calculation and SEE Impacts Calculation have separate Compose profiles and Kubernetes extensions.
• Both depend on hex-core-service for model validation, not directly on the IO adapter.
• Their required models are registered in the supplied versioned catalogs.
• Both can be deployed together without duplicating the core resources.

Extension resources define service ports, probes, resource requests, and temporary storage. SEE requests one CPU and 2 GiB of memory and mounts an emptyDir workspace. Size temporary storage and concurrency for the deployment. Optional Extensions lists these settings for each service.

When core authentication is enabled, configure the SEE bearer token using the Compose variable or Kubernetes Secret described in Configuration. See Optional Extensions for all service combinations.

Development overlay

The development overlay supplies:

• 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 production overlay supplies:

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

Set environment-specific adapter and identity-provider endpoints and supply managed credentials before deployment.

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.
• Calculation services must be able to reach hex-core-service using their configured service URL.
• Reverse proxies serving SEE requests must allow sufficient response time for calculations; the worker time limit defaults to 900 seconds.

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 internal-adapter Compose profile adds the io-adapter service alongside HEX Core. IO_ADAPTER_IMAGE selects its image. Add the environment settings, network access, and volumes required by the chosen adapter, then point IO_ADAPTER_BASE_URL to its internal HTTP endpoint.

This service slot does not supply an adapter-specific database configuration. Use the selected adapter’s deployment documentation for its dependencies, credentials, and storage. No adapter Deployment is included in the Kubernetes baseline.

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

Optional Extensions

Optional application services are enabled through Compose profiles or Kustomize overlays. They connect to hex-core-service without changing the baseline core-to-adapter deployment contract. Container versions are listed in Configuration.

RE indicators calculation service

The Compose template includes an optional re-indicators profile that adds re-indicators-calculation-service.

It connects to HEX Core over the Compose network and publishes container port 8081 on host port 8083 by default. Configure its image, host port, core endpoint, artifact endpoint, and HTTP timeout using the RE Indicators settings.

Typical local commands:

cd compose
docker compose --profile re-indicators up -d
cd ..
COMPOSE_PROFILES=re-indicators ./scripts/validate-local-compose.sh
K8S_OVERLAY=dev-re-indicators ./scripts/validate-local-kubernetes.sh

The service is deployed only when its profile or overlay is selected.

SEE impacts calculation service

The see-impacts profile adds see-impacts-calculation-service. It connects to HEX Core over the Compose network and publishes container port 8080 at 127.0.0.1:8084 by default. Configure its image, host port, core endpoint, credentials, timeouts, and concurrency using the SEE settings.

From the repository root, after configuring compose/.env:

cd compose
docker compose --profile see-impacts up -d
curl --fail http://localhost:8084/capabilities

Other containers can reach SEE on the Compose network. Remote access requires an authenticated reverse proxy; the HEX Core bearer token does not authenticate incoming SEE requests. The Compose health check uses /capabilities to verify service initialization. Writable working storage is provided by the container’s writable layer; no persistent volume is required.

Set SEE_IMPACTS_HEX_CORE_BEARER_TOKEN when HEX Core requires authentication. Keep credentials out of version control.

Kubernetes overlays

Each overlay combines the appropriate baseline with resources under k8s/extensions/. The combined overlays include the core only once. The baseline dev and prod overlays remain independent of both calculation services.

Both extensions provide ClusterIP services and ConfigMaps:

SEE mounts an emptyDir at /var/lib/see-impacts/brightway for temporary working storage. The deployment requests one CPU and 2 GiB of memory. Adjust resources, concurrency, and temporary disk space for the expected workload. The RE Indicators extension does not set resource requests or mount working volumes.

The see-impacts-env ConfigMap supplies the core URL, timeouts, concurrency, and workspace path. For authenticated deployments, create a see-impacts-auth Secret in the selected namespace with a HEX_CORE_BEARER_TOKEN key. Manage this secret through your deployment’s secret-management mechanism, not a committed token.

Running both services

Compose:

cd compose
docker compose --profile re-indicators --profile see-impacts up -d

Kubernetes, from the repository root:

kubectl apply -k k8s/overlays/dev-calculations

For production, configure the core authentication and adapter settings, supply the SEE token, and use prod-calculations instead. Production overlays do not configure an identity provider for you.

Deployment validation

From the repository root:

make validate-compose-see-impacts
make validate-compose-calculations
make validate-kubernetes-see-impacts
make validate-kubernetes-calculations

These checks verify deployment rendering, service startup, initialization responses, and required schema availability through HEX Core. The RE Indicators and combined targets also perform an API smoke request. See Operations for exact coverage, test isolation, and production authentication requirements.

Component Documentation

Use the component documentation for API usage and service-specific behavior:

• RE Indicators documentation
• SEE Impacts documentation

Operations

Use the checks below to verify configuration, service readiness, and access to model artifacts.

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
• COMPOSE_PROFILES=re-indicators ./scripts/validate-local-compose.sh
• make validate-compose-see-impacts
• make validate-compose-calculations

The validator creates a temporary configuration and a uniquely named Compose project, then removes its own containers on exit. It does not overwrite compose/.env or stop an operator’s stack. Ports still need to be free; use HEX_CORE_PORT, RE_INDICATORS_CALC_PORT, and SEE_IMPACTS_CALC_PORT in the shell environment to select alternative validation ports. The validation core uses development-only unauthenticated mode.

To inspect the baseline deployment, run from compose/:

docker compose ps
docker compose logs hex-core-service
curl --fail http://localhost:8080/admin/health

For deployments with both application services:

docker compose --profile re-indicators --profile see-impacts ps
docker compose --profile re-indicators --profile see-impacts logs re-indicators-calculation-service see-impacts-calculation-service
curl --fail http://localhost:8083/health
curl --fail http://localhost:8084/health
curl --fail http://localhost:8084/capabilities
curl --fail http://localhost:8084/methods

Use the configured host port if it differs from the default.

Kubernetes-oriented checks

Typical checks include:

• ./scripts/validate-local-kubernetes.sh
• K8S_OVERLAY=dev-re-indicators ./scripts/validate-local-kubernetes.sh
• K8S_OVERLAY=prod-re-indicators ./scripts/validate-local-kubernetes.sh
• make validate-kubernetes-see-impacts
• make validate-kubernetes-calculations

The Kubernetes validator needs a running cluster and permission to create resources. It creates the selected namespace (dp-system-dev or dp-system-prod) and removes its resources on exit. It refuses to proceed if that namespace already exists, so it cannot be run against an existing deployment. Use kubectl kustomize for rendering-only checks without a cluster.

To inspect an existing development deployment:

kubectl get pods -n dp-system-dev
kubectl logs -n dp-system-dev deployment/hex-core-service

When the corresponding application services are enabled:

kubectl logs -n dp-system-dev deployment/re-indicators-calculation-service
kubectl logs -n dp-system-dev deployment/see-impacts-calculation-service
kubectl port-forward -n dp-system-dev service/see-impacts-calculation-service 18084:8080

With the port forward running, the SEE endpoints are available at http://localhost:18084.

Validation Coverage

The baseline checks render the deployment configuration, start HEX Core, and check health. Development validation also checks core readiness and model listing. Production authentication requirements are described below.

Application-service checks add:

The SEE validator checks service identity, initialization metadata, non-empty and consistent method registration, and the schema versions in the supplied catalog. Combined targets run both sets of application-service checks.

Production Kubernetes validation checks service readiness without authenticated core requests by default. Set SEE_IMPACTS_HEX_CORE_BEARER_TOKEN in the validator’s shell environment to also check the three schemas against an authenticated core. That variable authenticates the validator only; configuring the running SEE service still requires the Kubernetes Secret. A reachable identity provider and valid core authentication settings are required for those requests to succeed.

The validation helper itself has lightweight tests that do not require containers, a cluster, or network access:

make validate-helpers

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
• insufficient writable working storage or service resources
• a missing or expired SEE bearer token when core authentication is enabled

Production-oriented overlays may also appear healthy while still rejecting unauthenticated smoke traffic by design.

CI/CD

Deployment validation runs locally against the published images. The Forgejo workflow publishes this template’s documentation; it does not deploy a running stack.

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 the validation-helper tests with Python’s standard library

Repository entry points:

• Makefile
• scripts/validate-local-compose.sh
• scripts/validate-local-kubernetes.sh
• scripts/validate_see_service.py

Useful local targets:

• make validate
• make validate-helpers
• make validate-compose
• make validate-compose-re-indicators
• make validate-compose-see-impacts
• make validate-compose-calculations
• make validate-kubernetes
• make validate-kubernetes-re-indicators
• make validate-kubernetes-see-impacts
• make validate-kubernetes-calculations

Deployment checks cover configuration rendering, service readiness, initialization, and access to required core schemas. Operations documents the checks for each service. The helper tests also check failure reporting and that validation cannot overwrite the operator’s Compose environment or remove an existing Kubernetes deployment.

For production-oriented overlays, local validation currently proves deployment and health. End-to-end authenticated functional checks still require real auth infrastructure and credentials.

The local validation scripts assume:

• Docker or a compatible Compose provider is installed
• Python 3 and curl are 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

Versioned dependencies

Service image references are pinned to the published releases listed in Configuration, consistently across Compose and Kubernetes. Model entries use versioned Codeberg artifact URLs in both catalogs. Keep both deployment formats and model catalogs aligned when updating these dependencies.

Documentation publishing

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

Release archival

The GitHub mirror creates an archival release when a version tag is pushed. Its release notes are extracted automatically from the matching version heading in CHANGELOG.md, with the leading v removed from the tag for matching. Missing, duplicate, or empty entries stop release creation. The workflow also links to the canonical Codeberg repository and documentation; it does not build container images, SDKs, or API artifacts.