Atlas Setup Guide with Docker

atlas-setup-guide-with-docker.md

Atlas Setup Guide with Docker

Atlas and WebAPI can be installed as docker services. It is an alternative to installing these code sets directly on a server. This way, build dependencies and server dependencies do not need to be installed, only Docker. This guide assumes that Docker is installed along with as docker-compose.

An example configuration for running OHDSI as a local service can be found in the docker/ folder. It includes a docker-compose.yml file and .env file and it assumes that the root directory of the WebAPI sources is located in the same folder as the root directory of the sources of Atlas, and that it is called WebAPI.

Configuration

The first step to using this setup, is to create a directory that will contains the docker setup. In that directory, create a docker-compose.yml file that describes the Atlas and WebAPI services. The contents can be the following, assuming that the underlying data source is a PostgreSQL database.

version: '3'

services:
  # Atlas service, running Nginx to serve the Javascript files.
  atlas:
    build: ${ATLAS_PATH}
    image: ohdsi/atlas
    environment:
      WEBAPI_URL: ${BASE_URL}/WebAPI/
      ATLAS_HOSTNAME: ${HOSTNAME}
    labels:
      - "traefik.http.routers.atlas.rule=PathPrefix(`/atlas`)"
      - "traefik.http.services.atlas.loadbalancer.server.port=80"

  # WebAPI service, running Nginx to serve the Javascript files.
  webapi:
    build: ${WEBAPI_PATH}
    image: ohdsi/webapi
    labels:
      - "traefik.http.routers.webapi.rule=PathPrefix(`/WebAPI`)"
      - "traefik.http.services.webapi.loadbalancer.server.port=8080"
    environment:
      - JAVA_OPTS=-Xmx4g
      - CLASSPATH=":/var/lib/ohdsi/webapi/drivers/*"
      - WEBAPI_URL=${BASE_URL}
      # Specify Spring settings. Any Spring setting that is set in `pom.xml` or your own
      # settings.xml can be replaced with a variable in this list. Replace the periods (.) 
      # in the variable name with underscores (_)
      - env=webapi-postgresql
      - datasource_driverClassName=org.postgresql.Driver
      - datasource_url=jdbc:postgresql://${DATASOURCE_HOST}/${DATASOURCE_DB}
      - datasource_ohdsi_schema=ohdsi
      - datasource_username=${DATASOURCE_USERNAME}
      - datasource_password=${DATASOURCE_PASSWORD}
      - spring_jpa_properties_hibernate_default__schema=ohdsi
      - spring_jpa_properties_hibernate_dialect=org.hibernate.dialect.PostgreSQLDialect
      - spring_batch_repository_tableprefix=ohdsi.BATCH_
      - flyway_datasource_driverClassName=org.postgresql.Driver
      - flyway_datasource_url=jdbc:postgresql://${DATASOURCE_HOST}/${DATASOURCE_DB}
      - flyway_schemas=ohdsi
      - flyway_placeholders_ohdsiSchema=ohdsi
      - flyway_datasource_username=${DATASOURCE_USERNAME}
      - flyway_datasource_password=${DATASOURCE_PASSWORD}
      - flyway_locations=classpath:db/migration/postgresql

  # Host both Atlas and WebAPI from the same port: <hostname>:8080
  traefik:
    image: traefik:2.1
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --api.insecure=true --providers.docker
    ports:
      - "8080:80"

To reconfigure this for another database type, set different datasource and Flyway datasource settings, including the driver, JDBC URL and Hibernate dialect to the corresponding database settings. If additional JAR drivers need to be loaded, they can be added to a new directory drivers. Then add a volumes property to the webapi service in docker-compose.yml:

webapi:
  # other settings...
  volumes:
    - ./drivers:/var/lib/ohdsi/webapi/drivers:ro

In addition to this, create a .env file with the following properties

# Set datasource variables
DATASOURCE_HOST=<my-database-server:5432>
DATASOURCE_DB=<my-database-name>
DATASOURCE_USERNAME=<my-db-username>
DATASOURCE_PASSWORD=<my-db-password>

# Configure how this server will be reached from a user's perspective
HOSTNAME=my.example.com
BASE_URL=https://my.example.com
# For local development, set the above variables to localhost and https://localhost:8080 respectively.

# Set the paths to the Atlas and WebAPI source directories
ATLAS_PATH=../Atlas
WEBAPI_PATH=../WebAPI

Usage

Once configured, the stack can be started with

docker-compose up -d

and reached at http://localhost:8080/atlas/.

If there is any update to the source directories of either Atlas or WebAPI, run

docker-compose up -d --build

to show the latest changes.

To completely stop the services, run

docker-compose down -v

For resetting the WebAPI state, run

docker-compose restart webapi

The progress of the services can be tracked with

docker-compose logs -f --tail 300

Docker image reuse

In the setup described above, each host where Atlas and WebAPI are needed has to copy the source code repositories and build the image. By uploading a docker image to a docker repository, it only needs to be built once and it can then be reused on other hosts.

If you change the docker image name configuration of the atlas and webapi services to a docker repository that you control, you can also push these images with

docker login  # login to your docker repository
docker-compose push

That way, the images need to be built only once in an organisation and pulled from any other host. For example, images can be built by individual developers and used by the others, or they can be built on an automated build server. When the latest changes should be pulled, run

docker-compose pull

Note that if the docker repository is private, ensure that you are logged in to the repository with docker login.

Advanced configuration

In a fully Docker setting, you could also host the database in the docker-compose stack. To do this, add a service

  postgresql:
    image: bitnami/postgresql:12.1.0
    volumes:
      - ./postgresql/data:/bitnami/postgresql
    ports:
      - "5432:5432"
    environment:
      - POSTGRESQL_USERNAME=${DATASOURCE_USERNAME}
      - POSTGRESQL_PASSWORD=${DATASOURCE_PASSWORD}
      - PGPASSWORD=${DATASOURCE_PASSWORD}
      - POSTGRESQL_DATABASE=${DATASOURCE_DB}

This will create a new directory postgresql/data which will contain the raw PostgreSQL files. The database can be reached with a regular psql -h localhost -U <db-user> command. In .env, set DATASOURCE_HOST=postgresql:5432 to use the internal docker hostname of the new service.