Installation & Configuration Guide

Authoritative narrative — for the deployment view (Kubernetes, container layout, admin setup) see the arc42 document at github.com/eclipse-xfsc/docs/federated-catalogue/src/docs/architecture/. For the quickstart (clone, build, run), see Build & Test Procedures and the repo's docker/README.md. This page is kept as the detailed configuration-property reference.

The Federated Catalogue is a Spring Boot service (Java 21, Spring Boot 3.5.7). All settings can be overridden by Spring profile properties or by environment variables — the canonical mapping is uppercase with dots and hyphens turned into underscores (datastore.file-path → DATASTORE_FILE_PATH). Secrets must be overridden in production via Kubernetes secrets or equivalent.

Deployment manifests live under /deployment; the Helm chart is at deployment/helm/fc-service. For local development, the docker/dev.sh script wraps a docker-compose stack — see Build & Test Procedures.

The Catalogue is composed of one or more FC Server instances and a Store layer: Metadata Store (PostgreSQL), Graph Store (Fuseki by default, or Neo4j), and Content Store (FileSystem for the original VPs and assets). The Store layer is brought up before the FC Server. Distributed query across multiple FC instances is supported (see federated-catalogue.query.partners below).

FC configuration parameters

Finding a property: the page is grouped by subsystem (datastore, graph store, file store, query, trust frameworks & verification, content types, pub/sub, revalidation, scheduler, IAM, admin dashboard, logging, actuator). Use full-text search (Ctrl/Cmd+F) on the property key or its environment-variable form (e.g. DATASTORE_FILE_PATH). Properties not listed here are either Spring Boot defaults or internal — open an issue if something you rely on is missing.

Property	Description	Default value
server.port	Port the Tomcat servlet container binds to	8081
server.shutdown	Servlet container shutdown mode	graceful
spring.datasource.url	JDBC URL of the Metadata Store (PostgreSQL)	jdbc:postgresql://localhost:5432/postgres
spring.datasource.username	PostgreSQL username	postgres
spring.datasource.password	PostgreSQL password (override via k8s secret in production)	postgres
spring.transaction.default-timeout	Default Metadata Store transaction timeout	10 (seconds)
spring.datasource.hikari.maximumPoolSize	HikariCP max pool size for the Metadata Store	128
spring.datasource.hikari.minimumIdle	HikariCP minimum idle connections	8
spring.datasource.hikari.connectionTimeout	HikariCP connection acquisition timeout (ms)	30000
spring.datasource.hikari.idleTimeout	HikariCP idle connection timeout (ms)	600000
spring.datasource.hikari.maxLifetime	HikariCP max connection lifetime (ms)	1800000
spring.servlet.multipart.max-file-size / .max-request-size	Multipart upload limits	10MB
spring.threads.virtual.enabled	Use JDK 21 virtual threads	true
spring.security.oauth2.resourceserver.jwt.issuer-uri	OAuth2 issuer URI for the JWT resource server	http://key-server:8080/realms/gaia-x
server.tomcat.threads.max	Tomcat max worker threads	200
server.tomcat.threads.min-spare	Tomcat minimum spare worker threads	20
federated-catalogue.instance-count	Number of FC instances in the cluster (used to shard revalidation work)	3

Graph store (pluggable: Fuseki default, Neo4j optional)

The active backend is resolved at startup by RoutingGraphStore: the persisted admin preference ( graphstore.preferred.backend) first, the configured graphstore.impl second, NONE last. The admin "Switch Backend" action performs a live in-process switch.

Property	Description	Default value
graphstore.impl	Cold-boot backend: fuseki, neo4j, or none	fuseki
graphstore.fuseki.uri	Fuseki SPARQL endpoint	http://localhost:3030/ds
graphstore.neo4j.uri	Neo4j Bolt URI	bolt://localhost:7687
graphstore.user	Graph DB username (Neo4j only)	neo4j
graphstore.password	Graph DB password (override via k8s secret in production)	neo12345
graphstore.auto-rebuild-on-empty	Trigger an automatic rebuild on empty backend at startup	false
graphstore.rebuild-threads	Worker threads used by the graph-store rebuild job	4
graphstore.rebuild-batch-size	Number of SDs per batch during graph-store rebuild	100
graphstore.query-timeout-in-seconds	SPARQL query timeout (Neo4j backend)	(none — backend default)
graphstore.timeout-marker	Substring used to detect upstream timeout exceptions	The transaction has not completed within the timeout specified
graphstore.uri	Deprecated single URI fallback for either adapter	${graphstore.fuseki.uri}

File store

Property	Description	Default value
federated-catalogue.file-store.cached	Enable caching FileStore implementation	true
federated-catalogue.file-store.cache-size	FileStore in-memory cache size (entries)	128
federated-catalogue.file-store.schema.location	Subdirectory holding RDF schema definitions used for SD / credential validation	schemaFiles
federated-catalogue.file-store.asset.location	Subdirectory holding non-RDF asset content (PDFs, images, binaries)	assetFiles
federated-catalogue.file-store.context-cache.location	Subdirectory holding cached JSON-LD context documents	contextCacheFiles
federated-catalogue.file-store.directory-tree-depth	Depth of the hashed directory tree FileStore uses to shard files	1
federated-catalogue.file-store.directory-name-length	Length of each hashed directory-name segment in the FileStore tree	2
datastore.file-path	Base FileStore location on disk (parent of the subdirectories above)	target

Query

Property	Description	Default value
federated-catalogue.query.partners	Other FC instances used in distributed query	(empty)
federated-catalogue.query.self	This FC instance's external address	http://localhost:${server.port}

Trust frameworks and verification

Verification is organised around trust-framework bundles. Enable a framework family by name (declared in the bundle's framework.yaml); per-framework verification config (trust anchor URL, etc.) lives in the bundle. Individual verification steps can be toggled independently.

Runtime overrides. The external client identifiers of an already-registered bundle — compliance service URL, compliance path, API version, timeout, client implementation key, trust-anchor list URL — can be overridden at runtime without redeployment through the admin API:

• PATCH /admin/trust-frameworks/bundles/{bundleId} with application/merge-patch+json. A property set to a value overrides the YAML; a property set to JSON null clears the override; an omitted property leaves the existing state untouched.
• DELETE /admin/trust-frameworks/bundles/{bundleId} clears every persisted override for the bundle (idempotent).
• GET /admin/trust-frameworks returns each bundle's effectiveConfig (values currently in use) and overriddenFields (which of those values come from a persisted override vs. the YAML).

The override precedence is DB > bundle YAML > hard-coded default, applied per call by TrustFrameworkProfileResolver. The filesystem overlay path (FEDERATED_CATALOGUE_TRUST_FRAMEWORKS_OVERRIDE_PATH) remains the right tool for bundle-shape changes (roles, ontology, validation type) and for shipping a new bundle. Both override mechanisms require the ADMIN_ALL role for admin-API writes.

Property	Description	Default value
federated-catalogue.enabled-trust-frameworks	Comma-separated framework families to enable (env: FEDERATED_CATALOGUE_ENABLED_TRUST_FRAMEWORKS=gaia-x)	(empty)
federated-catalogue.trust-frameworks.override-path	Filesystem path with bundle subdirectories that override (by id) or extend the classpath bundles (env: FEDERATED_CATALOGUE_TRUST_FRAMEWORKS_OVERRIDE_PATH)	(empty)
federated-catalogue.verification.semantics	Run RDF semantics validation	true
federated-catalogue.verification.vp-signature	Verify VP signature	false
federated-catalogue.verification.vc-signature	Verify VC signatures	false
federated-catalogue.verification.require-vp	Reject credentials submitted bare (i.e. not wrapped in a VP)	false
federated-catalogue.verification.signature-verifier	uni-res (delegate to a Universal Resolver) or local	uni-res
federated-catalogue.verification.http-timeout	Outbound HTTP timeout in ms (DID resolution, context fetch)	3000
federated-catalogue.verification.did.base-url	Universal Resolver base URL	https://dev.uniresolver.io/1.0
federated-catalogue.verification.did.cache.size	Resolved-document cache size	100
federated-catalogue.verification.did.cache.timeout	Resolved-document cache TTL	1H
federated-catalogue.verification.doc-loader.cache-size	JSON-LD context cache size	500
federated-catalogue.verification.doc-loader.cache-timeout	JSON-LD context cache TTL	24H
federated-catalogue.verification.doc-loader.enable-file	Allow file: scheme context references	true
federated-catalogue.verification.doc-loader.enable-http	Allow http(s): scheme context references	true
federated-catalogue.verification.doc-loader.enable-local-cache	Use a local context cache	false
federated-catalogue.verification.doc-loader.additional-context	Map of context URLs to fetch URLs (redirects)	(a few Gaia-X registry mappings)
federated-catalogue.verification.protected-namespace.namespace	Reserved namespace for FC metadata properties	https://projects.eclipse.org/projects/technology.xfsc/federated-catalogue/meta#
federated-catalogue.verification.protected-namespace.prefix	Prefix for the above namespace	fcmeta

DID resolution defaults: production uses the external Universal Resolver (signature-verifier: uni-res). The bundled docker-compose stack ships a local did-server (nginx) and overrides signature-verifier: local for self-contained dev — see docker/dev.env and docker/docker-compose.yml.

RDF and asset content types

Property	Description	Default value
federated-catalogue.scope	Catalogue scope marker	runtime
federated-catalogue.rdf.content-types	Accepted RDF / VC / VP content types	application/ld+json, application/vc+ld+json, application/vp+ld+json, application/vc+jwt, application/vp+jwt, text/turtle, application/n-triples, application/rdf+xml
federated-catalogue.assets.human-readable-content-types	Content types treated as human-readable assets	application/pdf, MS Word, text/html, text/plain
federated-catalogue.validation.max-assets-per-request	Max asset IDs accepted in a single validateAssets request	20

Publisher / Subscriber (SD events)

Property	Description	Default value
publisher.impl	none, ces (Credentials Event Service), or nats	none
publisher.url	Target URL — depends on impl	https://ces-v1.lab.gaia-x.eu (when ces); nats://localhost:4222 (when nats)
publisher.subject	NATS subject when nats	fc.sd
publisher.instance	Name/address of this FC deployment	http://localhost:8081
publisher.send-content	Include SD content in NATS events	false
publisher.comp-url	Compliance service URL (with ces publisher)	https://compliance.lab.gaia-x.eu/v1/api
publisher.pool-size	Thread-pool size for outbound publish workers	4
publisher.transactional	Publish events transactionally with the SD write	false
subscriber.impl	none, ces, or nats	none
subscriber.url	Source URL — depends on impl	https://ces-v1.lab.gaia-x.eu
subscriber.page-size	Events fetched per CES request	20
subscriber.fixed-rate	Delay between CES poll requests	30s
subscriber.event-type	Optional CES event-type filter (only events of this type are processed)	(unset — accept all)
subscriber.subject	NATS subject to subscribe to (when nats)	(required for nats)
subscriber.stream	NATS JetStream stream name (when nats)	(required for nats)
subscriber.group	NATS consumer group/queue name (when nats)	(required for nats)
subscriber.verify.semantics	Re-run semantics verification on incoming events	true
subscriber.verify.vp-signature	Re-run VP signature verification on incoming events	false
subscriber.verify.vc-signature	Re-run VC signature verification on incoming events	false
subscriber.verify.integrity	Verify content integrity on incoming events	true

Revalidation service

Background workers periodically re-verify previously stored SDs (e.g. when a trust anchor's revocation status changes). Work is sharded across FC instances using federated-catalogue.instance-count (see top of the table).

Property	Description	Default value
federated-catalogue.revalidation-service.worker-count	Number of revalidation worker threads per FC instance	5
federated-catalogue.revalidation-service.batch-size	Number of SDs claimed per revalidation batch	100
federated-catalogue.revalidation-service.sleeptime	Sleep (ms) between revalidation batches when idle	1000

Scheduler

Property	Description	Default value
scheduler.asset.cron.expression	Cron expression for asset / SD expiration invalidation	0 1 0 * * *
scheduler.schema.init-delay	Initial delay (ms) before schema loader runs	10000

Identity & access management (Keycloak)

Property	Description	Default value
keycloak.auth-server-url	Keycloak root URL	http://key-server:8080
keycloak.realm	Keycloak realm	gaia-x
keycloak.resource	Keycloak client ID	federated-catalogue
keycloak.credentials.secret	Keycloak client secret (env: KEYCLOAK_CREDENTIALS_SECRET)	(empty — must be provided)

Admin dashboard

Property	Description	Default value
admin.dashboard.keycloak-auth-server-url	Keycloak URL surfaced in the admin UI	${keycloak.auth-server-url}
admin.dashboard.keycloak-realm	Keycloak realm surfaced in the admin UI	${keycloak.realm}
admin.dashboard.keycloak-admin-console-url	External link to the Keycloak admin console	(empty)
admin.dashboard.file-store-path	File-store path surfaced in the admin UI	${datastore.file-path}

Logging Settings

The application uses Slf4j with the logback implementation. Root logging level is INFO. Defaults:

Logger	Description	Level
eu.xfsc.fc	Catalogue application logger	DEBUG
org.springframework.web	Spring MVC logger	DEBUG

Package rename note: the application package moved from eu.gaiax.difs.fc to eu.xfsc.fc during the migration to Eclipse XFSC. Override the old logger name only for historical compatibility — it no longer matches any current class.

Any logger can be overridden via environment variables, e.g.:

LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_WEB=INFO

Monitoring and Metrics

The Service exposes Spring Actuator endpoints by default at:

• /actuator/health
• /actuator/info
• /actuator/graph-rebuild (FC-specific — triggers a graph-store rebuild)

Additional endpoints (/metrics, /prometheus, /loggers, …) can be enabled by extending management.endpoints.web.exposure.include. The health endpoint exposes details only when_authorized.

Property	Description	Default value
management.endpoints.web.exposure.include	Exposed actuator endpoints	health, info, graph-rebuild
management.endpoint.health.show-details	When to include health details in responses	when_authorized
springdoc.api-docs.path	OpenAPI JSON document path	/api/docs
springdoc.api-docs.enabled	Expose the OpenAPI document	true
openapi.gaiaXCatalogue.base-path	Base path prefix injected into the OpenAPI spec	(empty)