Countly Documentation

Countly Resources

Here you'll find comprehensive guides to help you start working with Countly as quickly as possible.

Installation FAQ

Self-hosted or private cloud options available

You can either install Countly on-premises (e.g self-hosted), or let Countly handle the deployment, maintenance and backup procedures for you. This FAQ includes questions regarding self-hosted installation of Countly.

Where can I download Countly server and client libraries?

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

Note that Enterprise Edition is only downloadable after purchase.

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

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

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

Enterprise Edition 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 more.

In case you have an iOS application, please take into consideration of submission to Apple Appstore, since you have been including Countly SDK in your iOS app.

What are the system requirements?

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

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

64-bit support only

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

Which hosting provider do you suggest?

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

Is it possible to install on Digital Ocean?

Yes - and we have a fantastic Countly Digital Ocean Installer, right here. Go to this link, select a few parameters and hit "Install Countly" button. In under 10 minutes, you'll have your Countly instance running!

Is it possible to use MongoDB Atlas with Countly?

You may go with MongoDB Atlas, a SaaS database solution from MongoDB. In this case, please get in touch with us beforehand for best practices together with necessary configuration advise.

What are main differences between self-hosted and private cloud deployment?

There are a few differences that you would need to look at before choosing a deployment option.

Private cloud

Self hosted

Server setup

Countly is responsible for setup and configuration of: operating system, Countly server, MongoDB (including replica set support), Ngnix, and additional components.

Countly provides to the customer recommended specifications and configurations for servers that will be used to host the software. Customer obtains and configures the servers according to these recommendations and installs supported Linux OS along with Countly.


Countly is responsible for maintenance of the software and for the end to end health of servers and network connectivity. Network related issues by 3rd party hosting companies are handled by them accordingly.

Customer is responsible from end to end health of servers and network connectivity. Any maintenance related to Countly software is executed by customer according to directions provided by Countly.


Countly establishes and executes backup procedures

Customer establishes and is responsible for backup procedures.


Upgrades are automatically applied and tested by Countly after a new version is released.

Upgrades are included as part of the subscription plan and are the responsibility of the customer to install and test. Countly provides documentation for installing any upgrades. Typically there are 3 upgrades annually.


Server monitoring is done using a 3rd party professional monitoring service. In case an issue occurs, support staff is alerted immediately.

Server monitoring is implemented by customer and customer is responsible for informing Countly about any app-level issues detected. Countly can make recommendations for server monitoring services if requested.


Countly has immediate and full access to the customer's instance to assist with investigating, recreating, diagnosing, and resolving any reported issues.

Customer assists Countly support team by documenting any issues, providing additional information as requested by Countly, and authorizing and approving remote access to the software upon Countly's request.

Which browsers does Countly run on?

We test Countly on Chrome, Firefox and IE9+. A recent(ish) version of these modern browsers work well. We do not support IE8.

What's the programming language and underlying infrastructure?

Countly relies on MongoDB, Node.js and Nginx. Main programming language is Javascript.

Why did you choose MongoDB and Node.js?

We searched for the most reliable and performance-centric stacks and chose our stack carefully. MongoDB and Node.js are used across the globe, powering and trusted by tens of thousands of companies, ranging from Foursquare to Adobe, eBay to McAfee.

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 that Countly should solely be running on the instance that it is installed.

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

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

How much bandwidth does Countly SDK consume?

Every 60 seconds, Countly SDK connects to server and updates connection information. Each connection sends approximately 500 bytes of data from 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 external package (eg /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 to the user created by admin. By default, Countly automated installer uses Sendmail.

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 & web pages and your server, you'll need to configure your nginx.conf file under /etc/nginx. Change the location of ssl_certificate_key parameter below. Make sure SSL certificate key is located under a directory that is not visible from 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;

I installed Countly on an Amazon AWS but I cannot reach dashboard

By default, Amazon doesn't allow you reach port 80. You should allow incoming conections to port 80 via security group on your dashboard as you create your Amazon instance.

I installed Countly on Google Cloud but server cannot send email

All outbound known mail sending ports are blocked on Google Cloud instances, due to large amount of abuse, and you need to use third party services to send out emails. Google recommends that you use a mailing service mentioned in their documentation.

Is it possible to run dashboard and 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 dashboard and application on different servers (defaults to localhost).

I installed Countly, but forgot my password

When you first installed Countly, chances are you haven't yet setup DNS or MX records, so "forgot password" link won't work. In this case, you should create a global admin user from your console, using the following command:

# countly add_user <username> <password>

Then, login to your dashboard with this user and password. You can then change the password of the user you have created before.

How can I restart Countly?

In order to restart Countly, type the following as root:

# countly stop
# countly start

How do I reinstall Countly?

Deleting the countly directory, extracting the new package to the same directory and running countly upgrade should do the trick. This is explained in Upgrading Countly documentation. If you have an old server, we suggest you read this documentation first.

I installed CE, and I want to install EE on top. How do I do this?

When you install Community Edition and then want to install the same version of Countly Enterprise Edition on top, just run countly upgrade.

If you want to install a newer Enterprise Edition on top of Community Edition, then you should run upgrade scripts for each version, as shown here.

Installation FAQ

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.