Quick start

These are some brief instructions to get you up and running with Ontoserver.

Make sure you check the details of the latest changes.

1. System Requirements
2. Set up your environment
3. Minimal configuration
4. Common configurations
5. Running Ontoserver

System Requirements

Requirements for running a single instance are heavily dependent on the intended usage. For the basic usage pattern (<20 concurrent users, syndicating a small number of binary indexes but not building indexes from source), the following resource levels are recommended (on top of a 64-bit Docker machine).

Building indexes from sources (e.g. RF2) is very demanding on memory – in these cases, at least 16GB of RAM is recommended.

Set up your environment

• In order to run Ontoserver, you first need a Docker environment. This will allow you to control the hosts (whether real or virtual, local or remote) on which Ontoserver and its database will run.The simplest method is to download and install a Docker Engine. This should provide you with both the docker and docker-compose commands. If you wish to run Ontoserver on a remote virtual host, you may need to configure the appropriate drivers
• Establish an account with quay.io
• Obtain the appropriate licence:
  • Within Australia, email help@digitalhealth.gov.au to request a (free) Ontoserver licence. ADHA will then arrange authorisation for your quay.io account
  • Elsewhere, email ontoserver-support@csiro.au to discuss licensing terms (both evaluation and production licences are available for single and multiple instances with no limit on the number of users). Once the licence is established, CSIRO will register your quay.io account name to enable access to their repository
• Log in to quay.io with:docker login quay.io

Minimal configuration

Create a text file called docker-compose.yml with the following contents (or download ./docker-compose.yml).

version: '3'
volumes:
  onto:
    driver: local
  pgdata:
    driver: local
services:
  db:
    image: postgres:12
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    environment:
      - POSTGRES_HOST_AUTH_METHOD=trust
  ontoserver:
    image: quay.io/aehrc/ontoserver:ctsa-6
    container_name: ontoserver
    read_only: true
    security_opt:
      - no-new-privileges
    depends_on:
      - db
    ports:
      - "8443:8443"
      - "8080:8080"
    environment:
#      - ONTOSERVER_INSECURE=true # Only add if you wish to disable SSL/TLS
      - spring.datasource.url=jdbc:postgresql://db/postgres
# These two lines are specific to deployment in Australia only
      - authentication.oauth.endpoint.client_id.0=NCTS_CLIENT_ID         # Replace with appropriate value
      - authentication.oauth.endpoint.client_secret.0=NCTS_CLIENT_SECRET # Replace with appropriate value
      - JAVA_OPTS=-Xmx2G       # Minimum
#      - JAVA_OPTS=-Xmx8G      # Preferred
    volumes:
      - onto:/var/onto
      - /tmp
      - /var/log

If deploying in Australia, details on configuring NCTS_CLIENT_ID and NCTS_CLIENT_SECRET can be found here.Otherwise, you only need to include this configuration if you have a secured upstream syndication service. In this case, the process for obtaining credentials will be specific to your syndication provider.

You will almost certainly want to set the JVM maximum heap via JAVA_OPTS=-Xmx as per below, as the defaults can be unreliable.

Common configurations

• For production deployment we strongly recommend running Ontoserver behind an HTTP caching reverse proxy. We have found NGINX to be a very suitable for this task.
• You can find several sample deployments on GitHub. This is the simplest path to installing custom certificates for SSL/TLS support.

Running Ontoserver

Start

docker-compose up -d

Note: Ontoserver can take a short while (up to 60 seconds) to start up. During this time it will not respond to requests such as downloading a SNOMED CT-AU version.

Stop

docker-compose stop

Download the latest SNOMED CT-AU version

docker exec ontoserver /index.sh

Download a specific SNOMED CT-AU version

docker exec ontoserver /index.sh -v 20191231

Note: Retrieving a SNOMED index involves a large download; this may take a while, depending on network bandwidth.

For further documentation on index.sh

docker exec ontoserver /index.sh -h

View the logs

docker logs ontoserver

Note: If you wish to see live updates to the logs, use

docker logs -f ontoserver