Platform » Development build » macOS

Build on macOS

We recommend you use an Ubuntu VM on your Mac, as macOS is a bit of a moving target. However, with a bit of work, it is possible to run Haplo on macOS directly.

You need a recent version of macOS with Xcode or the command line development tools installed. If you haven’t got either installed yet, install the latter with

xcode-select --install

Then install Java 8 and Maven.

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, use /usr/libexec/java_home to set the appropriate PATH.

Use the current version of Maven, such as 3.5.4 or later.

Install PostgreSQL

Download a recent version of PostgreSQL Enterprise DB (we suggest version 10).

Install it with all the defaults, so it installs at /Library/PostgreSQL/10

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
/Library/PostgreSQL/10/bin/initdb -E UTF8 -D ~/haplo-dev-support/pg

Important: You need to make sure that the PostgreSQL bin directory is in your path, for example, by adding the following to your ~/.profile file.

export PATH=/Library/PostgreSQL/10/bin:$PATH

Running PostgreSQL for development and testing

Whenever you want to run the database, leave the following command running in a terminal window:

sudo launchctl stop com.edb.launchd.postgresql-10
/Library/PostgreSQL/10/bin/postmaster -D ~/haplo-dev-support/pg

Open another terminal window so you can leave it running now.

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.

You should expect a few tests to fail due to platform differences between our production environment and macOS. If lots of tests fail, you haven’t got enough free 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` "Test application" sme 4000
db/create_app_user.sh test.`hostname` "Ben Summers" ben@example.com password
echo Visit http://test.`hostname`:8080 in your browser.

The Haplo server will use multicast DNS to broadcast the hostname for the application, so a web browser on your Mac will be able to connect to the server on the address printed by the echo command.

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.