View on GitHub


Setting Up an Equella Dev Environment

Download required software

Download and install Git

In ubuntu:

~$ sudo apt-get install git


This guide assumes you have SSH capabilities. Be sure to add your public SSH key into the you git profile to access the code repos.

Download and install SBT

In ubuntu:

~$ echo "deb /" | sudo tee -a /etc/apt/sources.list.d/sbt.list
~$ sudo apt-key adv --keyserver hkp:// --recv 2EE0EA64E40A89B84B2DF73499E82A75642AC823
~$ sudo apt-get update
~$ sudo apt-get install sbt

Download and install Java 8 JDK

Oracle is the recommended and historically the supported vendor of Java to run Equella with.

In ubuntu:

~$ sudo add-apt-repository ppa:webupd8team/java
~$ sudo apt-get update
~$ sudo apt-get install oracle-java8-installer

Download and install Image Magick binaries

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

To confirm the installation directory in Ubuntu for the Equella installer, run the command:

~$ whereis convert

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

Download and install libav

In ubuntu:

~$ sudo apt-get install libav-tools

To confirm the installation directory in Ubuntu for the Equella installer, run the command:

~$ whereis avconv

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


Get the code

Maven Local

_NOTE: Currently the build process requires a ‘local maven’ repo of ‘equella-deps’ that is not yet available to the community. We are preparing those dependencies to be available to the community and the work should be completed soon._

Pull down the maven local repo ‘equella-deps’ and place it in your home directory.

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

This guide runs sbt in non-interactive mode. You can run in interactive mode to save rebuild time by first running ‘sbt’, and the another command such as ‘compile’.

cd to the {Equella repo} directory
~$ sbt compile

Equella Configuration

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

For the plugins folder in learningedge-config, you can pull an example from an existing Equella install of the same version or build it yourself. The directory tree should look like the following, rooted in « dev equella config »/learningedge-config/plugins/:


The contents of the files:


# Synchronisation Timer. The number of minutes between synchronisation attempts.
#freetextIndex.synchroiseMinutes = 5

# Index item attachments (defaults to true)
#textExtracter.indexAttachments = true

# Index IMS package contents (defaults to true)
#textExtracter.indexImsPackages = true

# Indicates if default search terms should be performed with an implicit AND or OR.
# Defaults to AND
#freetextIndex.defaultOperator = AND


# ImageMagick is a set of different programs, and EQUELLA needs to know the directory that
# contains these programs.  For example, running 'which convert' on a unix-like system may
# return '/usr/bin/convert' so you should enter '/usr/bin'.  On a Windows system, you may
# have installed to 'C:\ImageMagick6.4', then the programs can be found directly inside that
# path.

imageMagick.path = /usr/bin


# Auditing level can be one of NONE, NORMAL or SMART.
#   NONE
#      No audit trail
#      Logs the every viewing of an item summary page or downloading of an attachment.
#      This setting may create a very large number of audit log entries.
#      Logs the viewing of an item or it's attachments only once per user session.
#      This setting will increase the amount of memory required for each user session.
audit.level = NONE


# Tile after contribution mode. Specifies how images should be handled
# after contribution.  Valid values are AUTO_TILE_AFTER_CONTRIBUTION, 

#tileAfterContribution.mode = PROMPT_AFTER_CONTRIBUTION

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 (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:


if you get a deduplicate dependencies on commons logging, SLF4J has a moonlighting jar that says it’s commons logging. Use the build.sbt directive of exclude dependencies like the adminConsole does.

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 = []


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.