Running under Docker Desktop on a Mac

You can run Haplo as a pre-built container locally on a Mac using Docker Desktop.

Pre-install planning

You need to create a location for persistent storage. Because containers are stateless, the data has to live outside the image. For example,

mkdir ~/haplo-data

You will need to decide on the name you’re going to use for your Haplo installation. For example, if you want your Haplo installation to be available at the URL:

then you need to edit /private/etc/hosts to add as an alias for

This name will also be used in the configuration file below.

Seeding the configuration

In the location for persistent storage you created above, create a file called app.values that looks like the following, defining the five settings required to bootstrap the installation.

APPUNAME="Fred Bloggs"

The values required are:

This is the address you use to connect to the server
This is the name that will be displayed on all the pages of your Haplo installation. It should reflect the name of your department or organization, or the function of this Haplo installation.
You need to create at least one user, so you will be asked for their details. This should be their full name, for example ‘Fred Bloggs’.
And their email address, for example ‘’.
And then give a password for this user.

There is an additional value you can set, which is optional.


If this is set, then the application will have the specified plugin installed. If unset, you’ll get a basic uncustomized Haplo application. At the present time, the only valid value is “hresrepodemo_application”, which will cause a demonstration Academic Repository to be created.

With the initial configuration ready, run the Haplo Docker image. You need to map network ports and the persistent storage.

docker run -p 80:8080 -p 443:8443 -v ~/haplo-data:/haplo haploorg/haplo-app

This will download the Haplo image, map the network ports 80 (for http) and 443 (for https), and mount your persistent storage in the correct place inside the container.

The first time you run the container, it will take a little while to populate the database, create a self-signed certificate, set up an application, and start the application server. You can then go to

in your web browser and log in using the email address and password details you put in the configuration. (You will get a security warning from your web browser due to the use of a self-signed certificate.)

Subsequent runs of the container will just load the data from the persistent storage, and won’t need the initialization step. Once configured, you can go and delete the app.values file.