CleanSpeak Major Version Upgrade (3.x to 4.x)

1. CleanSpeak Major Version Upgrade (3.x to 4.x)

To download or check on the latest updates, please visit your CleanSpeak Account and find the Download link for your license.

If you are upgrading to CleanSpeak version 4.x from 1.x or 2.x, reference 2.x to 3.x for details on getting to 3.x first.

Linux
Windows
Database
Tomcat Removal
Status and metrics authentication changes
Deprecated properties

1.1. Linux

Updating your application is easy if you installed using the RPM or Debian packages. All you need to do is to issue an update command to the dpkg or rpm program and specify the new package file. Here is an example:

Red Hat

$ sudo rpm -U cleanspeak-app-<version>.rpm

Debian

$ sudo dpkg -i cleanspeak-app-<version>.deb

Running the update script will shut down the CleanSpeak service if it is running. The service (now named cleanspeak-app) will need to be restarted after the update is finished.

1.2. Windows

On Windows, the steps required are different. Follow these steps to upgrade your version on Windows:

Download the webapp only bundle
Shut-down your Tomcat or your JEE server
Rename the CLEANSPEAK_HOME/web directory to something meaningful like web-2009-06-07 (this is helpful in case you need to revert to this version of the application)
Extract the update bundle to the CLEANSPEAK_HOME directory. This will place a new directory called web in the directory
Start the service using the new, native HTTP server method. See Start and Stop CleanSpeak for more details on how to start CleanSpeak 4.0 on Windows.

1.3. Database

In most cases, you will not need to upgrade you database manually using the information below. CleanSpeak ships with a system called Maintenance Mode. When you restart CleanSpeak after installing a new bundle using the steps above, CleanSpeak will automatically upgrade your database.

You should always backup your database prior to using Maintenance Mode.

Depending on your current version and the new version you will be updating to you might need to execute one or more SQL scripts to update your database. These scripts are located in the migrations folder inside the Database Schema ZIP file. This file can be downloaded by logging into your CleanSpeak Account and find the Download link for your license, there you will find a package under Database Downloads.

When upgrading your database from a previous version, be sure to only run the scripts located in the migrations folder, the base files mysql.sql and postgresql.sql should only be used during a clean installation when no database schema is present.

Inside of the database schema zip file, you will find the following CleanSpeak 4.x migrations, run in this order, starting with the first migration that is greater than the version you are coming from, and ending with the version that is less than or equal to the target version.

cleanspeak-database-schema
  |
  migrations
    |
    mysql | postgresql
      |
      |- 4.0.0.sql

1.4. Tomcat Removal

As noted in the Release Notes, CleanSpeak 4.0.0 removes Apache Tomcat as the underlying application server. The new cleanspeak-app Debian and RPM package will remove Tomcat libraries and scripts.

The upgrade will leave some Tomcat files intact, including catalina*.log, host-manager*.log, localhost*.log files, and work. You can remove them after your upgrade is complete.
If you previously configured Tomcat with TLS (as opposed to do doing TLS termination at a load balancer in front of CleanSpeak), you will need to configure your certificates and private keys in a different place. Instead of using a JKS keystore, you will need to either configure the PEM text for your certs/keys in the cleanspeak properties file or point the properties file at files containing the certs/keys. See Configuration for more details.
If you customized your session settings with Tomcat, see the cleanspeak-app.session.timeout and cleanspeak-app.session.max-age settings at Configuration for more details.

1.5. Status and metrics authentication changes

In CleanSpeak 4.x, /api/status, /prometheus/metrics, and /status require at least 1 of the following:

Logged in user (via browser)
API key
Request from localhost with cleanspeak-app.local-metrics.enabled set to true in the configuration file

If you have any automated checks monitoring CleanSpeak, don’t forget to take this into consideration.

1.6. Deprecated properties

CleanSpeak 4.0.0 uses the HTTP and HTTPS ports from the 3.x WebService to try and avoid dependent system changes. This is port 8001 by default on a new CleanSpeak 4.0 system or on an upgraded system, whatever was configured as cleanspeak-webservice.http.port.

At your convenience, change the following properties from their non-deprecated names.

cleanspeak-webservice.http.port → cleanspeak-app.http.port
cleanspeak-webservice.https.port → cleanspeak-app.https.port
cleanspeak-webservice.runtime-mode → cleanspeak-app.runtime-mode

Configuration notes the complete list of properties and what is deprecated.