Installation Guide

Development Environment

The first thing a developer will need to do is to setup the development environment. It is common for developers to be working in different environments (Windows, Linux, Mac OS etc..) especially on open source projects and distributed teams. In order to set up a development environment which typically would involve installing softwares like Java, MySQL, tomcat, PHP etc, it can take up anywhere from hours to days depending on what all is required. 

To minimize the effort and to ensure every developer is working with the same software versions (i.e development environment), SCSB uses Docker Containers.

Prerequisites

Docker

In order to install Docker, please visit https://docs.docker.com and follow the instructions available there for the relevant Operating System.

Github

Please visit https://github.com/ and create a new account.

Getting Started

Fork ReCAP SCSB Repository

The main repo is at https://github.com/ResearchCollectionsAndPreservation/docker.git
Once forked, clone the repository onto your local machine by following the steps below;

1. Create a directory in your file system using the below command:

   mkdir recap-middleware

2. Clone the repository onto your loca machine using the git clone command:

   git clone https://github.com/**username**/docker.git

Once the repository has been downloaded, change directory into that location. You will find a folder called docker, change directory to docker.

cd docker

Steps to build docker image and run docker container

Under the docker folder, the user will find the following folders. Each folder represents a separate container and will need to be built and initiated manually by the user. The below paragraphs would deal on the commands that are to be used along side the file location where these needs to be used.

scsb-mysql

This directory, as the name suggests, holds the MySQL instance and the SQL scripts that are to be run as part of setting up the database and the relevant tables. This will have the docker file, config file and script files. The below steps help in building the image and running the container resulting in a MySQL instance persisting data for SCSB application.

• Change directory into the scsb-mysql folder.

  cd scsb-mysql

• Use the sudo docker build command to build docker images. (Do note the dot (.) at the end of the command).

  sudo docker build -t scsb-mysql .
  `# where, -t would set a name for the image, here scsb-mysql ` \

• Use the sudo docker run command to run docker container.

  sudo docker run --name scsb-mysql -v /data/mysql-dev-data:/var/lib/mysql -p 3306:3306 -d scsb-mysql
  `# where,	--name would set a name for the container ` \
  `#			-v would bind an external volume to the docker container. That way even if we remove and recreate the container we can retain old data `\
  `#			-p publishes a container's port to the host ` \
  `#			-d daemon mode ` \

Executing the above commands will create an image and run the container resulting in a MySQL instance running on 3306 port. 

scsb-activemq

This directory holds the activemq instance that handles the queues to and from SCSB application. This will have the docker file and config files to build docker image. The below steps help in building the image and running the container that would help activemq handle the queues.

• Return to the main docker folder

  cd ..

• Change directory to scsb-activemq

  cd scsb-activemq

• Use the sudo docker build command to build docker images. (Do note the dot (.) at the end of the command).

  sudo docker build -t scsb-activemq .

• Use the sudo docker run command to run docker container.

  sudo docker run --name scsb-activemq -v /data/activemq-dev-data:/opt/activemq/data -p 8161:8161 -p 61616:61616 -p 1099:1099 -e "DB_URL=jdbc:mysql://localhost:3306/recapactivemq?relaxAutoCommit=true" -e "DB_USERNAME=recap" -e "DB_PASSWORD=recap" -e "USERS=admin: admin, admin" -d scsb-activemq

Executing the above commands will create an image and run the container resulting in an activemq instance accessible on port 8161, 61616 and 1099. 8161 is for administration, 61616 is tcp and 1099 is STOMP.

scsb-solr-server

This directory holds the solr server instance that holds solr indexed data from SCSB. This will have the docker file and script file to build docker image. The below steps help in building the image and running the container that would host the solr server that will handle the solr indexed SCSB data.

• Return to the main docker folder

  cd ..

• Change directory to scsb-solr-server

  cd scsb-solr-server

• Use the sudo docker build command to build docker images. (Do note the dot (.) at the end of the command).

  sudo docker build -t scsb-solr-server .

• Use the sudo docker run command to run docker container.

  sudo docker run --name scsb-solr-server -v /data/solr-data:/var/data/solr -p 8983:8983 -d scsb-solr-server -e "ENV=-m 4g"

Executing the above commands will create image and run the container resulting in a solr server instance running on port 8983.

scsb-solr-client

This directory holds the solr client instance that would help in accessing the solr indexed data from SCSB. This will have the docker file and script file to build docker image. The below steps help in building the image and running the container that would host the solr client that will help in retrieving data from the solr server.

• Return to the main docker folder

  cd ..

• Change directory to scsb-solr-client

  cd scsb-solr-client

• Use the sudo docker build command to build docker images. (Do note the dot (.) at the end of the command).

  sudo docker build -t scsb-solr-client .

• Use the sudo docker run command to run docker container.

  sudo docker run --name scsb-solr-client --link scsb-mysql:scsb-mysql --link scsb-solr-server:scsb-solr-server --link scsb-activemq:scsb-activemq -v /data:/recap-vol -p 9090:9090 -e "ENV=-XX:+HeapDumpOnOutOfMemoryError -Dorg.apache.activemq.SERIALIZABLE_PACKAGES="" -Dspring.profiles.active=local-container -Dspring.config.location=/recap-vol/config/application.properties" -d scsb-solr-client
  `# where,   --link add link to another container. Application will communicate between these containers. Make sure that scsb-mysql, scsb-activemq and scsb-solr-server containers are running.` \
  `#          -e set environment variables ` \
  `#          -D denotes system parameter -Dspring.profiles.active=local-container -> This will pick the local-container property file while starting the application. -Dspring.config.location=/recap-vol/config/application.properties -> This is the external properties which will have the confidential informations. Need to create application.properties file under /data/config/ directory and that new file should have properties which are specified in External Properties link with proper informations. ` \

Executing the above commands will create image and run container running in a solr client application running on port 9090.

scsb

This directory holds the scsb project and will have the docker file and script file to build docker image. The below steps help in building the image and running the container that would host the scsb project.

• Return to the main docker folder

  cd ..

• Change directory to scsb

  cd scsb

• Use the sudo docker build command to build docker images. (Do note the dot (.) at the end of the command).

  sudo docker build -t scsb-scsb .

• Use the sudo docker run command to run docker container.

  sudo docker run --name scsb --link scsb-mysql:scsb-mysql --link scsb-activemq:scsb-activemq --link scsb-solr-client:scsb-solr-client -v /data:/recap-vol -p 9093:9093 -e "ENV=-XX:+HeapDumpOnOutOfMemoryError -Dspring.profiles.active=local-container -Dspring.config.location=/recap-vol/config/application.properties -Djsse.enableSNIExtension=false -Dorg.apache.activemq.SERIALIZABLE_PACKAGES=""" -d scsb

Executing the above commands will create the image and run the container resulting in the scsb application running on port 9093.

scsb-shiro

This directory holds the shiro project that will help in authentication and authorization of requests into SCSB. This will have the docker file and script file to build docker image. The below steps help in building the image and running the container that would host the shiro module.

• Return to the main docker folder

  cd ..

• Change directory to scsb-shiro

  cd scsb-shiro

• Use the sudo docker build command to build docker images. (Do note the dot (.) at the end of the command).

  sudo docker build -t scsb-shiro .

• Use the sudo docker run command to run docker container.

  sudo docker run --name scsb-shiro --link scsb-mysql:scsb-mysql --link scsb:scsb -v /data:/recap-vol -p 9092:9092 -e "ENV=-XX:+HeapDumpOnOutOfMemoryError -Dspring.profiles.active=local-container -Dspring.config.location=/recap-vol/config/application.properties" -d scsb-shiro

Executing the above commands will create an image and run the container resulting in SCSB Shiro application running on port 9092.

scsb-ui

This directory holds the UI module of the SCSB project and will have the docker file and script file to build docker image. The below steps help in building the image and running the container that would host the UI module.

• Return to the main docker folder

  cd ..

• Change directory to scsb-ui

  cd scsb-ui

• Use the sudo docker build command to build docker images. (Do note the dot (.) at the end of the command).

  sudo docker build -t scsb-ui .

• Use the sudo docker run command to run docker container.

  sudo docker run --name scsb-ui --link scsb-mysql:scsb-mysql --link scsb:scsb --link scsb-shiro:scsb-shiro -v /data:/recap-vol -p 9091:9091 -e "ENV=-XX:+HeapDumpOnOutOfMemoryError -Dspring.profiles.active=local-container -Dspring.config.location=/recap-vol/config/application.properties" -d scsb-ui

These above commands will create an image and run the container resulting in the scsb-ui application running on port 9091.