Summary: This section describes the upgrade process for standalone Dashboards. |
If you are using the Dashboards embedded in AIP Console, this step is not required. Instead, please see CAST-RESTAPI-integrated.war upgrade for more information. |
 | Upgrade process | The upgrade process is a "side-by-side upgrade". This means that the new dashboard WAR/ZIP file should be deployed alongside the existing WAR/ZIP file and any settings transferred from the existing to the new. |
|---|---|---|
| Where to run the upgrade? | The process must be run on the host server. |
| Obtain the installation media | Download the latest release of the required CAST Dashboard from CAST Extend. This media contains:
|
| Stop all services | Before starting any upgrade process, you must ensure ALL services are stopped, for example stop Apache Tomcat. |
Obtain the new .WAR file and unzip it to the following location:
CATALINA_HOME\webapps |
This should give you the following file hierarchy, for example when upgrading the CAST Engineering Dashboard from 1.18 to 1.19:
In a "side-by-side" deployment, you will need to transfer the details of your environment (stored in the configuration files such as web.xml/context.xml/other .properties/.xml/.json files) from the old Dashboard to the new. Please be aware that the location, structure and content of configuration files may have changed between releases, so you should not perform a merge or overwrite configuration files (unless specifically requested to do so in the instructions below) - instead you must manually update the new configuration files with the details from the old configuration files.
The following files may contain configuration that you will need to copy to the equivalent file in the newly deployed Dashboard:
CATALINA_HOME\webapps\<dashboard>\META-INF\context.xml CATALINA_HOME\webapps\<dashboard>\WEB-INF\authorizations.xml CATALINA_HOME\webapps\<dashboard>\WEB-INF\domains.properties CATALINA_HOME\webapps\<dashboard>\WEB-INF\license.key >>> only for the Engineering Dashboard. This file will not exist in the new Dashboard and can therefore be copied over as is. CATALINA_HOME\webapps\<dashboard>\WEB-INF\license.xml CATALINA_HOME\webapps\<dashboard>\WEB-INF\log4j2.xml CATALINA_HOME\webapps\<dashboard>\WEB-INF\report.properties CATALINA_HOME\webapps\<dashboard>\WEB-INF\roles.xml CATALINA_HOME\webapps\<dashboard>\WEB-INF\security.properties CATALINA_HOME\webapps\<dashboard>\WEB-INF\users.properties If you have added custom languages, these can be found in the following folders: CATALINA_HOME\webapps\<dashboard>\portal\locales CATALINA_HOME\webapps\<dashboard>\engineering\locales |
If you have made configuration changes to .JSON files to create custom tiles or layout and you want to retain those changes in the new version of the Dashboard, you can re-use old .JSON files with the new Dashboard, however, please note that doing so will mean that you will not benefit from any improvements or features added to the current release of the Dashboard. Files that may contain customizations are listed below:
Engineering/Security Dashboard CATALINA_HOME\webapps\<dashboard>\engineering\resources\ed.json Health Dashboard CATALINA_HOME\webapps\<dashboard>\portal\resources\app.json CATALINA_HOME\webapps\<dashboard>\portal\resources\cmp.json CATALINA_HOME\webapps\<dashboard>\portal\resources\internal\app-navigation.json |
In ≥ 1.23, the app-navigation.json file has been removed. It is no longer used. |
Undeploy the existing war file from Apache Tomcat - you can use Apache Tomcat manager to do this, or simply delete the relevant folder and file in CATALINA_HOME\webapps. This step is optional and you may wish to leave this in place until the new dashboard is fully tested and working.
If you use a specific naming convention to access the dashboards, you may need to rename the .WAR file and its corresponding folder (the two must match). The name of these two items forms the URL to access the dashboards:
Restart Apache Tomcat and ensure that the webapp has started correctly using Apache Tomcat manager:
Browse to your Dashboard URL, login and check that you can access the data you require.
Obtain the new .WAR file and unzip it to the following location:
CATALINA_HOME\webapps |
This should give you the following file hierarchy, for example when upgrading the CAST Engineering Dashboard from 1.23 to 2.0.0:
In a "side-by-side" deployment, you will need to transfer the details of your environment (stored in the configuration files such as web.xml/context.xml/other .properties/.xml/.json files) from the old Dashboard to the new. Please be aware that the location, structure and content of configuration files HAS CHANGED in the 2.x WAR files, so you should not perform a merge or overwrite configuration files (unless specifically requested to do so in the instructions below) - instead you must manually update the new configuration files with the details from the old configuration files.
The following files may contain configuration that you will need to copy to the equivalent file in the newly deployed Dashboard:
| 1.x WAR file | 2.x WAR file | Notes |
|---|---|---|
| \META-INF\context.xml | Does not exist. Use new sections in \WEB-INF\classes\application.properties. | Configuration has changed. Refer to the following documentation (Step 2) for more information: |
\WEB-INF\authorizations.xml | \WEB-INF\classes\authorizations.xml | No change in configuration method. See Data authorization. |
| \WEB-INF\domains.properties | \WEB-INF\classes\domains.properties | Configuration has changed. Refer to the following documentation (Step 2) for more information: |
| \WEB-INF\license.key | Only for the Engineering Dashboard. This file will not exist in the new Dashboard and can therefore be copied over as is to: \WEB-INF\classes\license.key | No change in configuration method. See Dashboard Service license key configuration. |
| \WEB-INF\license.xml | \WEB-INF\classes\license.xml | No change in configuration method. See Dashboard Service license key configuration and Data authorization. |
| \WEB-INF\log4j2.xml | Does not exist. Use \WEB-INF\classes\log4j2-spring.xml | No change in configuration method. See Configuring the Log and Audit Trail. |
| \WEB-INF\report.properties | Does not exist. Use equivalent section in \WEB-INF\classes\application.properties. | No change in configuration method. See CAST Report Generator - CAST Report Generator for Dashboards. |
| \WEB-INF\roles.xml | \WEB-INF\classes\roles.xml | No change in configuration method. See User roles. |
| \WEB-INF\security.properties | Does not exist. Use equivalent section in \WEB-INF\classes\application.properties. | Configuration has changed. Refer to the following documentation: User authentication. |
| \WEB-INF\users.properties | \WEB-INF\classes\users.properties | No change in configuration method. See User authentication. |
| \engineering\resources\ed.json | WEB-INF\classes\config\ed\ed.json | If you have made configuration changes to .JSON files to create custom tiles or layout and you want to retain those changes in the new version of the Dashboard, you can re-use old .JSON files with the new Dashboard, however, please note that doing so will mean that you will not benefit from any improvements or features added to the current release of the Dashboard. |
\portal\resources\app.json | WEB-INF\classes\config\hd\app.json | |
| \portal\resources\cmp.json | WEB-INF\classes\config\hd\cmp.json | |
| \portal\resources\internal\app-navigation.json | Does not exist (withdrawn in ≥ 1.23). | - |
Undeploy the existing war file from Apache Tomcat - you can use Apache Tomcat manager to do this, or simply delete the relevant folder and file in CATALINA_HOME\webapps. This step is optional and you may wish to leave this in place until the new dashboard is fully tested and working.
If you use a specific naming convention to access the dashboards, you may need to rename the .WAR file and its corresponding folder (the two must match). The name of these two items forms the URL to access the dashboards:
Restart Apache Tomcat and ensure that the webapp has started correctly using Apache Tomcat manager:
Browse to your Dashboard URL, login and check that you can access the data you require.
From release 2.x onwards, CAST is delivering a ZIP file for each CAST Dashboard, alongside the traditional WAR file that has always been delivered. The ZIP file is a method of deploying the CAST Dashboards based on Spring Boot and does not require a web application server (the application server is embedded in the ZIP itself). The aim of the ZIP file releases is to simplify and speed up the deployment of the CAST Dashboards. The deployment and configuration of the 2.x Spring Boot based dashboards differs slightly to the steps required for a traditional WAR file, mostly due to the fact that the files have moved and some have been removed.
To transition from 1.x WAR to 2.x ZIP is relatively simple although there is no managed "upgrade" process. You can repurpose the existing server hosting Apache Tomcat if necessary.
Obtain the new .ZIP file and unzip it to any location on the host server.
You will now need to transfer the details of your environment (stored in the configuration files such as web.xml/context.xml/other .properties/.xml/.json files) from the old Dashboard to the new. Please be aware that the location, structure and content of configuration files HAS CHANGED in the ZIP files, so you should not perform a merge or overwrite configuration files (unless specifically requested to do so in the instructions below) - instead you must manually update the new configuration files with the details from the old configuration files.
Use the following table to find the location of the equivalent configuration files in the new 2.x ZIP:
| 1.x WAR file | 2.x ZIP file | Notes |
|---|---|---|
| \META-INF\context.xml | Does not exist. Use new sections in <unpacked_zip>\configurations\application.properties. | Configuration has changed. Refer to the following documentation (Step 2) for more information: |
\WEB-INF\authorizations.xml | <unpacked_zip>\configurations\authorizations.xml | No change in configuration method. See Data authorization. |
| \WEB-INF\domains.properties | <unpacked_zip>\configurations\domains.properties | Configuration has changed. Refer to the following documentation (Step 2) for more information: |
| \WEB-INF\license.key | Only for the Engineering Dashboard. This file will not exist in the new Dashboard and can therefore be copied over as is to: <unpacked_zip>\configurations\license.key | No change in configuration method. See Dashboard Service license key configuration. |
| \WEB-INF\license.xml | <unpacked_zip>\configurations\license.xml | No change in configuration method. See Dashboard Service license key configuration and Data authorization. |
| \WEB-INF\log4j2.xml | Does not exist. Use <unpacked_zip>\configurations\log4j2-spring.xml | No change in configuration method. See Configuring the Log and Audit Trail. |
| \WEB-INF\report.properties | Does not exist. Use equivalent section in <unpacked_zip>\configurations\application.properties. | No change in configuration method. See CAST Report Generator - CAST Report Generator for Dashboards. |
| \WEB-INF\roles.xml | <unpacked_zip>\configurations\roles.xml | No change in configuration method. See User roles. |
| \WEB-INF\security.properties | Does not exist. Use equivalent section in <unpacked_zip>\configurations\application.properties. | Configuration has changed. Refer to the following documentation: User authentication. |
| \WEB-INF\users.properties | <unpacked_zip>\configurations\users.properties | No change in configuration method. See User authentication. |
| \engineering\resources\ed.json | <unpacked_zip>\configurations\config\ed\ed.json | If you have made configuration changes to .JSON files to create custom tiles or layout and you want to retain those changes in the new version of the Dashboard, you can re-use old .JSON files with the new Dashboard, however, please note that doing so will mean that you will not benefit from any improvements or features added to the current release of the Dashboard. |
\portal\resources\app.json | <unpacked_zip>\configurations\config\hd\app.json | |
| \portal\resources\cmp.json | <unpacked_zip>\configurations\config\hd\cmp.json | |
| \portal\resources\internal\app-navigation.json | Does not exist (withdrawn in ≥ 1.23). | - |
To start the dashboard, run the following file:
<unpacked_zip>\startup.bat <unpacked_zip>\startup.sh |
By default the dashboard is configured to run on port 8080. Use the following URL - where <server_name> is equal to the host name of the current server to access the dashboard. If you are testing on the server itself, you can use http://localhost:8080:
http://<server_name>:8080 |
|
Undeploy the existing war file from Apache Tomcat - you can use Apache Tomcat manager to do this, or simply delete the relevant folder and file in CATALINA_HOME\webapps. This step is optional and you may wish to leave this in place until the new dashboard is fully tested and working.