Upgrading the Countly Server

Upgrading to the latest Countly Edition usually does not involve any complicated operations. However, you need to know which version you are upgrading to.

To get the latest Countly Lite package, go to our Github repository.

To get the latest Countly Enterprise package, login to our support system and go to the Enterprise package page. If you don't have an account there, you can sign up for one here.

Before Upgrading to 23.03

OS Version Limitation

Due to limitations in NodeJS (glibc dependency), we will not be able to support some older OS versions, so we are deprecating support for:

• Centos 7
• RHEL 7
• Ubuntu 18

Please upgrade your OS version or make sure it is compatible before upgrading Countly

MongoDB and NodeJS versions

Starting with Countly 23.03, we use MongoDB 6.0 as the default database version and NodeJS 18 as the default NodeJS version.

This means before upgrading, you need to upgrade your MongoDB to 6.0. You can do that via the script we provide or do it yourself manually. The script should be run on the server where your MongoDB runs. And as always take backups, before you upgrade anything. MongoDB should also be upgraded incrementally, so if you're upgrading from MongoDB 4.4, please don't skip 5.0.

To upgrade from MongoDB 4.4 to MongoDB 5.0 run 

• bin/upgrade/23.03/upgrade.mongo.50.sh

To upgrade from MongoDB 5.0 to MongoDB 6.0 run

• bin/upgrade/23.03/upgrade.mongo.60.sh

Then for Countly Server, to upgrade the NodeJS version to 18.x run

• bin/upgrade/23.03/upgrade.nodejs.18.sh

Afterward, run the normal upgrade procedure of all upgrade scripts between your version and 23.03 (including bin/upgrade/23.03/upgrade.sh)

Changes in the mail server configuration

If you provide your email server configuration and overwrite email templates by extending mail.js file in countly/extend/mail.js then you need to modify to comply with new nodemailer changes as provided in this example (basically removing nodemailer-smtp-transport)

Authentication plugins

If you are using any of the authentication plugins like AD/LDAP/Cognito/etc please make sure to upgrade using the package that contains that authentication plugin, because there are some breaking changes there that need to be upgraded.

If you are using SSO plugin which is not released anymore, then create a support ticket to get the updated version of this plugin.

Before Upgrading to 20.11.X

Since Countly 20.11 release, the minimal supported MongoDB version changes to 4.4, and NodeJS version changes to 14.

Nodejs upgrade will be handled by the upgrade script itself, but since MongoDB can exist on separate servers, there are separate scripts to upgrade to MongoDB 4.4

You may upgrade the MongoDB version yourself or rely on the provided scripts to do the upgrade, but in case you are using non-standard settings or authentication, you might need to finish some steps manually.

To upgrade MongoDB from 3.6 to 4.4 you will need to run the following scripts in this order:

• bin/upgrade/20.11/upgrade.mongo.40.sh
• bin/upgrade/20.11/upgrade.mongo.42.sh
• bin/upgrade/20.11/upgrade.mongo.44.sh

You can use these MongoDB upgrade scripts also on separate MongoDB servers without Countly being installed there.

After that do a Regular Upgrade by running the upgrade script bin/upgrade/20.11/upgrade.sh or bin/upgrade/20.11.1/upgrade.sh depending on which version you are upgrading to.

Before Upgrading to 19.X.X

Ensure you are running MongoDB 3.6.

If you are using Countly Enterprise, it includes Remote config plugin which uses new database countly_out. Make sure to add countly user to this database if you implemented authentication in your database.

After that, continue with Regular Upgrade by running the upgrade script bin/upgrade/19.02/upgrade.sh

Before Upgrading to 18.08.X from an Older Version

If you are on a version before 18.08 and would like to upgrade to 18.08.X, this section is for you. In addition to regular upgrade, there are 4 optional scripts to run, depending on your system state, before running regular upgrade scripts mentioned below.

Optional Step 1: Upgrading MongoDB

We have now upgraded our current supported MongoDB version to MongoDB 3.6. Hence, if you are on MongoDB 3.2, you may want to upgrade to MongoDB 3.4, and then to MongoDB 3.6, step by step; you need to set feature compatibility in between. This is not strictly required, but is a highly recommended step as Countly uses some of the functions that come with MongoDB 3.6, which will increase speed to some extent.

You can use the automated script: bin/upgrade/18.08/upgrade.mongo.sh to upgrade MongoDB automatically, but if you have non default installation or modifications like authentication or some other limiting capabilities, it is suggested to go through the upgrade process manually.

Manual Upgrade

For Manual upgrade, if you are using MongoDB older than 3.2, you will need to upgrade to MongoDB 3.2 first.

If you already have MongoDB 3.2, you will need to run the following script after you extract Countly 18.08 package onto the old Countly directory and run the default upgrade.

This will first deploy MongoDB 3.4 and then MongoDB 3.6, one step at a time.

#change to countly directory
cd `countly dir`

#upgrade to 3.4
bash bin/upgrade/18.08/upgrade.mongo.34.sh

#set feature compatability to 3.4
mongo admin --eval "db.adminCommand( { setFeatureCompatibilityVersion: \"3.4\" } )"

#upgrade to 3.6
bash bin/upgrade/18.08/upgrade.mongo.36.sh

#set feature compatability to 3.6
mongo admin --eval "db.adminCommand( { setFeatureCompatibilityVersion: \"3.6\" } )"

If you are on MongoDB 3.4 already, then skip the above steps and follow the below to upgrade to feature compatibility 3.4 and then to MongoDB 3.6. After that, your database is upgraded:

#set feature compatability to 3.4
mongo admin --eval "db.adminCommand( { setFeatureCompatibilityVersion: \"3.4\" } )"

#upgrade to 3.6
bash bin/upgrade/18.08/upgrade.mongo.36.sh

#set feature compatability to 3.6
mongo admin --eval "db.adminCommand( { setFeatureCompatibilityVersion: \"3.6\" } )"

Optional Step 2: Modify MongoDB Authentication

Note: Before running this step, make sure you have extracted Countly 18.08 onto the old Countly directory.

If you have authentication enabled for your MongoDB database, you also need to add countly_fs database to be authenticated with the same username and password as countly database.

Follow these instructions for more information.

Optional Step 3: NodeJS Version Upgrade

Note: Before running this step, make sure you have extracted Countly 18.08 onto the old Countly directory.

New required Nodejs version is Nodejs 8+. Upgrade script should install it automatically, however, if you use another third-party Nodejs version manager, you would need to update it manually to make sure new Countly service uses Nodejs 8+.

Optional Step 4: Cleaning Old Push Collections

Note: Before running this step, make sure you have extracted Countly 18.08 onto the old Countly directory.

Additionally, if you used Push Notifications a lot (e.g., for millions of users), you may want to clear old collections, which are not used any more. You can do this by running the following script, after deploying Countly 18.08:

#change to countly directory
cd `countly dir`

#remove push collections
nodejs bin/upgrade/18.01.1/scripts/push_clear.js

Try removing those collections when server has the most resources (i.e., not during peak time).

Now, you can move forward with Regular Upgrade below.

Regular Upgrade

If you are going to upgrade from a previous version (e.g., 16.06 to 16.12), things are simple - just follow the path below. If there are more than two versions that you need to upgrade (e.g., from 16.02 to 16.12), then please see Skipping Versions When Upgrading section below.

1. Download Countly and extract contents over the current Countly directory, overwriting all existing files

2. Check if there is an upgrade folder for that specific version in bin/upgrade. If there is an upgrade.sh script, then run it, just like the example below (replace 19.02 with your new version):

bash bin/upgrade/19.02/upgrade.sh

If there is no such directory and upgrade.sh script inside that directory, then simply run:

#do upgrade files and restart countly
countly upgrade

Skipping Versions When Upgrading

If you are going to upgrade from a version that was released before the last version (meaning, skipping one version or more), then you will need to upgrade each version one by one, as shown below.

For this, you first need to download the latest release and extract it on your current Countly installation and then go to countly/bin/upgrade folder and execute all consecutive upgrade scripts.

Example: If you upgrade from 18.04 to 19.02, then you should do the following after extracting 19.02 package on top of 18.04:

bash bin/upgrade/18.08/upgrade.sh
bash bin/upgrade/19.02/upgrade.sh

Upgrading from Countly Lite to Countly Enterprise

Countly CLI is already able to upgrade from Countly Lite to Countly Enterprise. You can follow this procedure to complete process:

cd `countly dir`/../
(download enterprise edition package which is provided by us)
countly upgrade ee

Post-Upgrade Checklist

You can ensure that the upgrade was successful by going through the below checklist:

• Upgrade finished without errors
• Countly is accessible and dashboard loads
• New data arriving in Overview (Sessions or users are increasing)
• For Countly Enterprise, you can also check new data arriving in Users -> User Profile list (list changes with latest users)
• New data arriving in Utilities -> Request Logs (new request logs are coming in)
• No errors after starting Countly in countly/log/countly-api.log or top cog -> Server Logs -> API