On-Prem: Installation Guide

Dieser Artikel ist aufgrund seiner technischen Natur nur in Englisch verfügbar.

Haiilo is only available with docker. Docker is a tool for container based micro services.

https://www.docker.com/what-docker

A Container stands for virtualization of a single application/service, for example a Webserver like Apache and a MySQL Database.

Docker provides several images to run predefined services. You are also able to create your own images.

We are using the official docker-compose tool to orchestrate a bunch of services (database, application server, frontend server, message queue, elasticsearch server and so on) which all are needed for Haiilo.

If you want a more detailed view of how Haiilo works, check your our Technical OnBoarding Guide.

Prerequisites

For DNS and network configuration we can't offer a setup guide because of your individual infrastructure. So please make sure your server is reachable under 
  • Port 80 and 443 for HTTP/S connections
  • Port 8083 for Haiilo backup REST API
  • Port 5601 for Kibana to access the Haiilo server logs
  • Port 5602 for Grafana to access the metrics stack (optional)
You'll also find some articles here in our knowledge base regarding proxy configuration and other interesting articles.

Server software Requirements

  • docker >= 18.03.2
  • docker-compose >= 1.26.0
  • bash
  • unzip

Haiilo is a Java based application, available in docker. Why docker?

The containers can be installed and run easily by using the command-line or Docker supporting administration tools. While installation is simple, updating Haiilo with Docker is even simpler because containers can be dropped and re-initiated with a newer version in a matter of seconds.

Our Haiilo composition of many different containers is available as a Docker composition and can be run wherever Docker-Compose is available. Currently this is Linux and Mac OS but we only recommend Linux distributions.

We made good experiences with Ubuntu, Debian, RedHat, SLES and CentOS.

This is a guide written for Ubuntu distributions.
https://www.ubuntu.com/download/server

Server hardware requirements

Our minimum hardware requirement specifications for a single host on-premises installation are based on the number of regular users on your Haiilo social intranet platform.
If you want to run the optional metrics stack (start-advanced.sh) to gather data like CPU load, RAM usage, and backend insights like created content and online user count, you would need 8 GB of additional RAM and 2 more CPU cores.\n

Client browser requirementsBildschirmfoto_2020-04-24_um_16.43.46.png

*IE11 is supported but not recommended. For a great user experience use a modern browser. 
**The support of versions of Microsoft Edge older than v80 is deprecated and will be removed in future releases

Install Docker

Get update packages and install the docker engine and its prerequisites:

To get an overview of the supported Linux distributions and how to install docker, follow the official installation instructions: https://docs.docker.com/install/

Installing Docker on Ubuntu 18.04 LTS:\n
sudo apt install docker.io
\"When the container runs, it prints an informational message. Then, it exits.\" - Docker

Install Docker Compose

Here you have a one-liner to install Docker-Compose 1.26.0:
(root needed: sudo -i) 
curl -L --fail https://github.com/docker/compose/releases/download/1.26.0/run.sh > /usr/local/bin/docker-compose && \\\nchmod +x /usr/local/bin/docker-compose && \\\ndocker-compose --version\n
It should print docker-compose version: 1.26.0, the current docker-compose version, when installing was successful. 

Prepare the host system

Add a new user and create the environment for Haiilo4:
sudo adduser coyo
Add the coyo user to the sudoers group for access to docker commands:
sudo adduser coyo sudo
Change to user coyo:
sudo -i -u coyo
Go to your home directory:
cd /home/coyo
Create the coyo-data folder, e.g. coyo-data:
mkdir coyo-data
 
After that, download the Haiilo package and unzip it: 
(To check available COYO versions check https://download.coyoapp.com/release/onpremises)\n
wget https://download.coyoapp.com/release/onpremises/coyo4_<coyo-version>.zip\nunzip coyo4_<coyo-version>.zip`\n
 
Your Haiilo home directory should now look like this:
-rw-r--r-- 1 root root  6753 Nov 26 16:38 coyo4_18.10.3-RELEASE.zip\n-rw-r--r-- 1 root root   170 Nov 26 16:38 coyo-backend.properties\n-rw-r--r-- 1 root root    89 Nov 26 16:38 coyo-backup.properties\n-rw-r--r-- 1 root root    87 Nov 26 16:38 coyo-push.properties\n-rwxr-xr-x 1 root root 11419 Nov 26 16:38 docker-compose.yml\n-rw-r--r-- 1 root root  3625 Nov 26 16:38 .env\n-rw-r--r-- 1 root root  1323 Nov 26 16:38 README.md\n-rwxr-xr-x 1 root root   565 Nov 26 16:38 start-advanced.sh\n-rwxr-xr-x 1 root root  1162 Nov 26 16:38 start.sh\n-rwxr-xr-x 1 root root    55 Nov 26 16:38 stop.sh
 

Configure the environment variables for Docker

Open the .env file to configure your Haiilo composition. 

URL configuration

Set the URL for the frontend and backend. By default, these should be the same.
(Make sure domains are configured correctly)\n
COYO_BACKEND_URL=test.coyoapp.com
COYO_FRONTEND_URL=test.coyoapp.com

Environment profile

This specifies the profile Haiilo starts with. Might be either prod or dev where dev is only to use for developing.
COYO_PROFILE=prod

Management user

Some management features and tools e.g. the logging interface and backup REST API are protected by a basic auth username and password. We STRONGLY advise you to choose a secure password here. You might generate one using an online password generator.
COYO_MANAGEMENT_USER=admin
COYO_MANAGEMENT_PASSWORD=coyo4admin

Database

Set the name, username and password of the database.
COYO_DB_NAME=dbname
COYO_DB_USER=dbuser
COYO_DB_PASSWORD=dbpassword

File database

Files are stored in a MongoDB database which runs on port 27017 by default. You don't have to changes these values.
COYO_FILE_PORT=27017
COYO_FILE_DATABASE=coyo-files

Data location

Set a folder for the datastore. All data of the database, search engine, uploads, etc. are persisted here. The path can be either absolute or relative to the folder of the .env file – this is the data folder we created earlier in the guide, e.g. /home/coyo/coyo-data
COYO_DATA_STORAGE=./coyo-data

Outgoing email configuration

Configure the mail server so that emails can be sent to users. Note that we only support SMTP right now. If you don't need email notifications you can leave these values empty.
COYO_MAIL_FROM=Company <mailman@domain.tld>
COYO_MAIL_HOST=smtp.domain.tld
COYO_MAIL_USERNAME=smtp-user
COYO_MAIL_PASSWORD=smtp-password
COYO_MAIL_PORT=25
COYO_MAIL_PROTOCOL=smtp

SSL Certificate

The SSL certificate file. This must contain a private key followed by a public certificate in PEM format.
COYO_CERT_FILE=./cert.pem

Check out this article for more information about the SSL certificate file.

Backup task

Configure the interval to run the backup and where it should be stored. The BACKUP_CRON property takes a crontab line as value. The pattern of those crontabs is a list of six single space-separated fields: second, minute, hour, day, month, weekday. Month and weekday names can be given as the first three letters of the English names.

BACKUP_CRON=0 30 3 * * *
BACKUP_PATH=/srv/backup

Example patterns:

  • 0 0 * * * * = the top of every hour of every day.
  • */10 * * * * * = every ten seconds.
  • 0 0 8-10 * * * = 8, 9 and 10 o'clock of every day.
  • 0 0 6,19 * * * = 6:00 AM and 7:00 PM every day.
  • 0 30 3 * * * = every day at 3:30 AM.
  • 0 0/30 8-10 * * * = 8:00, 8:30, 9:00, 9:30, 10:00 and 10:30 every day.
  • 0 0 9-17 * * MON-FRI = on the hour nine-to-five weekdays
  • 0 0 0 25 12 ? = every Christmas Day at midnight

Session timeout

Configure the HTTP session timeout in seconds. After the expiration of this timeout a session is getting destroyed. The default value is 27674800 (one month).
An example: As a user, you get logged out after one month of inactivity.
(Only whole numbers are allowed.) 
COYO_SESSION_REMEMBER_TIMEOUT=2674800

Elasticsearch configuration

The Elasticsearch heap size. Max. memory that Elasticsearch may allocate. Because we are using two elasticsearch containers, one for Haiilo, one for Logging (accessed by Kibana), we have two values to configure. 
We suggest 12.5% of your RAM for ES_HEAP_SIZE and 6.25% for ES_LOGS_HEAP_SIZE.
Possible values are whole numbers followed by a single unit letter.
(m/M for Megabytes or g/G for Gigabytes)

The ES_LOGS_KEEP_DAYS defines how long log entries get stored in days.
ES_HEAP_SIZE=2g
ES_LOGS_HEAP_SIZE=1g
ES_LOGS_KEEP_DAYS=84
We recommend to set ES_LOGS_KEEP_DAYS to 30.

Java VM memory configuration

Set the maximum (Xmx) memory allocation pool for the Java Virtual Machine. Select these values according to your needs (the number of users would be an indicator). We recommend a value of 25% of your RAM for COYO_JAVA_OPTS (backend) whereby about 20% of RAM should be left for the host's system processes.
For push and backup, 1 GigaByte should be enough because these services do only one thing each.

The default value (2048m) is the minimum required value to get Haiilo running.
Possible values are whole numbers followed by a single unit letter.
(m/M for Megabytes or g/G for Gigabytes) 
COYO_JAVA_OPTS=-Xmx4g -server
COYO_PUSH_JAVA_OPTS=-Xmx1g -server
COYO_BACKUP_JAVA_OPTS=-Xmx1g -server

Database configuration

With these parameters, you can configure the Postgres database.

The two max connections parameters set the maximum number of connections in general and the number of active connections that can be allocated from this pool as well.

The synchronous commit indicates the transaction strategy.

The shared buffers is the max amount of data temporarily stored in the RAM for faster access.

We suggest 6.25% of your RAM but less is also possible.

The working memory is used for large queries and sorting within the database.

For single-host environments, you don't have to change our default values.

COYO_DB_MAX_ACTIVE_CONNECTIONS=100
COYO_DB_MAX_CONNECTIONS=400
COYO_DB_SYNCHRONOUS_COMMIT=false
COYO_DB_SHARED_BUFFERS=1024MB
COYO_DB_WORK_MEM=32MB

Server configuration

Max. threads define the max amount of worker threads.

With Backend cluster, you have multiple, clustered backend instances. This should only be true for very large and highly available instances.

For single-host environments you don't have to change our default values.
COYO_SERVER_MAX_THREADS=200
COYO_BACKEND_CLUSTER=false
For single-host environments please add the following line to your .env-file\n 
COYO_SINGLE_BACKEND=true

HTTP Security Headers

Enable HTTP Content-Security-Policy Header. The Content-Security-Policy HTTP response header helps you reduce XSS risks on modern browsers by declaring what dynamic resources are allowed to load via an HTTP Header. Disabled, if blank (default).

Enable HTTP Transport Security Header to include subdomains.

COYO_HTTP_CONTENT_SECURITY_POLICY=
COYO_HTTP_TRANSPORT_SECURITY_INCLUDE_SUBDOMAINS=true

Push notification service

If you want your users to receive push notifications on their mobile phone you need to insert a Google Firebase API service-account.json which is required to get push notifications working. 
If you don't have such a service account .json but want to use push notifications, please contact our Support team. We can provide you with one.

The thread limit limits the number of parallel executed push notifications.
COYO_PUSH_ACCOUNT_JSON=
COYO_PUSH_THREAD_LIMIT=10

ActiveMQ configuration

The MAX_CONNECTIONS defines the ActiveMQ concurrent connections limit.
The multiplier is used to calculate the effective read heart-beat timeout.

The MAX_ and MIN_MEMORY parameters define the initial and max memory in MB that ActiveMQ. For max. we suggest 9.6% of your RAM.

The log level of the ActiveMQ is defined as INFO, WARN, or ERROR.

For single-host environments you don't have to change our default values except for MAX_MEMORY. 
COYO_ACTIVEMQ_MAX_CONNECTIONS=100000
COYO_ACTIVEMQ_HB_GRACE_PERIOD_MULTIPLIER=2.5
COYO_ACTIVEMQ_MIN_MEMORY=512
COYO_ACTIVEMQ_MAX_MEMORY=1536
COYO_ACTIVEMQ_LOGLEVEL=WARN

Authorization Key

Since version 21.x Haiilo also requires a JSON Web Token to authorize users to the services. This token must be at least 256 bits (32 bytes) long and can be created using an online hash generator, for example.

COYO_AUTHORIZATION_KEY=

Start Haiilo

Now it's time to hit start and watch how Docker is downloading the containers defined in our docker-compose.yml file with the settings of your .env file.

To start Haiilo without the optional metrics stack run:
sudo ./start.sh
 
To start Haiilo with the optional metrics stack run:
sudo ./start-advanced.sh
This takes a little time, Haiilo will download all of its docker dependencies and docker images. After a successful start, Haiilo will be accessible at the COYO_FRONTEND_URL. You can verify the Docker containers status with the following command:
sudo docker ps
You can also tail the backend log directly on the Haiilo host to check when the application is up and running. There will be a log entry like \"The application started in X seconds.\"
(Make sure to replace COYO_DATA_STORAGE with the value defined in your .env file) 
tail -f COYO_DATA_STORAGE/backend/logs/coyo-backend.log
 
To stop Haiilo and its Docker Container just run:
sudo ./stop.sh

What now?

Now you have an up and running Haiilo ready for your project team to start working on the design and create content.
For you, as a system administrator, we suggest having a look at our Guides to integrate a user directory and to set up an authentication provider.
Also, you can check out our Update Guide to be ready for our next release or our Backup Guide.

War dieser Beitrag hilfreich?