Self-hosted Installation FAQ


You may either install Countly on-premises (i.e., self-hosted) or let Countly handle the deployment, maintenance, and backup procedures for you. This FAQ addresses commonly asked questions regarding the self-hosted installation of Countly.

Where can I download the Countly server and client libraries?

While downloading from Github, we suggest you use the latest release, as the main branch is used for developing the next version and may be unstable.

Note that Countly Enterprise is only downloadable after purchase.

How much time does it take to install Countly and the SDKs?

If your server has all the requirements, it takes approximately 10 minutes to install Countly and to get ready to start collecting data from devices. Follow the instructions in the Server Installation Manual. Note that installation and configuration do not require any developer skills, rather just a dedicated/virtual server for this purpose.

In order to integrate the SDK, you will need to know your KPIs before integration. This includes the events you want to track, and whether you are going to implement Views and such. Depending on the list and analysis, this may take a few days.

Countly Enterprise customers have the right to rebrand Countly. While simple rebranding (custom logo, custom colors, etc.) takes less than a day to complete, complex rebranding (customization of menus, CSS modification, single-sign-on) would take longer.

If you have an iOS application, please take into consideration the submission to the Apple Appstore, as you have been including the Countly SDK in your iOS app.

What are the system requirements?

We develop, test, and use Countly on Ubuntu (for Countly Lite / Enterprise) and Red Hat Enterprise Linux (for Countly Enterprise). A decent Linux machine can handle several hundreds (if not thousands) of requests per second. Depending on the load, as a minimum, you will need at least 1 CPU server with at least 1 GB RAM dedicated to mobile analytics, and at least 2 GB RAM for push notifications. You will also need to add swap space for cases where memory is not sufficient for MongoDB.

For exceedingly large amounts of traffic (several billions of requests per month), we sell and support Countly Enterprise, which scales horizontally using sharding technologies as your business grows.

64-bit support only

Due to MongoDB and 32-bit limitations, we only support new installations on 64-bit servers.

How can I keep the system up-to-date?

You may download the new version and install it on your server using the Countly upgrade script. Countly Lite also includes a plugin to automatically update from Github.

How to troubleshoot Countly Mail Config if it does not work after the upgrade?

You should always first check the port number, and the default port number has changed from 25 to 587. Then you can refer here, for more information.


Which hosting provider do you suggest?

Any will do. We carry out our tests on Google Cloud, Amazon, and Digital Ocean. Make sure you install Countly on a freshly installed, vanilla operating system without any servers running on it (e.g., LAMP stack, LEMP stack, etc.).

Is it possible to use MongoDB Atlas with Countly?

You may go with MongoDB Atlas, which is a SaaS database solution from MongoDB. In this case, please get in touch with us beforehand for best practices and the necessary configuration advice.

Should I install Countly on a clean instance?

Short answer: Yes

Long answer: Countly is an analytics platform that installs several modules from trusted sources that we should know of, and when there is an issue with underlying core functions (e.g., MongoDB, Node, or Nginx), it becomes hard for us to understand where the issue stems from. Another reason is that we expect Countly should solely be running on the instance where it is installed.

How much bandwidth does the Countly SDK consume?

Every 60 seconds the Countly SDK connects to the server and updates connection information. Each connection sends approximately 500 bytes of data from the SDK to Countly to be written to the database. Therefore, the network overhead is very negligible.

What's the recommended installation directory?

A directory to install the external package (e.g.,/var directory, /usr/local, etc.) is just fine. If you happen to have a setup that reveals some folder to public access (for ex. public_html folder), you may want to avoid extracting Countly there.

Do I need a mail server?

Countly needs an MTA to send emails created by the admin to the user. Countly’s automated installer uses Sendmail by default.

How do I install an SSL certificate?

Out of the box, Countly uses port 80 and no SSL. If you prefer to encrypt communication and use HTTPS in favor of HTTP between devices and web pages and your server, you'll need to configure your nginx.conf file under /etc/nginx. Change the location of the ssl_certificate_key parameter below. Ensure the SSL certificate key is located under a directory that is not visible from the outside.

        ssl_certificate_key /PATH_TO_KEY.key;
        server_name  localhost;

        location = /i {
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Real-IP $remote_addr;

        location ^~ /i/ {
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Real-IP $remote_addr;

        location = /o {

        location ^~ /o/ {

        location / {
                proxy_set_header Host $http_host;

Is it possible to run the dashboard and the database on different servers to increase security?

Countly has a server parameter for both app.js and api.js configuration files (/frontend/express/config.js and /api/config.js) to make it possible to run the dashboard and the application on different servers (defaults to localhost).

I installed Countly Lite, and I would like to install Countly Enterprise on top. How can I do this?

When you install Countly Lite and would like to install the same version of Countly Enterprise on top, just run countly upgrade ee. For example, when you have Countly Lite v22.03 and would like to upgrade to Countly Enterprise v22.03.

If you would like to install a newer Countly Enterprise version on top of an older Countly Lite version, you should run upgrade scripts for each Countly Lite version, as shown here. Once the Countly Lite version matches your targeted Enterprise version, run countly upgrade ee. This is the case when, for example, you are upgrading from Countly Lite v21.10 to Countly Enterprise v22.09.

Looking for help?