Skip to main content
Version: 15.0

Upgrade from ADOGRC 13.6 or 14.4 to ADOGRC 15.0

This chapter describes how to upgrade an existing ADOGRC installation from 13.6 or 14.4 to 15.0.

The upgrade process differs significantly from previous ADOGRC releases. Earlier versions ran the application server on Windows, while the web server supported deployment on multiple platforms. Starting with ADOGRC 15.0, both the application server and the web server are deployed as containerized services in a Kubernetes environment.

To simplify the migration process, ADOGRC 15.0 provides the management tool aupgrade_product. The tool upgrades an existing database to the new version and automatically performs the required migration tasks, including upgrading the database schema, updating the application library, executing migration scripts and preserving component settings.

The migration process consists of the following high-level steps:

  1. Stop the existing ADOGRC services.

  2. Back up deployment-specific configuration files.

  3. Upgrade the database using aupgrade_product.

  4. Deploy ADOGRC 15.0 in Kubernetes using the backed-up configuration.

  5. Verify the deployment and remove the old installation.

Prerequisites​

Before upgrading ADOGRC to version 15.0, ensure that the following prerequisites are met:

  • You are running ADOGRC 13.6 or 14.4.

  • Your database is hosted on a supported version of Microsoft SQL Server or PostgreSQL.

  • You have access to a Linux machine, or Windows Subsystem for Linux (WSL), with Docker Engine installed and network access to the database server and the BOC OCI Registry.

  • You have the required credentials for the database server and valid credentials for the BOC OCI Registry.

  • You have access to a Kubernetes environment and the required administration tools, including kubectl and helm.

  • The target environment meets the Hardware/Software Requirements for ADOGRC 15.0.

  • You know the password of the ADOGRC user Admin.

Application Library for ADOGRC 15.0​

You can get started right away if you are using the default library that comes with ADOGRC (the ADOGRC Standard Application Library). Custom metamodel changes made on the Properties page in the ADOGRC Administration will not affect the update—these changes will be preserved.

If you are using a customized application library, obtain the corresponding updated version from your ADOGRC consultant before starting the upgrade.

info

This migration procedure is intended for system administrators with access to the existing ADOGRC installation, the database and the target Kubernetes environment.

caution

Create a complete backup of your database before starting the migration. After the database upgrade has completed successfully, the upgraded database can no longer be used with ADOGRC 13.6 or 14.4.

Stop Services​

Stop all running ADOGRC services (application server and web server) and ensure that no users remain logged in to ADOGRC.

To stop the services (on Windows):

  • Open Services. Press <Windows> + <R> to open the Run box, enter services.msc, and then click OK.

  • Stop the ADOGRC application server (service name e.g. "ADOGRC14.0-ADONIS17.0Service") and the Apache Tomcat web server (service name e.g. "Tomcat10").

Backup Deployment-Specific Configuration​

Before upgrading the database, back up the deployment-specific configuration files of your existing ADOGRC installation.

Earlier versions of ADOGRC stored deployment-specific settings in various configuration files. In ADOGRC 15.0, these settings are no longer maintained in local configuration files. Instead, they are provided as configuration values during deployment.

The backed-up configuration files will therefore be required later when configuring the new ADOGRC 15.0 deployment.

ADOGRC Application Server Configuration​

  • <ADOGRC 13.x/14.x application server>/conf/server.conf (contains the database name, and application server or aworker processes ports).

  • <ADOGRC 13.x/14.x application server>/conf/adoxx.conf (optional, if parameters have been changed from their default value)

  • <ADONIS 13.x/14.x application server>/conf/log.conf (optional, if parameters have been changed from their default value)

Apache Tomcat Configuration​
  • <Tomcat>/webapps/ADONIS16|7_x/adoxx_web.properties (contains the application server IP address and definition of aworker processes)
info

Do not modify the backed-up files. They will be used as a reference when transferring deployment-specific settings to the ADOGRC 15.0 deployment.

Upgrade the Database​

To keep using your existing database with ADOGRC 15.0, you need to upgrade it using the management tool aupgrade_product. The tool is executed in a short-lived Docker container using the ADOGRC application server image.

During the upgrade, aupgrade_product automatically performs all required migration tasks. These include upgrading the database schema, updating the application library, executing the required migration scripts and preserving component settings.

Before executing the upgrade, prepare the working directory, prepare the application library and create the required configuration files as described in the following sections.

Prepare the Working Directory​

Create a working directory on the Linux machine or WSL environment from which you will execute the database upgrade. This directory will contain the configuration files required for the upgrade as well as the generated log files.

The following example creates the working directory /opt/data/config and a directory for the generated log files:

mkdir -p /opt/data/config
mkdir -p /opt/data/logs
note

To keep our examples simple, we have decided to use the folder /opt/data/ as the working folder. This folder is usually available and allows us to use absolute paths as opposed to relative paths in a users home folder. You can, of course, use any other folder, just make sure that, when you use paths used by processes in the container, you define them from the point of view of the container and not the host.

Prepare the Application Library​

The database upgrade requires an application library for ADOGRC 15.0. During the upgrade, aupgrade_product updates the application library using the specified library file.

Using the Default Library​

If you are using the default library (= the ADOGRC Standard Application Library), no further action is required. The library file is already included in the ADOGRC application server image and is located at /aserver/data/default.axl.

Using a Customized Library​

If you are using a customized library, copy the library file you received from your ADOGRC consultant into the directory /opt/data/config created in the previous section.

note

The examples in this guide assume that a customized library file is located in /opt/data/config.

Create config.json​

The file config.json controls the upgrade operations performed by aupgrade_product. It specifies whether the database schema is upgraded, whether component settings are preserved and which application library is imported into the upgraded database.

Create the file config.json in the directory /opt/data/config with the following content:

{
  "skipDbScripts": false,
  "beforePreprocessingScripts": [],
  "preprocessingScripts": [],
  "metamodelScripts": [],
  "migrateCompSettings": true,
  "applicationLibrary": "<library-file-name>",
  "additionalComponentSettings": [],
  "postprocessingScripts": []
}

The most important configuration parameters are:

  • skipDbScripts: Leave this value set to false to upgrade the database schema.

  • migrateCompSettings: Leave this value set to true to automatically export the component settings before the upgrade and re-import them afterwards, ensuring that your adaptations to library-specific features are preserved.

  • applicationLibrary: Specify the application library to be used for the database upgrade. If you are using the default library (= the ADOGRC Standard Application Library), specify /aserver/data/default.axl. If you are using a customized library, specify its file name in the directory /opt/data/config, for example custom.axl.

note

Unless instructed otherwise by your ADOGRC consultant, leave all remaining configuration parameters unchanged.

note

The logs created during the upgrade are written with a user in the container who doesn't exist on the host system. It is therefore necessary to allow write permissions to all on the logs folder. You can set these with the command chmod o+w /opt/data/logs . Please delete the files and folders used during the upgrade to ensure that the system is back in a clean state.

Log in to the BOC OCI Container Registry​

To log in to the BOC OCI container registry, you will need the access informations and credentials you received from your ADOGRC consultant. Login to the BOC OCI registry is required to access the image for the temporary container used to upgrade the database.

The easiest way to log in is to use the standard docker command docker login <boc-registry>. This will prompt you for an access id ("user name") and an access token ("password").

caution

This command stores the credentials in the docker config file in clear text (default: ~/.docker/config.json). If you are currently deploying ADOGRC, you can use this file when you log in to the BOC OCI registry with Helm and creating the ImagePullSecret but make sure to safely delete this file afterwards.

note

Do not pass credentials directly as command parameters, the bash command history stores a list of recent commands and could therefore inadvertently reveal the credentials.

Execute the Database Upgrade​

After preparing the working directory, the application library and the config.json file, execute the following command from the Linux machine or WSL environment to start the database upgrade.

docker run -it --rm \
  --entrypoint /aserver/aupgrade_product \
  -v /opt/data/logs:/aserver/logs \
  -v /opt/data/config:/opt/data/config \
  <boc-registry> \
  --srcProductVersion "<16.x|17.x>" \
  --id "<database-name>" \
  --dbInstance "<database-server>" \
  --dbType "<SQLServer|PostgreSQL>" \
  --dbPort "<database-port>" \
  --dbUser "<database-admin-name>" \
  --configRootPath "/opt/data" \
  --configName "config"

The command starts a short-lived Docker container using the ADOGRC application server image. The container executes aupgrade_product, performs the database upgrade and terminates automatically after the operation has completed.

info

For Microsoft SQL Server, aupgrade_product uses encrypted database connections by default, matching the default behavior of Microsoft ODBC Driver 18 for SQL Server. If your SQL Server is not configured for encrypted connections, specify --encrypt "optional". If your SQL Server uses an encrypted connection with an untrusted server certificate, you may also need to specify --trustservercertificate "yes". PostgreSQL does not require these parameters.

If the command fails with an SSL or certificate validation error, review the SQL Server encryption settings and adjust these parameters accordingly.

note

ADOGRC 15.0 no longer supports Windows Authentication for Microsoft SQL Server databases. Use SQL Server Authentication instead.

The most important parts of the command are:

  • --entrypoint /aserver/aupgrade_product: Executes the upgrade tool directly instead of starting the application server.

  • -v /opt/data/logs:/aserver/logs: Stores the log files generated during the upgrade in the /opt/data/logs directory on the host system.

  • -v /opt/data/config:/aserver/config: Makes the upgrade configuration, including config.json and, if applicable, a customized application library, available to aupgrade_product inside the container.

  • <boc-registry>: The BOC OCI Registry from which Docker downloads the image for the temporary container.

The database-related command parameters are:

  • --srcProductVersion: Specify the complete version of your existing ADOGRC installation, including the major and minor version.

  • --id: The name of the database to be upgraded.

  • --dbInstance: The host name of your database server.

  • --dbType: The type of your database management system. Supported values are PostgreSQL and SQLServer.

  • --dbPort: For default installations, you do not have to explicitly specify the database port. ADOGRC automatically uses the standard port 5432 for PostgreSQL or 1433 for SQL Server default instances. Specify this parameter only if your database server uses a custom port or a SQL Server named instance.

  • --dbUser: The user name of a database administrator with sufficient privileges to upgrade the database schema.

  • --configRootPath: The parent directory of the config directory containing config.json. In the examples throughout this guide, this value is /opt/data.

  • --configName: This is the name of the folder and configuration file of the same name, in our example config.

After executing the command, aupgrade_product prompts you to enter the following passwords interactively:

  • Database administrator password: The password of the database administrator specified with --dbUser.

  • Admin password: The password of the ADOGRC user Admin.

During the upgrade, aupgrade_product performs the following operations:

  1. Upgrades the database schema.

  2. Exports the existing component settings.

  3. Updates the application library.

  4. Executes the required migration scripts.

  5. Re-imports the component settings.

info

After the database upgrade has completed successfully, the upgraded database can no longer be used with ADOGRC 13.6 or 14.4.

Deploy ADOGRC 15.0​

After successfully upgrading the database, deploy ADOGRC 15.0 in your Kubernetes environment.

note

Deploy ADOGRC 15.0 by following the instructions in Deployment of ADOGRC.

During the deployment, recreate the deployment-specific configuration of your previous installation using the backed-up configuration values from Backup Deployment-Specific Configuration.

note

The chapter Map Deployment-Specific Configuration to Environment Variables explains how the configuration parameters used by previous ADOGRC versions map to the environment variables used by ADOGRC 15.0.

Remove the Previous Installation​

After you have successfully deployed ADOGRC 15.0 and verified that your users can work with the migrated database, you can remove the previous ADOGRC installation.

  • Uninstall the ADOGRC 13.6 or 14.4 application server from the Windows server. You can do this through the control panel.

  • Remove the ADOGRC 13.6 or 14.4 web application from Apache Tomcat.