Step 1: Backup Your Current Installation

The page APIMGMNT:API Management Backup and Restore was not found  -- Please check/update the page name used in the MultiExcerpt-Include macro

Step 2: Download and Extract the Software

1. Download the new API Management software.

2. Unzip the downloaded software from api-mgmt-<version>.zip. This creates a new folder api-mgmt containing the new version of API Management.

Step 3: Configure the Installation Settings

Rework the configuration files.

1. If there are new configuration variables coming with the new software release (see API Management Release Notes), you need to merge the .env file of your installation (the one you have backup-ed in step 4)  with the new one coming with the update.

   As you have already an administrator account for your API Management installation, you can comment out the following lines in your .env file:

   # KEYCLOAK_ADMIN_USERNAME=username
# KEYCLOAK_ADMIN_PASSWORD=password

2. If you did not stick to the standard installation and have made changes to the docker-compose.yml, you need to merge those changes into the new docker-compose.yml.
3. Copy all certificates and keystores from the backup folder of your old installation (api-mgmt_backup/configs) to your updated installation (api-mgmt/configs). Overwrite the existing files from the target folder - they are example files only.

Step 4: Update the Software

1. Load the new software with
   

   docker image load -i api-mgmt-gateway-<VERSION>.tar

   docker image load -i api-mgmt-ui-<VERSION>.tar
   

   docker image load -i api-mgmt-keycloak-<VERSION>.tar

   docker image load -i api-mgmt-devportal-<VERSION>.tar

2. Upgrade the MySQL database using the following commands:

   docker-compose up -d mysql
   

   docker exec -it mysql bash
   

   mysql_upgrade --password
   

   If you are asked for a password, use the password you specified in the .env file for MYSQL_ROOT_PASSWORD.

   exit
   

   docker-compose stop

Step 5: Start all Services and Finalize the Update

1. Go to folder api-mgmt/single-host-setup (folder that contains the file docker-compose.yml).

   Start all containers by running the following command:

   docker-compose up

   To run the containers in the background, use:

   docker-compose up -d

2. Upload new configurations.
   If the new API Management software comes with new configurations (e.g. new policies, see API Management Release Notes), you need to import them to your installation. Import the file(s) as described on API Management Administration > Export/Import Data.

3. After a successful update you may want to remove the old images to free up some disk space. In this case, just run

   docker image rm api-mgmt/NAME-VERSION

   For more clean up instructions refer to the docker documentation.

   Also consider removing the backup files from step 3 as they consume a considerable amount of disk space.