Developer Tips

Common Developer Pitfalls

Every development environment has its quirks, so here are a few which have been collected by the community:



Developer Builds

Besides the default dist Maven profile, the assemblies project defines a second dev profile which will cause only one allinone distribution to be created. It is already unpacked and ready to be started. Activate the profile using:

./mvnw clean install -Pdev

The administrative user interface needs nodejs to build and phantomjs for testing purposes. These will be downloaded as prebuilt binaries during the maven build process. If there are no prebuilt binaries for your operating system, you can build the tools manually and then build opencast using the frontend-no-prebuilt maven profile:

./mvnw clean install -Pdev,frontend-no-prebuilt

Logging During Builds

While building Opencast, the default log level for Opencast modules is WARN. To increase logging for development, edit the log level configuration in docs/log4j/

Building single modules

When working on a single Opencast module, it can be extremely helpful to watch the newly built version and include it automatically in the Opencast OSGi infrastructure. This can be done through the bundle:watch command in Karaf. The workflow would be as follows:

To see this technique in action, you can watch the following short video:

The updated bundles are only available in the currently running Karaf instance. To create a Opencast version that has this changes permanently, you have to run ./mvnw clean install in the the assemblies directory again. Your current instance will be deleted by the new assembly!

In several cases the bundle:watch can bring Karaf in an unstable condition, as dependencies between bundles will not correctly be restored, after the new bundle has been deployed.

Specific development environments tips

Ubuntu (Using JDK 11)

Update System

$ apt update
$ apt upgrade -y

Install Packages via APT

$ apt install -y git openjdk-11-jdk maven gcc g++ build-essential cmake curl sox hunspell synfig ffmpeg

Install NodeJS (optional)

$ curl -sL | sudo -E bash -
$ sudo apt-get install -y nodejs

Install and start Elasticsearch with Docker

You can use docker compose to easily run Elasticsearch:

$ cd docs/scripts/devel-dependency-containers
$ docker compose up -d

To shut the services down again, run:

$ cd docs/scripts/devel-dependency-containers
$ docker compose down

Set System Java JDK

Choose the Java Version 11 by entering:

$ update-alternatives --config java


Update System

Try to install all updates via the App Store or system settings.

Java JDK 11

Install the JDK 11 It's recommended to use SDKMAN to install and manage Java versions.


Install XCode over the App Store. It will be needed for building and for git.

Install Packages via Homebrew

The Homebrew Project adds a package manager to Mac OS. You can install it by:

$ /usr/bin/ruby -e "$(curl -fsSL"

You can now install needed packages:

$ brew install maven ffmpeg nodejs

Git Bash Completion

In macOS you can not complete or suggest half typed commands with your Tab Key (like you probably know from linux). If you want to use bash completion, you have to install it by:

$ brew install bash-completion

Find the location of the configuration file

$ sudo find / -type f -name "git-completion.bash"

Normally it should be in

$ cp /Library/Developer/CommandLineTools/usr/share/git-core/git-completion.bash /usr/local/etc/bash_completion.d/

Then add following line to the bash_profile in home

[ -f /usr/local/etc/bash_completion ] && . /usr/local/etc/bash_completion

Finally, apply your changes with

$ source /usr/local/etc/bash_completion.d/git-completion.bash