In dieser Anleitung zeigen wir euch, wie ihr euer COYO On-Premises aktualisiert. Um ein Update fehlerfrei durchzuführen, befolgt bitte alle notwendigen Schritte.
Hinweis:
Dieser Artikel ist aufgrund seiner technischen Natur nur in Englisch verfügbar. Falls ihr Fragen haben solltet, wendet euch gerne an unseren Service Desk.
Before we start, please note the following:
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 COYO host.
In the following, we give examples with the command-line tool cURL. You don't have to but you can run these on the COYO host.
Updating major versions
If 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 update 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.
If 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 update 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 COYO home directory and follow these easy steps:
1. Activate maintenance mode in the administration
2. 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)
(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
3. Stop COYO with the ./stop.sh script
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: y5. Check the new .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
COYO_SINGLE_BACKEND=true
# Score for OOM
COYO_BACKEND_OOM_SCORE=0In 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 COYOs 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.
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 COYO is currently using. So if your COYO 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 COYO
./start.sh
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. Tail the coyo-backend.log till the message "Application started in X seconds" appears
tail -f coyo-data/backend/logs/coyo-backend.log
8. Visit your COYO and deactivate maintenance mode
