niis/xroad-catalog-lister repository overview

⁠X-Road Catalog Lister

The X-Road Catalog Lister serves the members, subsystems, services and service descriptions (WSDL and OpenAPI) that the companion niis/xroad-catalog-collector⁠ image has collected into a PostgreSQL database. It offers a REST API for browsing, listing, searching and reporting on the catalog, with a Swagger UI at /api-docs.

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, and the global configuration directory /etc/xroad/globalconf must be writable by it.
• The API is served on port 8070; management endpoints (health, Prometheus metrics) are served on port 8090.
• The API has no authentication, authorization, TLS termination or rate limiting of its own. Publish it only towards a Security Server or a reverse proxy, never directly to an untrusted network.
• 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.
• Licensed under the MIT License.

⁠Quick start

A minimal Compose service against an externally managed PostgreSQL. The lister needs the configuration anchor of your X-Road instance and a volume for the global configuration it downloads. For more details, refer to the installation manual linked above.

services:
  xroad-catalog-lister:
    image: niis/xroad-catalog-lister:<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: <lister password>
      XROAD_CATALOG_SHARED_PARAMS_FILE: /etc/xroad/globalconf/<X-Road instance>/shared-params.xml
      TZ: Europe/Helsinki
    volumes:
      - ./lister/configuration-anchor.xml:/etc/xroad/configuration-anchor.xml:ro
      - globalconf:/etc/xroad/globalconf
    ports:
      - "<host IP reachable by the Security Server or reverse proxy>:8070:8070"

volumes:
  globalconf:

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