Countly 27 adds the new version of the Countly dashboard next to the classic version. After you upgrade a self-hosted server, both versions run on your domain, and every user can switch between them. In most cases, the upgrade does this for you. This article explains what the upgrade changes, the one setting it can need from you, and what to check afterwards.
Availability
This article is for administrators of self-hosted Countly servers that run on Kubernetes (Helm) or Docker Compose, Komodo included. If Countly hosts your server, Countly does the upgrade and the setup for you.
Understanding What the Upgrade Changes
Countly 27 serves both versions on one address. Countly calls this the UI mode combined. Each user starts on the classic version, opens the new version from the Try the new version card or link, and can go back at any time. Countly remembers each user's choice.
The upgrade moves your server to combined, unless you chose a different mode yourself. Both versions read the same data, so the upgrade does not move, copy, or delete data.
| You run today | After the upgrade | What you need to do |
|---|---|---|
| 26.01 on Helm | Both versions | Add a JWT secret before the upgrade. Without it, the upgrade stops and tells you. |
| 26.01 on Docker Compose | Both versions | Nothing. The migration to Docker Compose creates the JWT secret. |
| 26.10, no UI mode chosen | Both versions | Make sure the server has a JWT secret. A Docker Compose server set up with 26.10 has one already. |
| 26.10, a UI mode you chose yourself | The same mode | Nothing. If you want both versions on your domain, change the mode to combined. |
Adding the JWT Secret
The new version signs users in with a token, and Countly signs each token with a JWT secret. The secret is a random value of 32 characters or more. Without it, the new version cannot sign anyone in, so Countly does not start it.
To create a secret, run this command:
openssl rand -hex 32Then add the value to your deployment configuration:
- Helm:
secrets.common.jwtSecretin your values file. - Docker Compose:
COUNTLY_CONFIG__API_JWT_SECRETin/etc/countly/.env.
If the secret is missing, Countly tells you. On Helm, the upgrade stops before anything changes. On Docker Compose, the server keeps only the classic version, or the upgrade stops and names the missing setting.
Keep the JWT secret
Add the JWT secret once and do not change it. A new value signs every user out of the new version.
Checking the Server After the Upgrade
The Switch
Open your domain and sign in. You see the classic version. To open the new version, use the Try the new version card on Home, or open /ui-switch/new on your domain. To go back, open the profile menu in the new version and select Dashboard version > Classic.
The switch needs Countly at the root of your domain. If you serve Countly under a path, such as example.com/countly, the switch is not available.
The Invitation in the Classic Version
The Try the new version card on Home and the link in the Sidebar invite users to the new version. A setting in the classic version, Switch to the new dashboard, decides when they show:
- As Countly rolls it out (default): the server asks Countly's servers if it should show the invitation. This needs internet access. If the server gets no answer, the invitation stays hidden.
- Always offer it: the invitation always shows. Choose this on a server without internet access.
- Never offer it: the invitation never shows.
This setting changes only the invitation. The way back from the new version always shows.
Custom nginx Files (Docker Compose)
The upgrade keeps your own copies of the files in vhosts/. A copy made before Countly 27 does not know the new version. In that case, nginx does not start, names the file, and shows how to update it. Update the file to the version that comes with Countly 27, then run make up again.
Choosing a Different UI Mode
Most servers keep combined. If you want a different setup, choose one of these modes:
| Mode | Your domain shows | Use it when |
|---|---|---|
combined (default) | Both versions, each user chooses | Users move to the new version at their own pace. |
new | The new version only | Every user must use the new version. There is no way back to the classic version. |
disabled | The classic version only | You are not ready for the new version yet. This mode needs no JWT secret. |
To change the mode, set it where your deployment reads its configuration, then apply it:
- Helm: set
ui.modein your values file, then runhelm upgrade. - Docker Compose: set
COUNTLY_UI_MODEin/etc/countly/.env, then runmake up. - Komodo: set
COUNTLY_UI_MODEin the stack environment, then click Deploy.
On Docker Compose, every app container restarts when the mode changes. Plan a few minutes. MongoDB, ClickHouse, and Kafka do not restart.
Single sign-on in the new mode
In new, only the new version signs users in, and the classic sign-in addresses stop working. Before you change to new, register https://<your domain>/v2/<provider>/callback with each identity provider. The combined mode keeps the classic addresses.
Frequently Asked Questions
I upgraded, but my users do not see the switch. Why?
Check these points in order. First, the server must have a JWT secret, or it shows only the classic version. Second, the UI mode must be combined. A mode you chose before the upgrade stays. Third, on a server without internet access, set Switch to the new dashboard to Always offer it. Last, Countly must be at the root of your domain, not under a path.
How do I make every user start on the new version?
Use the mode new. In combined, a user who never switched starts on the classic version.
Can I go back to the classic version only?
Yes. Set the mode to disabled and apply it. Your data does not change. If you also go back to Countly 26, set the mode you had on 26 first, because Countly 26 does not know combined or new.
I run the two versions on two hostnames today. Do I have to change that?
No. The modes subdomain and primary stay after the upgrade. To use one address for both versions, change the mode to combined and remove the second hostname settings. When nothing links to the second hostname anymore, remove its DNS record and its name on the certificate.
Do my users lose data or saved work?
No. Both versions read and write the same data. The mode changes only which screens your users see.