< Back to blog page

Setting up Valamis from GitHub

Valamis is a powerful open source learning solution which gives you a collection of tools to construct various eLearning sites to serve different kind of needs. As a simplified example: you could create a site, where users with teacher role can create courses including lessons and quizes, and users with student role can attend these courses and earn certificates. If you would like to know more about the product itself, I suggest you to visit "What is Learning eXperience Platform" page for detailed information.

Valamis runs on Liferay and up until recently the CE version was available from the Liferay Marketplace. However, from version 2.2 upwards, it is only available from GitHub as a source code. The aim of this article is to help brave developers on their journey of setting up a working Valamis environment from that code. I will explain what you should do, how and in what order. In the end, you will have a working Valamis instance.

Keep in mind that many paths lead to that destination. I will describe only one in detail, but you may get the correct directions even if you don't follow it precisely. Let's state upfront that my operation system is Ubuntu 14.04, so if you happen to use windows or mac, you may have to look up the exact commands for yourself.

Installing the supporting tools

These are the collection of items that you must need in order to succeed on your journey.

Java Development kit

This one is quite obvious and if you have ever worked with Liferay, you probably have it already. Since Liferay doesn't have an official support for Java 8, Valamis doesn't have either. You can experience with it, but if you want play safe I suggest the oracle version of Java 7.

Here is an easy way to install it from the command line on Ubuntu, but on the Oracle's website, you can find versions for all kinds of operation systems.

Validate your installation with java -version.

You should see something like this:

java version "1.7.0_71"
Java(TM) SE Runtime Environment (build 1.7.0_71-b14)
Java HotSpot(TM) 64-Bit Server VM (build 24.71-b01, mixed mode)


This is a commonly used build tool for projects written in the wonderful language of Scala, such as Valamis. You can find detailed instruction about its installation here.

Validate your installation with sbt sbtVersion
You will see several lines, but among them, you should see this:

[info] 0.13.8

After you have installed SBT, you should configure it in order to access some repositories that you will need during the later builds. Find the SBT's folder (on Ubuntu, it is ~/.sbt) and create a file named repositories with the following content:

typesafe-snapshots: https://repo.typesafe.com/typesafe/snapshots/
typesafe-releases: https://repo.typesafe.com/typesafe/releases/

Setting up local Liferay enviroment

I guess this won't need much explanation, but I'll roughly go through it.

1. Download Liferay CE
The latest release can be found from its website. Valamis should support the latest version, but you might want make sure before continuing. Check the supported version here.

2. Set up a database
Probably everybody has a good old way to do this. I use PostgreSQL on Ubuntu, so I just type in these two lines:

sudo -u postgres createuser -SPRD "username"
sudo -u postgres createdb --owner "username" "databasename"

Note: If you don't have any database system installed, but you are using Ubuntu, type in this to install PostgreSQL:

sudo apt-get install postgresql postgresql-contrib

If you are really into installing, you might as well install pgAdmin III, a useful GUI tool for your new PostgreSQL:

sudo apt-get install pgadmin3

3. Unpack your Liferay and configure the webserver
Valamis uses a lot of memory and PermGen space, so I recommend setting their limit to a high enough level. The default tomcat settings are not enough. Go to the liferay-xxx/tomcat-xxx/bin folder, and modify the setenv.sh (or setenv.bat, if you use windows) so the following part will look like this:

Xmx2048m -XX:MaxPermSize=512m

If you use other webserver, check its default settings and increase it, if needed.

4. Start your Liferay
If you are in the tomcat folder, you could type in the following line:

bin/startup.sh && tail -f logs/catalina.out

This will start the Liferay and monitors the server-log afterwards. When the browser opens with the start-up page, don't forget to configure your database there.

Getting the Valamis source code

Now, its time to download the source code from GitHub. You will need two different things: the Valamis portlets, and a Learning Record Store (If you don't have one already.)

    •    GitHub page: https://github.com/arcusys/Valamis
    •    git clone url: https://github.com/arcusys/Valamis.git
    •    zip download: https://github.com/arcusys/Valamis/archive/master.zip
Valamis Learning Record Store:

    •    GitHub page: https://github.com/arcusys/valamis-lrs
    •    git clone url: https://github.com/arcusys/valamis-lrs.git
    •    zip download: https://github.com/arcusys/valamis-lrs/archive/master.zip
If you have a GitHub account, you can simply execute the following commands once you are in the folder where you would like to download the code:

git clone https://github.com/arcusys/Valamis.git
git clone https://github.com/arcusys/valamis-lrs.git

If you don't have a GitHub account, or you don't even use git, you can use the zip downloads and extract them into an appropriate folder.

Building and deploying the portlets

Navigate into the freshly acquired Valamis folder and build the project with SBT. You could type in sbt tasks to see the available tasks for the project, but for now sbt clean package will do the job.
The build will generate two deployable war files:


You will need only the learn-portlet. Copy it into your Liferay's deploy folder, and it should deploy smoothly.
At this point, you can access the Valamis portlets in Liferay, but you may notice that few of them actually works. This is because they need a learning record store (LRS) in order to operate correctly.
If you have your own LRS, go to the Site-administration ⇒ Content ⇒ Valamis Administration ⇒ Tincan settings to configure it. If you don't have or even know, what is LRS, leave the settings on default, and deploy the Valamis LRS.

Building and deploying the Learning Record Store

The process is similar to portlet's case. Navigate into your valamis-lrs folder, and execute the sbt clean package, than copy the created ...valamis-lrs-liferay/target/scala-2.10/valamis-lrs-portlet.war file into your Liferay's deploy folder.
Thus ends your journey of setting up Valamis. Or does it?!

Hook and Theme

You may have noticed the hook file that has been created along with the portlet. That hook is currently unsupported by the free source code release, it is just happens to be in it. If you try to deploy it, you will notice that it expects EE Liferay version (6.2.10+). If you solve this problem, you will hit another barrier: you need the valamis-theme to be deployed before you can deploy the hook, and you don't have that theme. Cunning developers might find out, that it can be acquired from the marketplace's older Valamis version, but don't bother with it. The hook currently doesn't contain any important code, and if it will in the future, you will be able to use it without any hacking.

Suggested IDE

The obvious choice would be something, that has a nice support for Scala and SBT. You could try the Scala IDE for Eclipse, but my ultimate choice is the newest (14+) IntelliJ IDEA with the Scala plug-in.

Zsolt Berki
Software Developer

Next: Cutting edge solution for solving regulatory compliance
Prev: Install and configure Open edX with Valamis