Syndication certificate setup

Ontoserver is able to distribute content on the server to other servers. This process is called syndication, more information can be found in the Ontoserver documentation.

Access protection using mTLS

The instance of Ontoserver that is hosted through the SU-TermServ is protected using Mutual TLS. This means that with every access to the endpoint, a mutual certificate exchange takes place, so you need to set up a corresponding certificate on your side and present it with every connection establishment:

Cloudflare: What is mutual TLS (mTLS)?

As a basis for the setup, of course, a corresponding certificate has to be requested. For this purpose, please refer to the corresponding FAQ entry.

Ontoserver setup

The settings of Ontoserver must be configured via environment variables in the container. The following settings need to be made:

1. The certificate must be made known to the service, as syndication can only be accessed with the appropriate certificate.
2. Ontoserver must be set to the correct URL for the syndication feed.
3. It may be desirable for your instance to offer a syndication feed that also distributes the resources from the upstream.

Certificate provision

First, it must be ensured that the certificate is available in PKCS12 format within the Ontoserver container. It is advisable to use the legacy format for PKCS12 (the entries are encrypted with 3TDEA instead of AES256) because AES encryption is not supported by all operating systems. However, in our tests, the AES encryption that is now standard in OpenSSL is compatible with the Java runtime of Ontoserver.

If you have a certificate chain in PEM format and the corresponding private key, you can convert it to PKCS12 format using OpenSSL in the console, for example with:

openssl pkcs12 -in your-chain.pem -inkey your-private.key -out syndication.p12 -export

A password must be entered, and it should not be left empty to avoid issues when passing it to Ontoserver. If you already have a certificate in PKCS12 format but no password has been set yet, we recommend using the graphical tool Keystore Explorer.

If the legacy format is desired, the parameter -legacy can be added to the command mentioned above.

The resulting file must then be made available within the Ontoserver container, for instance, through a bind mount (an exemplary docker-compose.yaml file is available below).

Now, the certificate must be provided to the Ontoserver process, which is done via Java options that need to be set within an environment variable.

For a minimal server, the following option should be set:

JAVA_OPTS=-Xmx4G -Dspring.datasource.url=jdbc:postgresql://onto-db/postgres -Djavax.ssl.keyStoreType=pkcs12 -Djavax.net.ssl.keyStore=/syndication.p12 -Djavax.net.ssl.keyStorePassword=password

In this line, further options are also adjusted, specifically the assigned memory (in this case, a maximum of 4 gigabytes, so that manual indexing of SNOMED CT would be rejected by Ontoserver, and SNOMED CT can only be consumed via syndication) and the JDBC URL to the PostgreSQL database (here under the Docker hostname onto-db); please adjust these parameters accordingly.

Through the three options -Djavax.ssl.keyStoreType, -Djavax.net.ssl.keyStore, and -Djavax.net.ssl.keyStorePassword, the corresponding certificate is presented during an HTTP request from Ontoserver, enabling access to the syndication feed, the binary indexes for SNOMED CT and LOINC, as well as the FHIR API for consuming FHIR resources via syndication.

Syndication setup

As a second step, Ontoserver now needs to connect to the upstream’s syndication feed:

atom.syndication.feedLocation=https://ontoserver.mii-termserv.de/synd/syndication.xml

With this, the minimal necessary configuration is now complete.

Customizing Syndication

If desired, additional options for syndication can be configured. For example, Ontoserver can consume multiple syndication sources simultaneously and then provide them as a combined XML file. For the corresponding options, please refer to the Ontoserver documentation.

Interesting options may include the following:

• atom.syndication.publish.enabled - this enables your server to act as a syndication upstream (true/false)
• atom.syndication.publish.fhir.enabled - should all FHIR resources be distributed (true), only marked ones (selected), or none (false)?
• atom.syndication.publish.index.enabled - similarly for SNOMED CT and LOINC, which are distributed as binary indexes (true/selected/false).
• atom.syndication.republishUpstreamEntries - this includes all resources from our upstream feed in your feed, not just your own resources.
• ontoserver.synd.base - this allows you to adjust the URLs used in your syndication feed (in combination with ontoserver.fhir.base).
• atom.syndication.publish.feedTitle - the name of your own syndication feed (an arbitrary string).
• atom.syndication.excludeXml - can be set to true to reduce the feed size.
• atom.syndication.disableChecksums - likewise.

Functional test

To use syndication, the “Ontocommand” tool from CSIRO is very helpful.

When you visit https://ontoserver.csiro.au/ui, a page should appear where you can enter the endpoint of your server (for this example, this is simply http://localhost:8080/fhir). Please note that Ontocommand communicates directly with the services of Ontoserver from your browser, so you need to ensure that the appropriate CORS headers are configured on your system.

Now click on Syndication in the left navigation, and your server should automatically load and display the feed:

The feed when calling Ontocommand

You can now load both binary indexes for SNOMED CT and LOINC as well as FHIR resources into your server using the corresponding button:

Binary indices in the feed

FHIR-CodeSystem resources in the feed

Exemplary configuration files

docker-compose.yaml (minimal example)

services:
  onto-db:
    image: postgres:12
    container_name: onto-db
    volumes:
      - ./data/pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
    environment:
      - POSTGRES_HOST_AUTH_METHOD=trust

  ontoserver:
    image: quay.io/aehrc/ontoserver:ctsa-6
    container_name: ontoserver
    ports:
      - 8080:8080
    depends_on:
      onto-db:
        condition: service_healthy
    env_file:
      - ./.ontoserver.env
    volumes:
      - ./data/onto:/var/onto
      - ./syndication-certificate.p12:/syndication.p12

.ontoserver.env

ONTOSERVER_INSECURE=true
JAVA_OPTS=-Xmx4G -Dspring.datasource.url=jdbc:postgresql://onto-db/postgres -Djavax.ssl.keyStoreType=pkcs12 -Djavax.net.ssl.keyStore=/syndication.p12 -Djavax.net.ssl.keyStorePassword=password
atom.syndication.feedLocation=https://ontoserver-ballot.mii-termserv.de/synd/syndication.xml
ontoserver.security.enabled=false
atom.syndication.publish.enabled=true
atom.syndication.publish.feedTitle=Tester for Ontoserver Syndication Redistribution