CoinTossX <img align="right" width="200" src=".github/images/Logo.PNG">

Below are the instructions for deploying CoinTossX to a user's local machine or virtual machine in a cloud environment. These instructions apply to Windows, Linux and OSX operating systems. CoinTossX is a Java web application and is built using the Gradle build tool. The user need not install Gradle or change the version of Gradle installed on their system as the project uses the Gradle wrapper to download and run the required Gradle version. Currently CoinTossX is compatible with Java version 8 and Gradle version 6.7.1. The application can be started from the command line, however, it is recommended that the user make use of a Java IDE such as Eclipse or IntelliJ IDEA to automate the start-up process and simplify deployment.

Quick start

Prerequisites

JDK version 8 (see Installation section for more details)
A computer with 4 or more CPU cores and a sufficient amount of RAM (ideally 4 cores 32 GB but can be less depending on the number of clients and stocks used).
A Java IDE such as Eclipse or IntelliJ IDEA.
The user may be required to run commands using Command Prompt (Windows) or Bash (Linux and OSX).

Additional resources

Installation

If the correct version of Java is already installed and configured correctly, the user can skip step 1 below.

CoinTossX is currently only compatible with version 8 of Java. Therefore, the user should install version 8 of either the Oracle or Open JDK (Java Development Kit). Note that the user should install the JDK (which includes the JRE), not only the JRE. For simplicity, it is assumed that Windows and OSX users will install the Oracle JDK while Linux users will install the Open JDK.
- Windows - After installing Oracle JDK 8 using the link above, if not done so automatically by the java install wizard, ensure that JAVA_HOME is set and that the java executable is set in the path environment variable. To set/add java to the system's JAVA_HOME and path environment variables, go to Settings > Advanced System Settings > Environment Variables > System Variables. Then add the location of the java installation to a new variable called JAVA_HOME which points to the relevant java distribution (e.g. C:/Program Files/Java/jdk1.8.0_271). Thereafter append a new pointer in the path environment variable by adding %JAVA_HOME%/bin.
- Linux - Installation of Open JDK 8 is done by executing the commands below:
```
sudo apt-get update
sudo apt-get install openjdk-8-jdk
```
  After this, if the correct version of Java is still not being used, the user can switch to the correct version using
```
sudo update-alternatives --set java /usr/lib/jvm/jdk1.8.0_[version]/bin/java
```
- OSX - To set JAVA_HOME run
```
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.0_[version].jdk/Contents/Home
```
Clone the CoinTossX repository (using either git in the terminal or Github Desktop). The user can clone the repository to any location of their choosing.
```
cd [directory to clone into]
git clone https://github.com/dharmeshsing/CoinTossX.git
```
The next set of instructions provides guidelines for the deployment of CoinTossX.
By this point the user will have cloned the repository to a location of their choosing for either local or remote deployment. Depending on the operating system, different deployment configurations would need to be employed - hence the multiple configuration and deployment files. The files with the .properties extensions define the required ports for each component as well as user specific path definitions. To match the location to which the repository was cloned, the user would have to configure the local.properties file (for Linux) or the windows.properties file (for Windows) to correspond with the user's directories. For remote deployment the user would have to configure the remote.properties with the corresponding paths on the remote server. The path variables which need to be configured are:
- MEDIA_DRIVER_DIR pointing to the Aeron Media Driver. This folder will only be created after the application is started. For Linux users it is recommended that the default path (/dev/shm) is not deviated from in order to achieve optimal performance. Otherwise the path can be amended as follows:
```
MEDIA_DRIVER_DIR=[...]/aeron
```
  Note that if the user deviates from the default media driver path, they would have to make the same change in the build.gradle file.
- SOFTWARE_PATH pointing to the start-up folder that will be created upon deployment. This path can be set to any valid path on the user's machine and may be given any name. For example:
```
SOFTWARE_PATH=[...]/[folder name]
```
- DATA_PATH points to the data folder within the software path. For example:
```
DATA_PATH=[SOFTWARE_PATH]/data
```
Before the application can be started, we are required to change a few system settings to ensure that network performance and system memory are utilised correctly. Firstly, the receive and send UDP buffer sizes/limits need to be configured as follows:
```
sudo sysctl net.core.rmem_max=2097152
sudo sysctl net.core.wmem_max=2097152
```
Secondly, this Java application requires large pages to be enabled. By default Linux does not enable any HugePages (portions of memory set aside to be solely used by the application). To determine the current HugePage usage, run grep Huge /proc/meminfo. Furthermore, the default HugePage size is 2MB (2048kB). So if the user wishes to enable approximately 20GB of HugePages (dedicated memory), this would require 10000 HugePages - so the command to run would be
```
sudo sysctl vm.nr_hugepages=10000
```
Last is the running of the application. Users deploying the application to Microsoft Azure, CHPC, Wits Server or any other server may choose to do so locally or remotely. Remote deployment will require that the user specify the above paths to correspond with that of the remote server. The instructions below demonstrate both local and remote deployment. For users deploying remotely, one must first ensure that SSH is enabled on the server and that port 22 is open for the transfer of files. Additionally, the username, IP address and password fields in the deploy_remote.gradle file should match that of the server.
1. Set the current directory to the location of CoinTossX:
```
cd [path to]/CoinTossX
```
2. To build the project, use the provided gradle wrapper to run:
```
./gradlew -Penv=local build -x test # For local deployment
./gradlew -Penv=remote build -x test # For remote deployment
./gradlew.bat -Penv=windows build -x test # For windows deployment
```
3. To deploy the project to a start-up folder, execute one of the following.
```
./gradlew -Penv=local clean installDist bootWar copyResourcesToInstallDir copyToDeploy deployLocal # For local deployment
./gradlew -Penv=remote clean installDist bootWar copyResourcesToInstallDir copyToDeploy deployRemote # For remote deployment
./gradlew.bat -Penv=windows clean installDist bootWar copyResourcesToInstallDir copyToDeploy deployLocal # For windows deployment
```
4. Finally, to run the program, execute the shell script:
```
sh [SOFTWARE_PATH]/scripts/startAll.sh
```
5. Access the web app by typing localhost:8080 (if deployed locally) or [server IP]:8080 (if deployed remotely) into the URL search bar of a browser.

Usage

To configure the trading sessions to be fired during the simulation refer to the data/tradingSessionsCron.properties file. The usage/syntax of the cron expressions within that file are as follows. A cron expression is a string consisting of six or seven fields, separated by white space, that describe individual details of the schedule:

[seconds] [minutes] [hours] [day of month] [month] [day of week] [year]

A few examples, provided in data/tradingSessionsCron.properties, are shown below.

TRADING_SESSIONS=ContinuousTrading2

#StartOfTrading.name=ContinuousTrading
#StartOfTrading.cron=0 0 7 * * 1-7

#ContinuousTrading.name=ContinuousTrading
#Continuous

CoinTossX

Install / Use

README