Development Environment Setup

Required Software

Java

The XCoLab is written in Java. You will need to install JDK 8 if you don't already have it, you can get it here.

MySQL

In order to run the XCoLab locally, you will need to install MySQL. If you're on macOS with homebrew, see below for instructions, otherwise see MySQL's getting started guide.

1. Install MySQL

   brew install mysql

   1.1 Check version

   ### MySQL >= 8.0
   mysqld --initialize-insecure --user=`whoami` --datadir=/usr/local/var/mysql --tmpdir=/tmp
   
   ### MySQL >= 5.6 && < 8
   mysql_install_db --verbose --user=`whoami` --basedir="$(brew --prefix mysql)" --datadir=/usr/local/var/mysql --tmpdir=/tmp

2. Make sure MySQL is running

   # Install the brew services utility
   brew tap homebrew/services
   
   # now you can start/stop/restart mysql easily (persists across restarts)
   brew services start mysql

If you are running Linux or Mac, make sure that you can connect to the database using your current user without superuser privileges (without using sudo).

Setup for Development

1. Clone the XCoLab GitHub repository: https://github.com/CCI-MIT/XCoLab.

2. Create a database that uses "utf8mb4 collation" encoding and specify a user:

   mysql -u root -e 'CREATE DATABASE xcolab CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;'

3. Copy the file conf/sample-application.properties ~/.xcolab.application.properties and edit it to match your local configuration for mysql:

   cp conf/sample-application.properties ~/.xcolab.application.properties
   

4. Compile the sources. This will also build the database schema. From the project root directory, run:

   ./mvnw compile
   

5. Populate the database with initial data. You can use our database starter scripts to get started with a new XCoLab instance:

   cat sql/starter/xcolab-data.sql | mysql -u root xcolab
   

Note: If you get an 'ErrorCode: 1067. Invalid default value for <timestamp field>' when creating the database schema, refer to the Common Pitfalls section.

Running a build and starting the servers

Using the command line

Note: our preferred way of working with the xCoLab is through an IDE, see the next section for more information.

1. You can build all artifacts by running ./mvnw package from the root directory of the repository.

2. You can find some utility scripts in the scripts/run folder. Make sure you run the scripts directly in that folder (cd scripts/run).

3. After compiling from source, you can copy the binaries from the various modules into a single folder by running ./copyBinaries.sh.

4. You can then start all servers by running ./startAll.sh in the root directory.

   Note: starting all servers will take a few minutes, but restarting only some of them will be much faster.

5. You can follow the progress by tailing all logs at once with this utility script: ./tailAll.sh

6. Once all servers are started (no more log output), you can access the site here: http://localhost:18082/

Using an IDE (preferred)

Instead of building and running the servers from the command line, we recommend you use an IDE. We use IntelliJ IDEA, so here's a guide how to work with it:

• Working with IntelliJ IDEA