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:
- Create the
song
db as the userpostgres
.
sudo -u postgres -c "createdb song"
- Create the password for the postgres user.
sudo -u postgres psql postgres -c ‘ALTER USER postgres WITH PASSWORD ‘myNewPassword’;
- 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
- Extract the schema.sql from the song-server jar archive.
unzip -p /tmp/song-server.jar schema.sql > /tmp/schema.sql
- 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