Developer Installation guide

These instructions outline how to install Opencast. This is meant for developers. For the installation of a production cluster, take a look at the admin guides.

TL;DR

$ git clone https://github.com/opencast/opencast.git
$ cd opencast
$ mvn clean install -Pdev
$ cd build/opencast-dist-develop-*
$ ./bin/start-opencast

Opencast will then listen on 127.0.0.1:8080

Default credentials are:

Configuring Git

$ git config --global user.name "Example Name"
$ git config --global user.email [email protected]
$ ssh-keygen -t ed25519 -C "Example Name <[email protected]>"
$ cat ~/.ssh/id_ed25519.pub

Go to: Github, click "New SSH Key" and paste your content of id_rsa.pub into the input field. It should look like:

ssh-ed25519 at9/q0tR69TqQvwnFZuat90k0PY+z7mTyLB7UZXDnmpNHkU/MzO...

Now press "Add SSH Key" and return to your terminal and:

$ ssh -T [email protected]

Clone Opencast

You can get the Opencast source code by cloning the Git repository.

Cloning the Git repository:

$ git clone https://github.com/opencast/opencast.git

Install Dependencies

Please make sure to install the following dependencies.

Required:

java-1.8.0-openjdk-devel.x86_64 / openjdk-8-jdk (other jdk versions untested / Oracle JDK strongly not recommended)
elasticsearch = 7.5.1
ffmpeg >= 3.2.4
maven >= 3.1
python
firefox/chrome/some other major browser
unzip
gcc-c++
tar
bzip2

Required as a service for running Opencast:

ActiveMQ >= 5.10

Required for some services. Some tests may be skipped and some features may not be usable if they are not installed. Hence, it's generally a good idea to install them.

tesseract >= 3
hunspell >= 1.2.8
sox >= 14.4
synfig

Ubuntu 18.04

Update System

$ apt update
$ apt upgrade -y

Install Packages via APT

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

Install NodeJS (optional)

$ curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -
$ sudo apt-get install -y nodejs

Install and start Elasticsearch with Docker

$ docker run -d --rm --name oc-elasticsearch -p 9200:9200 -p 9300:9300 -e discovery.type=single-node elasticsearch:7.5.1

Note that --rm automatically removes the container when it exits, so if it does you will need to start it again in order to run opencast properly.

Set System Java JDK

Choose the Java Version 1.8.0 by entering:

$ update-alternatives --config java

Fedora

Update System

$ dnf update -y

Install Dependencies

$ dnf install https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm https://download1.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm -y
$ dnf group install 'Development Tools'
$ dnf install -y java-1.8.0-openjdk ffmpeg maven tesseract hunspell sox synfig unzip gcc-c++ tar bzip2 nodejs

macOS 10.14

Update System

Try to install all updates via the App Store or the Apple Icon on the top left corner.

Java JDK 8

Install the JDK 8 by downloading it from https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html

XCode

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 https://raw.githubusercontent.com/Homebrew/install/master/install)"

You can now install needed packages:

$ brew install maven ffmpeg nodejs

ActiveMQ with Homebrew

Homebrew offers you an ActiveMQ Package. Please decide, if you want to use Homebrew for ActiveMQ or if you want to follow the general guide below and run it by downloading the binaries. If you want continue you can install ActiveMQ by

$ brew install activemq

Remember to copy the activemq.xml like mentioned below in the right directory. You have to find the right folder for that operation, Homebrew will put the ActiveMQ files in a different location. You could find it by

$ sudo find / -name activemq.xml
````

After changing the configuration file you can list and start or stop you services with

```sh
$ brew services list
$ brew services start activemq

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

Install and Configure ActiveMQ

Download the current version from https://activemq.apache.org/components/classic/download

Extract and copy it to a directory, in this case you could use the opt directory.

$ sudo tar -zxvf apache-activemq-*-bin.tar.gz -C /opt
$ cd /opt && sudo mv apache-activemq-*/ activemq

Copy the preconfigured XML from your opencast directory into your ActiveMQ configuration. In this example you have following folder structure:

With that folder structure you could use following command:

$ cd && cd Projects && sudo cp opencast/docs/scripts/activemq/activemq.xml /opt/activemq/conf/activemq.xml

If your folder structure is different from that example or you do decide to put it somewhere else, you should copy and replace the preconfigured XML from

into

You can start your ActiveMQ instance with:

$ sudo ./location/to/your/activemq/bin/activemq start

Build and Start Opencast


You can build now opencast by changing your directory into your opencast location and by running:

$ mvn clean install

After the successfully compilation you can start opencast with:

$ cd build/opencast-dist-develop-*/bin && ./start-opencast

The -Pdev argument decreases the build time and skips the creation of multiple tarballs and turning on the developer tarball.

$ cd opencast && mvn clean install -Pdev
$ cd build/opencast-dist-develop-*/bin && ./start-opencast

For further information visit Development Environment.

Useful Commands for Testing Purposes

For a quick build, you can use the following command to skip Opencast's tests.

$ cd opencast
$ mvn clean install -Pdev -DskipTests=true

To see the whole stacktrace of the installation you can use the following command to disable the trimming.

$ cd opencast
$ mvn clean install -DtrimStackTrace=false

If you want to start opencast in debug mode, you could use the debug argument:

$ cd build/opencast-dist-develop-*/bin && ./start-opencast debug

Modify Code and Build Changes


After you modified your code you can go back to step "Build and Start Opencast" to rebuild Opencast.

Common Build Errors or Fixes


NPM Access Error

To fix an npm access error (example), you can run

$ sudo chown -R $USER:$(id -gn $USER) ~/.config && sudo chown -R $USER:$(id -gn $USER) ~/.npm

JDK Version

Some IDEs attempt to use the most recent version of the JDK. Make sure that your IDE is configured to use JDK 1.8.0.

Waiting for ActiveMQ

Opencast requires ActiveMQ to be both running and properly configured, otherwise it will wait forever to connect. See here for details on how to configure ActiveMQ. Make sure, that ActiveMQ runs without errors and with the right JAVA_HOME Variable (explained here).

Slow IDEA Fix

Edit following file

$ sudo nano /etc/sysctl.conf

and copy this text into it

fs.inotify.max_user_watches = 524288

Apply your changes with

$ sudo sysctl -p --system

Intellij Idea IDE Community Edition (optional)


If you are currently on Fedora, you can install it with following command. Make sure, that the versions match, you probably have to change it depending on the most current version.

$ cd && cd Downloads && wget https://download.jetbrains.com/idea/ideaIC-2019.2.tar.gz
$ sudo tar -zxvf ideaIC-*.tar.gz -C /opt
$ cd /opt && sudo mv idea-IC-*/ idea && sh /opt/idea/bin/idea.sh

Otherwise install it by downloading and following the manufacturer guide, select Community Edition:

IDEA Intellij Community Edition

Follow the next steps, if you want to import opencast correctly

Now Idea should import the projects, it could take some time, you can make it faster by following this.

Import the opencast code style configuration by following the steps

Now your IDE should be ready for developing.

Visual Studio Code Editor (optional)


If you are currently on Fedora, you can install it with

$ cd && cd Downloads && sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc && sudo sh -c 'echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com/yumrepos/vscode\nenabled=1\ngpgcheck=1\ngpgkey=https://packages.microsoft.com/keys/microsoft.asc" > /etc/yum.repos.d/vscode.repo' && dnf check-update && sudo dnf install code -y

Otherwise install it by downloading and following the manufacturer guide:

Visual Studio Code

After installation you can open a folder in bash with

$ code .

Recommended Extensions are