On-Prem: Update Guide

Die aktuelle Version für Haiilo On-Premises findet ihr stets hier. Solltet ihr vorweg Fragen zum Update haben, könnt ihr uns natürlich jederzeit gerne über unseren Service Desk kontaktieren.

Wie bereits Ende Januar angekündigt, verfolgen wir seit dem Januar 2022 eine Cloud-only Strategie. Daher haben wir euch mit Version 42 die letzte Version für On-Premises zur Verfügung gestellt, die ihr noch bis Ende 2024 wie gewohnt nutzen könnt

Ihr möchtet auch zukünftig von neuen Features profitieren? Nutzt jetzt die Chance und wechselt in die in Deutschland gehostete Cloud. Falls ihr Fragen haben solltet, wendet euch gerne an unseren Service Desk.

In dieser Anleitung zeigen wir euch, wie ihr euer On-Premises aktualisiert. Um ein Update fehlerfrei durchzuführen, befolgt bitte alle notwendigen Schritte.

Dieser Artikel ist aufgrund seiner technischen Natur nur in Englisch verfügbar. Falls ihr Fragen haben solltet, wendet euch gerne an unseren Service Desk.

Own backup plan

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

REST API

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

Administration: 

Bildschirmfoto_2021-06-25_um_13.16.00.png

API:

Please set the headline and message depending on your needs.
(Make sure to replace the COYO_* parameters with the values in your .env file)
curl -u 'COYO_MANAGEMENT_USER':'COYO_MANAGEMENT_PASSWORD'
-X POST
https://COYO_BACKEND_URL/manage/maintenance
-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:
curl -u 'COYO_MANAGEMENT_USER':'COYO_MANAGEMENT_PASSWORD' 
-X PUT  
https://COYO_BACKEND_URL:8083/api/backups

#check backup status:
curl -u 'COYO_MANAGEMENT_USER':'COYO_MANAGEMENT_PASSWORD' 
https://COYO_BACKEND_URL:8083/api/backups

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

#show directory 
pwd
/home/coyo

./stop.sh
 

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).

Bildschirmfoto_2021-03-22_um_13.28.33.png

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
COYO_SINGLE_BACKEND=true

# Score for OOM 
COYO_BACKEND_OOM_SCORE=0
 

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.
COYO_AUTHORIZATION_KEY=

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:

curl -u 'COYO_MANAGEMENT_USER':'COYO_MANAGEMENT_PASSWORD' \
-X DELETE \
  https://COYO_BACKEND_URL/manage/backend/maintenance

 

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:
./start-advanced.sh
 

Attention: 

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

curl -u 'COYO_MANAGEMENT_USER':'COYO_MANAGEMENT_PASSWORD'
-X DELETE 
https://COYO_BACKEND_URL/manage/maintenance

 

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

curl -u 'COYO_MANAGEMENT_USER':'COYO_MANAGEMENT_PASSWORD'
-X DELETE 
https://COYO_BACKEND_URL/manage/backend/maintenance
 

War dieser Beitrag hilfreich?