niis/xroad-catalog-collector repository overview

⁠X-Road Catalog Collector

The X-Road Catalog Collector walks an X-Road ecosystem through a Security Server and stores its members, subsystems, services and service descriptions (WSDL and OpenAPI) in a PostgreSQL database. The companion niis/xroad-catalog-lister⁠ image serves that data over REST. The collector itself exposes no API; it is a scheduled background job with a management port for health and metrics.

Full documentation⁠ and source code⁠ are on GitHub. We suggest starting with the Installation Guide⁠ to get started.

⁠Supported platforms

• A x86-64 host with Docker Engine and Docker Compose
• PostgreSQL 16 or newer

⁠Tags

X-Road Catalog images follow the following Docker tagging strategy. Every release build is pushed under the following tags:

A security refresh is a rebuild of an already released version on an updated base image, with no application changes. It has the build date as a suffix, and the MAJOR.MINOR tag moves to it as well. The original MAJOR.MINOR.PATCH tag is left untouched.

We don't publish a latest tag, instead consider locking to the following depending on your needs:

• MAJOR.MINOR.PATCH when you want byte-for-byte reproducible deployments and control each update yourself.
• MAJOR.MINOR when you want to pick up patch releases and security refreshes without breaking changes by re-pulling, without changing your deployment files.

The collector and the lister must always run the same version, and the collector should be upgraded first because it owns the database schema. The available versions are listed in the GitHub releases⁠. Release notes are available inside the X-Road Knowledge Base⁠.

⁠Image properties

• Base image: Eclipse Temurin 25 JRE on Alpine.
• Runs as the non-root user xroad. Mounted files must be readable by that user.
• No ports for the application itself; management endpoints (health, Prometheus metrics) are served on port 8090.
• Default JVM options: -XX:MaxRAMPercentage=75.0 -XX:+ExitOnOutOfMemoryError. The heap is sized as a percentage the container's memory limit, so it should always be set.
• Graceful shutdown finalises an in-flight collection run; it is suggested to give the container a stop timeout of at least 35 seconds.
• Licensed under the MIT License.

⁠Quick start

A minimal Compose service against an externally managed PostgreSQL. For more details, refer to the installation manual linked above.

services:
  xroad-catalog-collector:
    image: niis/xroad-catalog-collector:<tag>
    restart: unless-stopped
    mem_limit: 2g
    stop_grace_period: 35s
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://db.example.org:5432/xroad_catalog?socketTimeout=60
      SPRING_DATASOURCE_PASSWORD: <collector password>
      SPRING_LIQUIBASE_PASSWORD: <database owner password>
      XROAD_CATALOG_TARGET_XROAD_INSTANCE: <X-Road instance>
      XROAD_CATALOG_TARGET_MEMBER_CLASS: <Collector member class>
      XROAD_CATALOG_TARGET_MEMBER_CODE: "<Collector member code>"
      XROAD_CATALOG_TARGET_SUBSYSTEM_CODE: <Collector subsystem>
      XROAD_CATALOG_URLS_SECURITY_SERVER_HOST: https://ss.example.org:8443
      XROAD_CATALOG_INSTANCE_IGNORED_SUBSYSTEM_IDS_0: DEV:ORG:1234567-8:MANAGEMENT
      XROAD_CATALOG_TASKS_FETCH_TIME_AFTER_HOUR: "3"
      XROAD_CATALOG_TASKS_FETCH_TIME_BEFORE_HOUR: "4"
      TZ: Europe/Helsinki

⁠Upgrading and security updates

New releases are announced through the GitHub releases⁠. To update:

1. Read the release notes of the target version and back up the database.
2. Change the image tag of both services, or re-pull if you track a MAJOR.MINOR tag.
3. Recreate the collector first and wait until it is healthy, then recreate the lister.

The full procedure is in the Upgrading⁠ section of the Installation Guide.