Deploying a SONG Server in Production

The following section describes how to install, configure and run the SONG server in production.

Prerequisites

The following software dependencies are required in order to run the server:

  • Bash Shell
  • Java 8 or higher
  • Postgres database

Note

Only a postgres database can be used, since postgres-specific features are used in the SONG server

Official Releases

Official SONG releases can be found here. The releases follow the symantic versioning specification and contain notes with a description of the bug fixes, new features or enhancements and breaking changes, as well as links to downloads and change logs. All official song releases are tagged in the format $COMPONENT-$VERSION, where the $COMPONENT portion follows the regex ^[a-z-]+$ and the $VERSION component follows ^\d+\.\d+\.\d+$ . For the SONG server, the tag format has the regex: ^song-\d+\.\d+\.\d+$. For example song-1.0.0.

Installation

Once the desired release tag and therefore $VERSION are known, the corresponding distibution can be downloaded using the command:

curl "https://artifacts.oicr.on.ca/artifactory/dcc-release/org/icgc/dcc/song-server/$VERSION/song-server-$VERSION-dist.tar.gz" -Ls -o song-server-$VERSION-dist.tar.gz

This distibution contains the default configuration and jars for running the server. To unarchive, run the command:

tar zxvf song-server-$VERSION-dist.tar.gz

Configuration

Server

By default, the SONG server distibution is configured to run in secure production mode. The server can easily be configured by creating the file ./conf/application-secure.properties with the following contents:

################################
#     SONG Server Config       #
################################

server.port=8080


################################
#     OAuth2 Server Config     #
################################

# Scope prefix used to authorize requests to the SONG server.
auth.server.prefix=collab

# Endpoint to validate OAuth2 tokens
auth.server.url=https://auth.icgc.org/oauth/check_token

auth.server.clientId=<auth-client-id>
auth.server.clientSecret=<auth-client-secret>


################################
#       ID Server Config       #
################################

# URL of the ID server
id.idUrl=https://id.icgc.org

# ID server auth token, which has id.create scope
id.authToken=<id-server-auth-token>

# Enabled to use an ID server. If false, will use
# and in-memory id server (use only for testing)
id.realIds=true

################################
#   Postgres Database Config   #
################################

spring.datasource.url=jdbc:postgresql://localhost:5432/song?stringtype=unspecified
spring.datasource.username=<my-db-username>
spring.datasource.password=<my-db-password>

################################
# SCORE Storage Server Config  #
################################

# URL used to ensure files exist in the storage server
# Note: The same SONG auth token will be used for requests sent
#       to the SCORE server. This means the same scope must be
#       authorized to access the SCORE storage service.
dcc-storage.url=https://storage.cancercollaboratory.org

The example file above configures the server to use the id.icgc.org id service, auth.icgc.org auth service, and the storage.cancercollaboratory.org SCORE storage service with a local Postgres database, however any similar service can be used. For example, the Docker for SONG Microservice Architecture uses a different implementation of an OAuth2 server.

Database

If the user chooses to host their own song server database, it can easily be setup with a few commands. Assuming postgresql was installed, the following instructions describe how to configure the schema and user roles for the song database using any linux user with sudo permissions:

  1. Create the song db as the user postgres.
sudo -u postgres -c "createdb song"
  1. Create the password for the postgres user.
sudo -u postgres psql postgres -c ‘ALTER USER postgres WITH PASSWORD ‘myNewPassword’;
  1. Download the desired release’s song-server jar archive. Refer to Official Releases for more information.
wget ‘https://artifacts.oicr.on.ca/artifactory/dcc-release/org/icgc/dcc/song-server/$VERSION/song-server-$VERSION.jar’ -O /tmp/song-server.jar
  1. Extract the schema.sql from the song-server jar archive.
unzip -p /tmp/song-server.jar  schema.sql > /tmp/schema.sql
  1. Load the schema.sql into the song db.
sudo -u postgres psql song < /tmp/schema.sql

Running as a Service

Although the SONG server distribution could be run as a standalone application, it must be manually started or stopped by the user. For a long-running server, sudden power loss or a hard reboot would mean the standalone application would need to be restarted manually. However, if the SONG server distribution is run as a service, the OS would be responsible for automatically restarting the service upon reboot. For this reason, the distibution should be configured as a service that is always started on boot.

Linux (SysV)

Assuming the directory path of the distribution is $SONG_SERVER_HOME, the following steps will register the SONG server as a SysV service on any Linux host supporting SysV and the Prerequisites, and configure it to start on boot.

# Register the SONG service
sudo ln -s $SONG_SERVER_HOME/bin/song-server /etc/init.d/song-server

# Start on boot (defaults)
sudo update-rc.d song-server defaults

It can also be manually managed using serveral commands:

# Start the service
sudo service song-server start

# Stop the service
sudo service song-server stop

# Restart the service
sudo service song-server restart