View on GitHub


Setting Up an Equella Dev Environment

Download required software

Download and install Git

Download and install SBT

Download and install Java 8 JDK

Download and install Image Magick binaries

Note: For ubuntu follow the install from Unix Source instructions:

They are installed in /usr/local/lib

When installing in Windows, check “Install Legacy Utilities (e.g. convert)”.

Download and install libav

In ubuntu:

sudo apt-get install libav-tools

They are installed in /usr/lib

Once SBT and Java are installed, you may need to set a JAVA_HOME environment variable.


Get the code

Base code

Git Clone

git clone

Optional code

There is functionality that could not be included into the core Equella code repository, but based on your business needs, may be appropriate to include.

Build configuration

Some aspects of the build can be configured by editing the build.conf file.


A keystore with a certificate is required to sign some of the jars in order for them to escape the Java sandbox.

By default the build will generate a self signed key which will show security warnings when launching. In order to prevent this you will need to have a properly signed certificate and configure the build to use it. In the build.conf file you can modify the parameters to configure your own keystore:

signer {
  keystore = "/path/to/.keystore"
  storePassword = "<storepasswd>"
  keyPassword = "<optional>" # defaults to storePassword
  alias = "<keyalias>"

IMPORTANT: A self registered certificate implies that the jars won’t be secured and a security exception will appear when trying to launch the jars. To avoid this it is needed to add the domain you want to trust as a security exception in your java configuration. It can be done with the Java Control Panel or directly adding the domain in a new line in this file: ${user.home}/.java/deployment/security/exception.sites

Building the code

cd to the {Equella repo}/ directory
sbt compile

Equella Configuration

Under the {Equella repo}/Dev/learningedge-config folder, you’ll need several artifacts:

Running a dev instance

Ensure you have your Dev/learningedge-config setup. See Equella Configuration.

sbt compile equellaserver/run

Running a dev instance of the admin tool

Ensure you have your Dev/learningedge-config setup. See Equella Configuration.

sbt compile adminTool/run

Installation of the Vanilla institution

Really any instituion is sufficient. Under the ‘Installing Equella’ page, there is a guide to a ‘Vanilla’ institution that would be suitable for a development environment.

SBT Notes

The new build uses SBT which is a build tool which is very flexible and has a large set of useful plugins available. You can customize pretty much any aspect of your build process using Scala scripts.

Plugins are global to the build but can be turned on/off on a per project basis.

The root build is located in the following files:

Located in the “project” folder is a series of SBT AutoPlugins which are responsible for replicating some of what the ant build used to do:

The root plugin manually defines the sub-project location and their inter-project dependencies:


Building Equella with SBT does not require an IDE to run, and while not a particular IDE is not recommended / required, IntelliJ has been proven to work with the Equella SBT build process.

Due to the enourmous number of projects, when importing into IntelliJ the required memory usage will be higher than the default, so you’ll probably need to increase the memory (Help -> Edit custom VM Options...)

You will also need to increase the default maximum memory allocation for SBT when doing the import: (Build Tools -> SBT -> Maximum Heap size)

4096MB should be enough.

Speeding up the build during dev

If you are editing the build files you can temporarily disable all the non-essential plugins to speed up your dev/reload/test process by editing (or creating) the project/build.conf file to have the setting:

plugin.whitelist = []