Update Guide – COYO Campus

In dieser Anleitung zeigen wir euch, wie ihr euer COYO updatet. 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 advice 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.

Don't skip major Versions
If you need to update to a higher version, from v14.x to 21.x, in example, please note that you first update v14 to v18 and then v18 to v21.

We also prepared a Video guide:

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. 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. Put COYO into maintenance mode via REST API's management endpoint. Please set 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 13.0.2-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

4. Stop COYO with the ./stop.sh script

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

6. Check the new .env file for updates or read our release notes carefully and apply changes to .env file
(When you missed a parameter you'll get a WARN message when running the start.sh script. You should then abort the start and check the parameter)

In example:
these additional parameter in are mandatory and must be existent in your .env file:

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 COYO in case of OOM (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 in 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=

Attention:

Should you experience ERRORS from the docker-compose.yml file, make sure that you are on the current supported version of docker-compose (>=v1.26.0.).

in Version 25+
Some parameters got outsourced into the .services file. you'll need to adapt the parameters manually. Also you will find another Variable you need to add to the .env file.

 # Java opts used for the service discovery
 COYO_EUREKA_JAVA_OPTS=-Xmx1g -server

in Version 28+

Parameters for plug-ins have been added. If you are going to use a plug-in add on-line RSA keys

# Private RSA key that is used to sign data sent to a plug-in. One-line value only, remove all line breaks.
# Only required if a plug-in is enabled.
COYO_PLUGIN_PRIVATE_KEY=

# Certificate belonging to the private key that is used to sign data sent to a plug-in. One-line value only, remove all line breaks.
# Only required if a plug-in is enabled.
COYO_PLUGIN_CERTIFICATE=

7. Start COYO

./start.sh

or start with the optional metrics stack:

./start-advanced.sh

8. Tail the coyo-backend.log till the message "Application started in X seconds" appears and watch for migration errors

tail -f COYO_DATA_STORAGE/backend/logs/coyo-backend.log

9. Visit your COYO and deactivate maintenance mode

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

Fehlt was?