Build on Fedora 30

Download Fedora Server and install it on a system with at least 4GB of memory allocated. The instructions below are appropriate for Fedora 30, tested using a cloud image on AWS.

If you just want to run a Haplo server with a minimum of fuss, go straight to the Production server documentation.

Important: Do not include a dot in the hostname. A good hostname to choose would be haplo

Install required packages

After logging in, install packages with:

sudo dnf install gcc gcc-c++ patch
sudo dnf install java-1.8.0-openjdk java-1.8.0-openjdk-devel maven
sudo dnf install xapian-core-devel zlib-devel

Check the version of java with java -version. You must use Java 8, as older and newer versions aren’t compatible. If it’s not using Java 8, run sudo update-alternatives --config java to set the correct version.

Install PostgreSQL with:

sudo dnf install postgresql postgresql-contrib postgresql-server postgresql-server-devel libpq-devel

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.)

Setting up PostgreSQL

Create a database as the current user:

mkdir -p ~/haplo-dev-support/pg
initdb -E UTF8 -D ~/haplo-dev-support/pg

Running PostgreSQL for development and testing

Whenever you want to run the database, firstly, recreate the /var/run/postgresql directory, as /var/run gets wiped on every boot.

sudo mkdir -p /var/run/postgresql
sudo chmod a+rwx /var/run/postgresql

Then, leave the following command running in a terminal window:

postmaster -D ~/haplo-dev-support/pg

Open another terminal window now, before moving on to building Haplo.

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

Running the test suite

After ensuring PostgreSQL is running under the current user (see instructions above), run the test suite with:

script/test

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.

If more than one or two tests fail, your system doesn’t have enough memory.

Running the application in development mode

After ensuring PostgreSQL is running under the current user (see instructions above), initialise the database with:

db/init_dev_db.sh

You only need to do this once.

To run the Haplo server:

script/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" ben@example.com 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 echo command.

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.

Next steps

Click your user name in the top right, and choose “System management” to configure your application.

You may wish to try developing plugins with your development server.