Deploying via Docker

The following describes how to deploy cims-server using Docker. It does not cover how to setup Docker itself. For that, please refer to the relevant user documentation.

PostgreSQL Setup

To get started, you need to have access to a PostgreSQL database management server with the PostGIS extension available. Once you have access, you just need to create a database, login role, and schema for the application. The following is how you would do this with psql:

create database cims;
\c cims;
create extension postgis;
create extension "uuid-ossp";
create schema cims;
create role cims login;
alter schema cims owner to cims;
alter role cims set search_path='$user',public;
alter role cims password 'whatever-you-want';

Enable PostgreSQL connections from Docker containers

By default, postgresql listens only on the loopback interface. This means that only connections originating from the same machine as the server, connecting to a local address, will be allowed to connect. Unfortunately, this means that connections originating from our docker container will not work, since docker hosts use the docker0 network interface by default. The solution to this is to reconfigure your postgresql database to listen on the docker0 interface and to allow username/password logins over that interface.

Determine Docker's network interface address

To configure connections from postgresql, we first need to determine the internet protocol address of the docker0 network interface. This will be used in the next configuration steps.

# Get docker0's IP address
$ ip -4 addr show docker0 | sed -nE 's/.*inet ([0-9.]+).*/\1/p'
172.17.0.1 (your value may be different)

Configure PostgreSQL to listen on Docker's network interface

Next, we edit postgresql's postgresql.conf file to set the listen_addresses value. Here, we configure our server to listen on the loopback interface (localhost), and the docker0 interface (172.17.0.1, your address may be different).

listen_addresses = 'localhost,172.17.0.1'  # what IP address(es) to listen on;

Configure PostgreSQL to allow username/password logins on Docker's network interface

Finally, we need to edit postgresql's pg_hba.conf file to enable username/password logins over the docker interface. The following shows the relevant portion of the file. It includes both configuring username/password login on localhost and docker0. Again, the docker0 address may differ on your system.

# IPv4 local connections:
host    all             all             127.0.0.1/32            md5
host    all             all             172.17.0.2/32           md5

Restart the server

Finally, you just need to restart the postgresql server for the configuration to take effect. The following is how you do this on linux/unix:

sudo service postgresql restart

Running the server via Docker

Once you have setup the necessary database and user, you can start the application using docker run. Below is a sample bash script for running version cims-server, which is automatically downloaded from DockerHub:

##
# Basic setup
##
VERSION=6.2
DB=db.host.name/cims
DB_USER=cims

##
# Prompt the user for the database password so we don't have to bake it in
##
echo -n "Database password ($DB_USER): " 
read -s DB_PASS
echo

##
# Runs the docker image in production mode
##
docker run \
   -it \
   -v "cims-server:/app-storage" \
   -v "$HOME/.cims:/shared-storage" \
   -p 8080:8080 \
   --net="bridge" \
   -e "SPRING_DATASOURCE_URL=jdbc:postgresql://$DB" \
   -e "SPRING_DATASOURCE_USERNAME=$DB_USER" \
   -e "SPRING_DATASOURCE_PASSWORD=$DB_PASS" \
   -e "LOGGING_PATH=/app-storage/logs" \
   cimsbioko/cims-server:$VERSION

This will automatically create the necessary database objects and result in a running server. You can login with the test account (which you should promptly remove or reset the password) username=admin, password=test.