Note:
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
• 2.2 Requirements on the server hardware
• 2.3 Requirements on the client browser 

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 

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.

• 3.1 Docker Compose
• 3.2 Docker network
• 3.3 Haiilo containers
• 3.4 Third-party containers

Note:
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 172.18.0.0.0.0/24. 

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:

Note:
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.

3.4 Third-party containers

Dependencies

These are the mandatory dependencies to execute Haiilo.

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:

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.

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.

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.

Note:
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.

Note:
You can find instructions here. 

6. REST API

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.

Note:
You can find more information in our documentation.