Countly Documentation

Countly Resources

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

Installing Countly server


Countly can be installed on a Linux server (see system requirements for more information). By default, Node.js (the web server Countly needs) will run on port 80 or 443 (for HTTPS), so make sure those ports are free and not blocked (as in Amazon AWS case)

Ubuntu flavors

Ubuntu flavors (eg. Kubuntu, Lubuntu) are not supported.

Method 1: One liner installation

The following command will download and install Countly Community Edition on your Ubuntu or CentOS server.

sudo su - 
wget -qO- | bash
sudo su -
wget -qO- | bash -s dev

Method 2: One click installation via Digital Ocean

If you have a Digital Ocean account and want to install Countly Community Edition, create a droplet using this link. Upon selecting a plan and a datacenter region, your Countly instance is ready to go!

Method 3: Downloading via Github or package installation

As an alternative method, you can download Countly Community Edition via Github:

Note: Enterprise Editions source code is not available for public and is downloaded from Enterprise Edition customer private repository. However, installation procedures for both editions are the same, as follows.

Extract Countly package to a directly of your taste (e.g under /usr) - do not use /root folder for this purpose. Then, fire the easy installation script that comes with Countly, which will work both for Ubuntu or RHEL/CentOS:

sudo su - 

Disable SELinux

Disable SELinux on Red Hat or CentOS if it's enabled. Countly may not work on a server where SELinux is enabled. In order to disable SELinux, run "setenforce 0".

Installation will take between 10-15 minutes. Using your browser, go to http://YOUR_SERVER_IP_OR_DOMAIN in order to create your admin account and login to your dashboard. Also do not forget to download client SDKs.

64-bit support only

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

Method 4: Installation via Docker

To help developers easily try Countly, we provide ready-to-use Docker images for Countly Community Edition.

Docker images are for evaluation only

Note that Countly Community Edition docker images are for evaluation purposes only.

Countly image can be fetched from Docker Hub:

docker pull countly/countly-server

Countly uses Baseimage which in turn uses runit to manage multiple processes inside docker container, including Countly NodeJS, Nginx and MongoDB.

Once image is pulled, you can run it by executing following command:

docker run -d -p 32768:80 countly/countly-server

Above, -d daemonizes container, and -p connects port 32768 of host to port 80 of container. You need to connect port 443 if you would like to use Countly SDKs over HTTPS.

Also note that you might want to mount host folder for MongoDB which lives inside the container to persist your data. This is required, since if you don't do the following, data that you collect inside MongoDB will be lost if you stop Docker.

mkdir /var/data/mongodb
docker run -d -P -v /var/data/mongodb:/var/lib/mongodb countly/countly-server

This will mount host's /var/data/mongodb to container at required path /var/lib/mongodb.

Server logs can be checked using standard docker logs command.

MongoDB-less docker image

Countly also provides a Dockerfile-core (see github repository root) which can be used to generate an image without MongoDB inside. Yet there's no standard image available at Docker Hub.

Docker image configuration

Countly docker container can be configured either by extending our standard image and overriding api/config.js & frontend/express/config.js, or by using environment variables.

Environment variables have a special format: COUNTLY_CONFIG_APP_OPTION, where APP is either API, or FRONTEND and OPTION is a path of your configuration option in a respective config.js file (each nesting level is also separated by _). For example, to override MongoDB server address & maximum pool size in api/config.js and set it as follows:

var countlyConfig = {
    mongodb: {
        host: "",
        max_pool_size: 1000,

... you'll need to specify 2 environment variables for API app & at least 1 variable for FRONTEND. For FRONTEND we can set MongoDB server and leave pool size default:


Rebuilding the image

In case you modify Countly distributions, rebuilding docker image is quite simple. The only trick is to set MongoDB server location, so that installation script​ could connect to it. For example, for the case without MongoDB and using local IP address for MongoDB:

docker build --build-arg COUNTLY_CONFIG_API_MONGODB_HOST= --build-arg COUNTLY_CONFIG_FRONTEND_MONGODB_HOST= -f Dockerfile-core .

Running Countly from a subdirectory

It is also possible to run Countly from a subdirectory. Follow those instructions to configure this.

Configure DNS

While Countly server will work without a DNS, it's suggested that you assign a DNS A record to your server, so you do not have to memorize IP address, like

Configure email delivery

Due to potential spam issues, you need make sure that you configure your DNS records (explained below), so that emails sent from Countly (e.g when you add a new user, or daily/weekly email reports) can be sent and not caught by SPAM preventions.

Here are a few important things you should check first:

  1. Make sure your ISP have a reverse DNS record entered to associate the domain names and IP addresses you send mail from. Test your Reverse PTR record here. If your ISP does not enter the proper reverse DNS pointer record, it's very unlikely any of your email will be delivered.

  2. Is your domain's SPF record correct? Test your SPF record here. Note that TXT is the correct official record type for SPF.

  3. Is your domain's DKIM record correct? This will significantly improve email deliverability. Test your DKIM record here.

  4. If you run your own mail server, check to make sure the IPs of your mail server are not on any email blacklists. Also verify that it is definitely sending a fully-qualified hostname that resolves in DNS in its HELO message. If not, this will cause your email to be rejected by many mail services.

We highly recommend you send a test email to to verify that all the above is working correctly.

Using a 3rd party email server

If you want to use a 3rd party email server and instead not use Countly server's email abilities, do the following:

  1. Rename this file (/extend/mail.example.js in your Countly directory) to /extend/mail.js.
  2. Add your email server information. An example is provided below:
module.exports = function(mail){
    //define this if you need to send email from some third party service
    mail.smtpTransport = nodemailer.createTransport(smtpTransport({
        host: "",
        secureConnection: true,
        port: 2525,
        auth: {
            user: "your-mailserver-username",
            pass: "your-mailserver-password"

Configure monitoring for your server

When your server has a problem (e.g lack of enough RAM, lack of swap space, running out of disk etc), chances are Linux kernel will kill some of the processes, or Countly won't work properly. In order to make sure you have a healthy and stable server, we suggest that you use one of monitoring and alerting solutions like Server Density, Nagios or New Relic.

Making Countly more secure

We have a list of security & privacy recommendations, together with guidelines on how to ensure a secure deployment. You can read it here.

Installing Countly server

Suggested Edits are limited on API Reference Pages

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