Running under Docker

If you have a system capable of running Docker, you can run Haplo as a pre-built container. This might be on a Linux server with Docker installed, or on a Mac or PC 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. On a server, register a name in DNS so that clients can connect to your server. This can either be the name of the server you’re going to install Haplo on, or an alias (CNAME). For example, if you want your Haplo installation to be available at the URL:

http://haplo.your.site.name/

then you need to create a DNS entry for haplo.your.site.name.

If you’re using a Mac, then edit /private/etc/hosts to add haplo.your.site.name as an alias for 127.0.0.1.

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.

APPURL="haplo.your.site.name"
APPNAME="Fred"
APPUNAME="Fred Bloggs"
APPUMAIL="fred@example.com"
APPUPASS="fred123"

The values required are:

APPURL
This is the address you use to connect to the server
APPNAME
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.
APPUNAME
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’.
APPUMAIL
And their email address, for example ‘fred.bloggs@example.com’.
APPUPASS
And then give a password for this user.

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

APPPLUGIN="hresrepodemo_application"

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.

Starting the container

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

http://haplo.your.site.name/

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.

Building the Docker image

If you’re interested in seeing how the Docker image is built, then you can look at the original source and Dockerfiles here: https://github.com/haplo-org/haplo-docker