Skip to content

Upgrades

Most of the time, Iris handles upgrades of the database automatically when a new version is started, thus no specific actions are required.
However, some breaking changes might need manual intervention. Please use the selectors below to assess if a manual action is required.

For production environments, it is highly recommended to make backups of the DB in case any issues occur during upgrades.

Backing-up DB

Only if you run in production and/or data is critical.

  1. List the current running docker containers docker container list
  2. Spot the IRIS DB container name or ID, and execute the backup
  docker exec <container> pg_dump -U postgres iris_db | \ 
    gzip > ../iris_db_backup.gz
  1. Ensure the backup was successful by looking at the gz file 
  zcat ../iris_db_backup.gz | less

Upgrading

  1. Stop the dockers 

    docker-compose stop

  2. Remove the application dockers 

    docker-compose rm app worker

  3. Get the last version of Iris 

    git checkout <last_tagged_version>

    eg git checkout v2.3.6

  4. Build the new versions 

    docker-compose build --no-cache app worker

  5. Run IRIS again. The app will handle the DB migration automatically. 

    docker-compose up

Rolling back

In case something went wrong, you can rollback to your previous version and restore data.

  1. Remove the faulty docker DB docker-compose down db --volumes
  2. Checkout to the previous version working of IRIS
  3. Rebuild the images docker-compose build --no-cache
  4. Spin up the docker DB, and ONLY this one. docker-compose up db
  5. Get the ID or name of the docker DB docker container list
  6. Restore the DB data zcat ../iris_db_backup.gz | docker exec -i <container> psql -U postgres -d iris_db
  7. Spin up the rest of the dockers docker-compose up
  8. Your data should back.

Version specific upgrades

v2.3.4

❗ The layout of the reporting has slightly changed. Custom report templates might not work anymore. You can use https://<server>/case/export?cid=<case_id> to get all the possible fields.

No other impact is to be expected.

v2.1.0

The default location of the SSL certificates have been changed from dockers/nginx/dev_certs to certificates/nginx/web_certificates.
The docker-compose.yml has thus been updated to mount this volume on the nginx Docker.

Except these changes, users in v2.0.x can upgrade to v2.1.0 without any manual intervention.
Users in v1.4.x need to follow the v2.0.0 upgrade instructions before upgrading to v2.1.0.

v2.0.0

Breaking changes

This version brings breaking changes on the following:

  • API
  • Modules
  • Python Client
  • Environment variables in the .env configuration
  • Default listening ports of IRIS WebApp

Warning

Custom made modules need to be upgraded to IRIS Module Interface v1.2.0. Please see modules upgrade for v2.0.0

Instance migration

To migrate an instance from v1.4.5, one can use the script in upgrades/upgrade_to_2.0.0.py located in the repository.
These commands needs to be run from the root of the repository (pwd should return something like /iris-web): 

# Pull the lastest version 
git pull 

# Checkout to iris v2.0.0
git checkout v2.0.0 

# Check if upgrades possible
python3 upgrades/upgrade_to_2.0.0.py --check

# Run the upgrade
python3 upgrades/upgrade_to_2.0.0.py --install

The script will take care of migrating the environment variables to reflect the changes in v2.0.0. Please review the .env file afterward.

The port have been changed 443. The script asks if the previous port should be kept or migrated to the new one.

Once validated, one can proceed with the usual upgrade methodology. 

docker-compose stop 
docker-compose build --no-cache 
docker-compose up -d

v2.0.0 modules upgrades

This only concerns custom modules not shipped with IRIS Web App.
The IRIS module interface has been upgraded to v1.2.0. No breaking changes are associated. One need to change the iris_module_interface dependency to 1.2.0 in the requirements and rebuild the module.

Python client

The client has been updated to reflect the latest changes of the API. It also integrates features that were missing previously, such as Datastore Management.
Some methods have been deprecated and some other modified. The easiest way to upgrade is to increase the version in the requirements and test. Each deprecated method will produce a warning or raise an exception.

v1.4.5

If you are coming from IRIS <= v1.3.1 please read this.
Changes have been made to the NGINX docker to allow upload of big files for the datastore. It is hence necessary to also rebuild the NGINX docker this time.

  1. Stop the dockers docker-compose stop
  2. Remove the application dockers docker-compose rm app worker
  3. Get the last version of Iris git checkout <last_tagged_version> - eg git checkout v1.4.5
  4. Build the new versions docker-compose build --no-cache app worker nginx
  5. Run IRIS again. docker-compose up

v1.4.4

This only applies if you are coming from IRIS <= v1.3.1.

This version brings breaking changes in the DB docker by adding a named volume instead of the default one. This implies that previous existing database is ignored as the new docker won't know which volume was previously used.
To prevent this, please strictly follow the guide below. This will copy the data of the existing volume, to the new named one.

  1. Spot the IRIS DB container with docker container list. It should look like iris-web-db-x
  2. Fetch the current db volume ID (name field with the command below)

docker inspect <iris_db> | grep -A5 "Mounts"

# Example of output
"Mounts": [
  {
      "Type": "volume",
      "Name": "a90b9998a3233a68438c8e099bd0ba98d9f62c9734e40297b8067f9fdb921eb9",
      "Source": "/var/lib/docker/volumes/a90b9998a3233a68438c8e099bd0ba98d9f62c9734e40297b8067f9fdb921eb9/_data",
      "Destination": "/var/lib/postgresql/data",
3. Stop all the IRIS dockers : docker-compose stop
4. Create a new empty volume : docker volume create --name iris-web_db_data
5. Run a volume copy via a dummy image : 
docker run --rm -it -v <previous_db_volume_id>:/from:ro -v iris-web_db_data:/to alpine ash -c "cd /from ; cp -av . /to"

# With the example of 2., this gives 
docker run --rm -it -v a90b9998a3233a68438c8e099bd0ba98d9f62c9734e40297b8067f9fdb921eb9:/from:ro -v iris-web_db_data:/to alpine ash -c "cd /from ; cp -av . /to"
6. Pull the last changes from the repository, checkout to v1.4.4, build and run. 

git pull origin 
git checkout v1.4.4
docker-compose build 
docker-compose up
7. The data should be successfully transferred.

Do not forget to clear out your browser cache, many JS files were changed.

v1.4.3

A patch exists for this version. Please directly upgrade to v1.4.4

v1.4.2

A patch exists for this version. Please directly upgrade to v1.4.4

v1.4.1

A patch exists for this version. Please directly upgrade to v1.4.4

v1.4.0

A patch exists for this version. Please directly upgrade to v1.4.4

Last update: 2023-12-30