What is FHIR?

FHIR is an emerging HL7 standard.

Fast Health Interoperability Resources

FHIR Specification v3.0.1

Latest FHIR Specification

Where can I get help?

There is a very large, dynamic, and welcoming community of developers on FHIR Chat (Zulip) community expectations. This is the best place to go for general questions about FHIR, terminology services and FHIR, as well as Ontoserver itself.

Where can I get support?

For technical support issues directly related to Ontoserver, please email


How do I uninstall Ontoserver?

There are two main parts to removing Ontoserver completely from your system: removing the docker images (which contain ontoserver and postgres), and removing the docker volumes (which contain the data).

You can see the docker images by running

docker images
You can uninstall them using a command like
docker rmi -f aehrc/ontoserver:5.0
Or, to remove all versions:
docker rmi -f $(docker images | grep 'aehrc/ontoserver' | awk {'print $3'})
You may also wish to remove the postgres docker image, for example by running
docker rmi -f postgres

You can see the docker volumes by running

docker volume ls
You can uninstall the docker volumes by running
docker volume rm $(docker volume ls | grep -E '_onto|_pgdata' | awk {'print $2'})

You may also wish to remove your docker-compose.yml file, or even to uninstall Docker itself (instructions can be found on the relevant Docker installation pages)

Note: these commands assume a default configuration. If you have made changes, e.g. to the volumes that are used, then the commands for uninstalling images and volumes may differ.

What if I want to use a cache?

Ontoserver is built to support standard HTTP caching using ETags and Last-Modified headers.

This means you can use standard front-side caches such as Apache, NGINX, Varnish, Squid, etc.

This GitHub project provides a sample deployment setup for Ontoserver using an NGINX cache.


How do I backup Ontoserver's data, including FHIR resources and indexes?

Ontoserver's data consists of two artifacts that need to be backed up, both mounted as docker volumes.

Note: These volume are mounted by the containers, but do not live inside the containers, so it is not sufficient to snapshot the ontoserver and postgres containers.

  • The pgdata volume mount in the db (postgres) container, which contains FHIR resources, downloaded RF2 sources, and lists of indexes
  • The onto volume mount in the ontoserver container, which contains the indexes themselves, as well as downstream syndication artifacts

Once you have your docker client pointed at the docker-machine that is running the Ontoserver instance you wish to back up, and assuming your docker-compose.yml file is located in a myOntoserver directory):

  1. docker run --rm --volumes-from ontoserver -v /home/ubuntu/backup:/backup ubuntu tar cvf /backup/backup-ontoserver.tar /var/onto
  2. docker run --rm --volumes-from myOntoserver_db_1 -v /home/ubuntu/backup:/backup ubuntu tar cvf /backup/backup-pgdata.tar /var/lib/postgresql/data

These commands create two tar files in the /home/ubuntu/backup directory of the machine (real or virtual) where Ontoserver is running. You may wish to retrieve them to another machine using a program such as sftp.

How do I restore an Ontoserver from backup (or copy to a new container)?

Once you have the backup tar files (see backup), and with your docker client pointed at the docker-machine where you want to restore Ontoserver:

  1. docker-compose up –d
  2. Wait until ontoserver is up (for example, run docker logs –f ontoserver and wait until it says Started Application in XX seconds)
  3. docker-compose stop
  4. docker run --rm --volumes-from ontoserver -v /home/ubuntu/backup:/backup ubuntu bash -c "tar xvf /backup/backup-ontoserver.tar"
  5. docker run --rm --volumes-from myOntoserver_db_1 -v /home/ubuntu/backup:/backup ubuntu bash -c "tar xvf /backup/backup-pgdata.tar"
  6. docker-compose up –d

How do I update Ontoserver to a new version?

If your docker-compose.yml file refers to a major-minor version (e.g. ontoserver:ctsa-5.0), and you want to upgrade to the latest patch version (e.g. from 5.0.0 to 5.0.1), then all you have to do is pull the latest 5.0 release. To do this, simply run

docker pull aehrc/ontoserver:ctsa-5.0

If you want to change to a specific version, then you can also change the specific version in your docker-compose.yml file. The list of available versions can be found here.

Once you have done either (or both) of these, then you can apply the change by re-upping your docker-compose:

docker-compose up -d

This should recreate the ontoserver container with the new version.

How do I migrate my Ontoserver 4.1.x resources (Value Sets, Code Systems, Concept Maps) to Ontoserver 5.0?

If you are updating to Ontoserver 5.x from Ontoserver 4.1.x, then FHIR resources (other than SNOMED and LOINC code systems) in the database will not be migrated. This is because the structure of these resources has changed from FHIR DSTU 2.1 (Ontoserver 4.1.x) to FHIR STU 3 (Ontoserver 5.x). If Ontoserver 5.x finds these old resources in its database, then it will refuse to start up.

If you wish to retrieve FHIR resources from Ontoserver 4.1.x so that you can migrate them, you can use the FHIR search (GET requests on /fhir/CodeSystem, /fhir/ConceptMap, /fhir/ValueSet) or read (/fhir/CodeSystem/[id], /fhir/ConceptMap/[id], /fhir/ValueSet/[id]) endpoints from a running Ontoserver 4.1.x instance to retrieve them.

Once resources have been converted to STU3 resources, start Ontoserver 5 with an empty database and add migrated resources either individually using FHIR create/update endpoints, or as a bundle using the /api/addBundle endpoint.