Download Ubuntu Server LTS and install it in a VM with at least 4GB of memory allocated. The instructions below are appropriate for Ubuntu 16.04 LTS. If you’re still using the older Ubuntu 14.04 LTS release, then you should use these alternative build instructions.
Important: Do not include a dot in the hostname. A good hostname to choose would be
You’ll probably want to install openssh to allow you to log in from the VM host.
sudo apt-get install openssh-server
After logging in, install packages with:
sudo apt-get install software-properties-common sudo apt-get update sudo apt-get install g++ make openjdk-8-jdk maven avahi-daemon uuid-dev curl patch git libxapian22v5
Check the version of java with
java -version. If it’s not using Java 8, run
sudo update-alternatives --config java to set the correct version.
Install PostgreSQL 9.5 with:
sudo apt-get install postgresql-9.5 postgresql-server-dev-9.5 postgresql-contrib-9.5
This will initialise and run the PostgreSQL server. However, when testing and developing Haplo, you need to run PostgreSQL as the same user as the Haplo process. (In deployment, PostgreSQL runs under a different user.)
Disable the PostgreSQL daemon and allow the current user to run the server with:
sudo /etc/init.d/postgresql stop sudo update-rc.d postgresql disable
Create a database as the current user:
mkdir -p ~/haplo-dev-support/pg /usr/lib/postgresql/9.5/bin/initdb -E UTF8 -D ~/haplo-dev-support/pg
Whenever you want to run the database, firstly, recreate the
/var/run/postgresql directory, as
/var/run gets wiped on every boot.
sudo mkdir /var/run/postgresql sudo chmod a+rwx /var/run/postgresql
Then, leave the following command running in a terminal window:
/usr/lib/postgresql/9.5/bin/postmaster -D ~/haplo-dev-support/pg
Open another terminal window now, before moving on to building Haplo.
Check out the repository from GitHub, for example, with:
cd ~ git clone https://github.com/haplo-org/haplo.git
Within the repository checkout, run the
fetch-and-compile.sh script. This will download about 110MB of archives, and create a
haplo-dev-support directory in your home directory.
cd ~/haplo ./fetch-and-compile.sh
After ensuring PostgreSQL is running under the current user (see instructions above), run the test suite with:
If you see something like
'ERROR: could not access file ".../xapian_pg/oxp": Permission denied' then you are not running postgres as the same user as the test process.
You should expect a few tests to fail due to platform differences between our production environment and Linux. If lots of tests fail, you haven’t allocated enough memory to the VM.
After ensuring PostgreSQL is running under the current user (see instructions above), initialise the database with:
You only need to do this once.
To run the Haplo server:
Haplo runs as a multi-tenant application server, so before we can log into the server, we need to create an application.
In another terminal window:
cd ~/haplo db/init_app.sh haplo test.`hostname`.local "Test application" sme 4000 db/create_app_user.sh test.`hostname`.local "Ben Summers" firstname.lastname@example.org password echo Visit http://test.`hostname`.local:8080 in your browser.
The Haplo server will use multicast DNS to broadcast the hostname for the application, so a web browser on the machine on which the VM is running should be able to connect to the server on the address printed by the
You need to make sure your host OS can resolve multicast DNS:
Mac OS X: Supports multicast DNS out of the box.
Linux: Ensure the
avahi-daemon package is installed on the host OS.
Windows: There isn’t a good multicast DNS implementation for Windows. Find the IP address of the VM by running
ipconfig -a in the VM, then add the application hostnames to the
C:\Windows\System32\Drivers\etc\hosts file on the Windows host.
The development configuration uses a self-signed SSL certificate, so you’ll get a warning in your browser about the certificate.
Log into the application using the email address and password given on the third line above.
Click your user name in the top right, and choose “System management” to configure your application.
Then, develop a Haplo plugin.