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.
- List the current running docker containers
docker container list
- Spot the IRIS DB container name or ID, and execute the backup
- Ensure the backup was successful by looking at the gz file
Upgrading
-
Stop the dockers
-
Remove the application dockers
-
Get the last version of Iris
eg
git checkout v2.4.12
-
Pull the new version
-
Run IRIS again. The app will handle the DB migration automatically.
Rolling back
In case something went wrong, you can rollback to your previous version and restore data.
- Remove the faulty docker DB
docker-compose down db --volumes
- Checkout to the previous version working of IRIS
- Rebuild the images
docker-compose build --no-cache
- Spin up the docker DB, and ONLY this one.
docker-compose up db
- Get the ID or name of the docker DB
docker container list
- Restore the DB data
zcat ../iris_db_backup.gz | docker exec -i <container> psql -U postgres -d iris_db
- Spin up the rest of the dockers
docker-compose up
- Your data should back.
Version specific upgrades
v2.4.8 and onwards
The default docker compose file now pulls prebuilt images from the Docker Hub. This is done to speed up the deployment process.
❗ Custom docker compose file need to be updated to reflect this change.
v2.4.0 to v2.4.7
Warning
v2.4.0 to v2.4.6 contains bugs. Please upgrade to v2.4.7 directly.
The update from previous versions to this one is done automatically. However it introduces a number of changes in the API and access control. It may thus break integrations.
Danger
Access control has been updated. Starting from this version, all users have by-default access deny to all the cases, expect explicitely specified otherwise by group membership or automatic access rights.
Users can also now be linked to customers, which automatically give them access to the related alerts and cases.
- The migration to the new access control system is done automatically.
- New users will not have access to any cases until they are explicitely granted access.
- Existing users will keep their previous access rights.
- Existing users will not be linked to any customer. They will need to be linked to a customer to have access to the new cases.
- Existing users not linked to customers will not see any alerts. They need to be added to the corresponding customer to see the alerts.
Please refer to the API documentation to update any integration which may use the following features:
- Notes
- Timeline
- Acccess control
The layout of the reporting has been updated as well. Refer to the https://<server>/case/export?cid=<case_id>
endpoint to get all the possible fields.
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.
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.
- Stop the dockers
docker-compose stop
- Remove the application dockers
docker-compose rm app worker
- Get the last version of Iris
git checkout <last_tagged_version>
- eggit checkout v1.4.5
- Build the new versions
docker-compose build --no-cache app worker nginx
- 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.
- Spot the IRIS DB container with
docker container list
. It should look likeiris-web-db-x
- 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",
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"
v1.4.4
, build and run.
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