On-Prem: Update guide

You can always find the current version of Haiilo On-Premises here. If you have any questions about the update beforehand, you're welcome to contact us at any time via our Service Desk.

Haiilo has been pursuing a cloud-only strategy since January 2022. Therefore, we have provided version 42 as the last version for On-Premises. This version will be supported with security-relevant updates and bug fixes.

Would you like to benefit from new features in the future? Take the chance now and switch to the Cloud, which is hosted in Germany. Contact the Service Desk for more information.

In these instructions, we’ll show you how to update your On-Premises. To perform an update without any problems, please follow all necessary steps.

Own backup plan

When you have your own backup mechanism implemented you may skip the backup steps described in this guide.


We advise you to use a GUI tool like postman to manage REST API calls / HTTP requests. 

In the following, we give examples with the command-line tool cURL. You don't have to but you can run these on the Haiilo host.

Updating major versions

If you update to a higher version, from v14.x to 21.x for example, please note that you first update v14 to v18 and then v18 to v21. 

Also, we recommend always updating to the latest major of your current version when updating to a higher major version (21.8.0 to 21.9.0 to 25.10.7).

Also make sure to not use a more recently published version, then the version you want to update to. In example, If you try to update from a LTS version that contains a newer backport (28.7.2, published March 19th) to the next major version (32.2.0, published March 16th), the update will fail due to mismatching bugfix migration dates.

Step by Step Guide

The update of an existing installation is done in a few simple steps.
We provide download packages here. Just download the new release with wget into your Haiilo home directory and follow these easy steps:

1. Announce maintenance work 

some hours early with a maintenance message via REST API's management endpoint. Please set duration (time till message disappears by itself) and message depending on your needs.
(Make sure to replace the COYO_* parameters with the values in your .env file)


2. Activate maintenance mode




Please set the headline and message depending on your needs.
(Make sure to replace the COYO_* parameters with the values in your .env file)
-H 'Content-Type: application/json'
-d '{
"headline": "Upgrading to 42.5.1-RELEASE",
"message": 'Don't panic!"

3. Create a backup 

and wait until it's finished. Below you find the PUT request to create a backup and the GET request to pull the status.

(Make sure to replace the COYO_* parameters with the values in your .env file)
#create backup:


Stop Haiilo: be sure to be in the home directory of Haiilo:

#show directory 


4. Unzip 

the downloaded release and replace/rename files like this:
root@coyo-host:/home/coyo unzip coyo4_<version>-RELEASE.zip 
Archive:  coyo4_<version>-RELEASE.zip
replace .env? [y]es, [n]o, [A]ll, [N]one, [r]ename: r
new name: .env_<version> 
  inflating: .env_<version>            
replace coyo-push.properties? [y]es, [n]o, [A]ll, [N]one, [r]ename: n
replace coyo-backup.properties? [y]es, [n]o, [A]ll, [N]one, [r]ename: n
replace stop.sh? [y]es, [n]o, [A]ll, [N]one, [r]ename: y
replace docker-compose.yml? [y]es, [n]o, [A]ll, [N]one, [r]ename: y
replace start.sh? [y]es, [n]o, [A]ll, [N]one, [r]ename: y
replace start-advanced.sh? [y]es, [n]o, [A]ll, [N]one, [r]ename: y
replace coyo-backend.properties? [y]es, [n]o, [A]ll, [N]one, [r]ename: n
replace README.md? [y]es, [n]o, [A]ll, [N]one, [r]ename: y

5. Verify the .env file

for new parameters and manually add them to your .env. Read the descriptions carefully and enter required values if mandatory.

To make this step easier, you can use the (mostly-) preinstalled tool diff:
sdiff -o .env_new .env .env_<version>

It creates a new file (.env_new) from your current .env and the previously unzipped one from the new version (.env_<version>)

The tool shows a side-to-side view of both files. You can choose which parameters to merge into the new file with either entering 1 (for left) or 2 (for right).


Afterwards you rename .env_new to .env .


in Version 14+

Two new lines are expected. One is for telling the environment to run on only one backend the other one sets the OOM-score to 0 to not kill the process in case of out-of-memory.
# Mode for single host installation


In Version 21+ 

You will need to add an authorization key with at least 256 bit. You can use any hash generator online to generate one. 
# Mandatory shared secret used for authorization json web tokens that are used to authorize the user at the services
# (e.g. translation service). Must be at least 256 bit (32 byte) long.

In Version 25+

The path to Haiilos JVM Keystore changed. If you use a self-signed certificate for LDAPS, make sure to adapt it. Refer to this article.

In Version 32+ (to update to v32 it is mandatory that you updated to v28.7.1 !)

The download file contains "update-mongodb.sh". You don't need to execute it manually. It will be executed with any of the start-scripts.
Additionally we merged the parameters from .services into .env. If you are using an add-on, you would want to set the correct values in the .env for these.

As of v32, all /manage/* endpoints change to /manage/backend/*
for example, when deactivating maintenance mode:



In Version 35+

We are migrating your files from GridFS to S3. For that process you should have at least double the storage free that Haiilo is currently using. So if your Haiilo is 400GB in storage size you will need 800GB of free storage space. Also make sure to have 2GB of RAM available for the migrator service.


6. Start Haiilo

or start with the optional metrics stack:


Should you experience ERRORS from the docker-compose.yml file, please make sure that you are on the current supported version of docker-compose (>=v1.26.0.). For further instructions how to update to the current docker-compose version look up or Installation Guide.

7. Check the backend Log

Tail the coyo-backend.log till the message "Application started in X seconds" appears:
tail -f coyo-data/backend/logs/coyo-backend.log

8. Deactivate maintenance mode



As of v32, all /manage/* endpoints change to /manage/backend/*


Was this article helpful?