Development Environment Setup

Johannes Bachhuber edited this page Aug 26, 2018 · 75 revisions

Required Software


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.


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:

  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/ ~/ and edit it to match your local configuration for mysql:

    cp conf/ ~/
  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 ./

  4. You can then start all servers by running ./ 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: ./

  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:

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.