On-Prem: Hosting guide

This article relates to the latest On-Premises installation of Haiilo.

1. Introduction

Welcome to your new digital home: Haiilo!

This document gives you as system administrators some fundamental information about hosting Haiilo yourself, the system requirements, Docker itself, and how we use application virtualization. You’ll also get some introductory information about backups, updates, user directory, user authentication, and our REST API.

Everything is supplied with helpful links to our knowledge database and documentation.

We hope to be able to answer all of your questions about hosting Haiilo and the functioning behind it, and recommend you make notes if anything is unclear.

2. System requirements 

2.1 Requirements on the server software

Haiilo can be used wherever Docker Compose is also executable. This is currently Linux and Mac OS, but we only recommend the Linux distributions. We have had good experience with Ubuntu, Debian, RedHat, SLES, and CentOS.

Windows Server is not possible due to a lack of components. 

2.2 Requirements on the server hardware

Our minimum requirements on the hardware for an individual host are based on the number of regular users on your Haiilo. 


If you want to run the optional metrics stack (start-advanced.sh) to gather data like CPU load, RAM usage and backend insights, you would need 10 GB of additional RAM and 2 more CPU cores. You can find more information about our metrics stack in Chapter 3.4 Third-party containers.

2.3 Requirements on the client browser 


*IE11 is supported but not recommended. We recommend a modern browser for a great user experience. 
**Support for Microsoft Edge, older than v80, will be removed in future versions.

That’s everything that your client needs.

3. Docker


Docker is used to run application packages called "containers". In a typical example use case, a container runs a web server and a web application, while a second container runs a database server, which is used by the web application. Containers are isolated from each other and combine their own tools, libraries and configuration files, and can communicate with each other via clearly defined channels. All containers are run by a single operating system core, making them lighter than virtual machines. There is virtualization of just one application rather than an entire operating system. Containers are created as "images", which state their precise content. Images are often created by combining and modifying "base images", which have been downloaded from repositories.

Haiilo is a Java-based application that is available as a Docker container and is orchestrated together with other containerized applications such as PostgreSQL (database) and MongoDB (Filestore) with Docker Compose.

You can find out more about Docker in the official Docker documentation

3.1 Docker Compose

A tool for defining and executing multi-container Docker applications

With Compose, you use a YAML file to configure the services of your application. You then create and launch all of the services from your configuration with a single command.

With each release, we make available a pre-configured YAML file with the name "docker-compose.yml", which is a kind of pre-configuration for our orchestration of Docker containers.
The Compose file contains all configuration details such as public ports, virtual network settings, container links – so that they can communicate with each other, volume mounts, and, not forgetting the environmental parameters for the dimensioning and configuration of deeper components such as the backend JVM.
To give you an impression of this technology, we’ll show you the load balancer part of our Compose file:


  • services: Contains all of our containers, which we want to orchestrate.
  • coyo-lb: The host name of the container, so that we can use this abbreviation e.g. when linking.
  • image: Defines from which image the container is created. If the image is not locally available, Docker moves it from the Docker Hub.
  • environment: Your specific configurations are used here. We provide an additional file, in which all of the parameters are filled with values.
  • links: Defines with which containers this container can communicate via all ports within the virtual Docker network.
  • volumes: Defines mounts in the virtual Docker containers. This is important, as all data is lost when a container is removed, except if some volumes are mounted from the host to the container.
  • ports: Definition of the open ports. In this case, this is our load balancer and we want it to process the entire HTTP traffic so that ports 80 and 443 are open. The other ports are intended for other publicly accessible services.

3.2 Docker network

By default, Docker creates a virtual network bridge and dynamically allocates IP addresses to the containers. This network cannot be reached outside of the host. To make containers publicly accessible, you need to configure port mapping. With our Compose file, Docker Compose creates a virtual network called "coyo-default", in which only the load balancer is published. Without further configuration, the IP range for all containers is 

You can find out how to configure the virtual network of Haiilo yourself in this article.

And if you want to run Haiilo with a HTTP(S) proxy, take a look at this article

Load balancer

All incoming connections go via the Haiilo load balancer. This requires an SSL connection, so you need a valid certificate to execute Haiilo in our standard setup. It is, however, possible to reconfigure this to use your company’s proxy. If you want to change the configuration of our Haiilo load balancer (HAProxy), you need to retain the .conf file and customizations.

Alongside the HTTP(S) ports 80 and 443, the load balancer accepts connections to the following ports:

Kibana: Here you can find the protocols for all containers.

Grafana: Here you can find metrics such as CPU and memory usage for all containers.

Backup: Here you can create and restore the backups via a REST API.

RabbitMQ: There you find metrics about the service.

Other services such as database and file store are not accessible from outside the host.

3.3 Haiilo containers 

Haiilo stack

These containers are the centerpiece of Haiilo. It consists of the load balancer, backend, frontend, push, documentation, and backup.

Load balancer 
distributes the network and application traffic. The load balancer is the only public container.

is the core that controls the application and the databases; it is the internal logic and supervision of the program, it is everything that the user can’t see.

contains the visible part of Haiilo.

processes push notifications. Here, the server requires access to the public Internet.

contain the documentation that you find when you click on "Help" in your Haiilo.

creates backups of your Haiilo platform. More on this here

provides different languages.
is an API gateway that routes traffic to the services.

3.4 Third-party containers


These are the mandatory dependencies to execute Haiilo.

is the database to store all Haiilo content with the exception of files.

saves all files.

is a full-text search engine that we use for the search in Haiilo.

is a news broker. You can find the web interface behind port 15672.

is an in-memory database that we use for session caching. 

is a toolkit to extract metadata and content from various file types. We use Tika so that documents can also be found via their content in the search. 

Service-Discovery /Eureka
is a service registry to which other services register.

Logging stack (ELK)

ELK alias Elastic Stack is most often used in protocol analysis in IT environments and consists of three different open-source projects. With this stack, you can simply search your protocol files for all containers with a web interface:

is a search and analysis engine for all kinds of data

is a log pipeline tool that accepts inputs from various sources, performs various transformations, and exports the data in various destinations.

is a visualization tool based on Elasticsearch. You can search though all of the protocols of all containers. Here you can find helpful information for troubleshooting. You can find the web interface behind port 5601.

Metrics stack (PROM) - optional

Monitors your Haiilo with the PROM stack! As this stack requires additional RAM resources and you could already use a supervision tool in your company, this stack is optional and can be launched with the advanced start script (start-advanced.sh). You can find this in each of our releases.
Interesting key figures about your Haiilo can be found in our pre-configured Grafana dashboards, e.g. CPU and memory usage for the individual containers and other detailed information.

is a database that is optimized for the quick, highly available saving and querying of time series data in areas such as operational monitoring and application metrics.

is an open-source software, universal dashboard, and graph composer that runs as a web application. You can find the web interface behind port 5602.

analyzes the use of resources and the performance characteristics of running containers.

collect various metrics in several containers. 

4. Home directory

Each Haiilo release contains a ZIP package with start/stop scripts for the previously mentioned Compose file and the important .env file, in which all environmental parameters are set with default values.

reads the .env and executes the command "docker-compose up" to start all necessary containers that Haiilo requires for running.

executes the script "start.sh" and additionally launches the metrics stack with Grafana.

executes the command "docker-compose stop" to stop all running containers.

This file defines the setup and version of Haiilo. All variables that you need to configure have been moved to the .env file so that no customizations are normally necessary here. You can find more information in chapter 3.1.

 contains all configurable variables that are necessary for running Haiilo. To configure Haiilo, you need to edit the .env file in which you overwrite the default values with your individual configuration. 

.services (deprecated in v32)
similar to in the .env, you find additional variables here for starting certain services.

is the directory containing your complete Haiilo installation. There you can find the backend log, the databases, and your backups. You can customize the location of the directory in the .env file. 

4.1 Update

If you want to update to a new version of Haiilo, you only need to download the ZIP package.
Simply create a backup (instructions), stop Haiilo with our stop.sh script supplied, and unpack and replace all of the files stated above. It is strongly recommended to check the .env file for new parameters that need to be customized in the .env file. The changes to the parameters that we have made with each release can be found in our release notes.  

5. User administration and authentication

5.1 User administration

If you’re launching Haiilo for the first time, a local user directory is used. If you want to add an external user directory, that isn’t a problem:

Haiilo supports the protocol LDAP(S) for user provisioning, so that directories such as MS Active Directory, MS Azure AD, and OpenLDAP can be integrated easily.

You can find the instructions here.

5.2 Authentication

Alongside local authentication with users from the local user directory, users from external user directories authenticate themselves in your Haiilo via LDAP(S) and you can also add other authentication providers.

Haiilo supports authentication via SAML 2.0 and OpenID with its OAuth 2.0 standard, so that you can easily integrate MS Office SSO, MS ADFS, Google, Facebook, LinkedIn, and the like.

You can find instructions here


Our REST API offers you certain additional administrative functions, such as the re-indexing of the search index or the status of the server. It’s also possible to use all functions that Haiilo offers on the web, as well as customizing the user profile fields.

You can find more information in our documentation.

Was this article helpful?