Upgrade from community version 4.2.0.x to enterprise version 4.2.1.2

This section describes how customers and partners using OpenIAM on Docker can upgrade from community version 4.2.0.x to enterprise version 4.2.1.2.

Update repository settings

To start the upgrade process, connect to your Linux host where you installed OpenIAM and go to the directory where you installed the OpenIAM Docker compose. By default, this should be:/usr/local/openiam/openiam-docker-compose. Go to that directory and check the status using the command shown below.

cd /usr/local/openiam/openiam-docker-compose
git status

During installation of the previous version, at a minimum, the env.sh file was updated. Output from the command above, which is shown below, will indicate the files which were changed.

On branch [branch name]
Your branch is up to date with 'origin/[release branch name]'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:   env.sh
    ...[other files if they where modified]

To preserve the customizations create a new branch and add the changes to that branch as shown below. You can name your branches based on your standards or preference.

sudo git checkout -b RELEASE-4.2.0.7-changes
sudo git add .
sudo git commit -a -m "4.2.0.7-changes"         // Now you have saved branch with customizations
sudo git checkout -b update_to_RELEASE-4.2.1.2  // New branch to do a merge so you can keep original customized branch safe
sudo git pull
sudo git pull origin RELEASE-4.2.1.2
sudo git merge origin/RELEASE-4.2.1.2

In case conflic arises, follow the article below and jump onto the section related to “How to identify merge conflicts” and “How to resolve merge conflicts using the command line”. https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts

In short, the steps described in the documents mentioned are:

Identify the file with conflict, which will be shown after executing git merge command;
Open the files in editor used and search for <<<<<HEAD ===== >>>>>new_branch
Keep the section required and delete the other section
Execute git commit -m <comment_here>.

Then execute remaining commands.

sudo git merge origin/RELEASE-4.2.1.2

After these steps, verify that env.sh has updated branch.

export ELASTICSEARCH_DISCOVERY_URL=tasks.elasticsearch-Service
export OPENIAM_VERSION_NUMBER="4.2.1.2"
export BUILD_ENVIRONMENT="prod"
export RABBITMQ_USERNAME="openiam"

At this point, you have updated your docker-compose project to Release-4.2.1.2.

Continue upgrade process

Now you all set, please run the following commands to update your local images and then start the application.

sudo ./shutdown.sh
sudo ./setup.sh
sudo ./startup.sh

After upgrading execute

watch -n 5 ‘docker ps’

to check the status of all the containers.

If some of the services are getting killed follow the steps below:

The flyway container should fail: docker ps -a | grep flyway with a non-zero exit.
Modify utilities/flyway/docker-compose.yaml, and uncomment this line:

FLYWAY_COMMAND: "repair"

Deploy using ./setup.sh && ./startup.sh
Modify utilities/flyway/docker-compose.yaml, and comment out this line:

FLYWAY_COMMAND: "repair"

Deploy using./setup.sh && ./startup.sh

Wait for the containers to fully startup and then the application will be ready for use.

Post upgrade: update workflow activiti files

Release 4.2.1.2 has changes in Activiti XML files. Those files are stored in volume openiam-activiti-storage_storage.

If you did any changes in XML files:

create backup of changed files. To find files location run docker inspect openiam-activiti-storage_storage Consider property 'Mountpoint' as a path to activiti files.
drop volume by running docker volume rm openiam-activiti-storage_storage
after you run setup.sh and startup.sh new volume will be created based on files from new release.
gracefully merge your changes into proper files and restart container workflow by running docker stop [workflow container id]

If you didn't do any changes in XML files simply drop the volume docker volume rm openiam-activiti-storage_storage It will be re-created automatically based on files from new release.

Post upgrade: update groovy script files

Release 4.2.1.2 has changes in groovy script files. Those files are stored in volume openiam-iamscripts-storage_storage.

If you did any changes in groovy script files (mostly possible situation):

create backup of changed files. To find files location run docker inspect openiam-iamscripts-storage_storage Consider property 'Mountpoint' as a path to groovy script files.
drop volume by running docker volume rm openiam-iamscripts-storage_storage
after you run setup.sh and startup.sh new volume will be created based on files from new release.
gracefully merge your changes into proper files using groovy manager or do it in terminal using Linux commands. If you do it using Linux commands make sure new files have same permissions as other files in the volume. Check it by running ls -al in the iamscripts volume directory
restart whole application by running shutdown, setup and startup scripts in order
in webconsole->administration->groovy-manager-> press button 'Compile All Groovy Scripts' to make sure your merged files are compatible with new version. In case of any errors, fix those and run compilation again unless it will be completed successfully.

If you didn't do any changes in groovy script files simply drop the volume docker volume rm openiam-iamscripts-storage_storage It will be re-created automatically based on files from new release.

Upgrade from 4.2.0.7 to 4.2.0.8

Upgrade from 4.2.0.x to 4.2.1.3