Configuring Countly


Countly is divided into two parts (frontend and API), both of which have their own additional configuration options that you might want to change when installing Countly.

Location of configuration files:

  • {countlydir}/frontend/express/config.js
  • {countlydir}/api/config.js

Also, some plugins may have their own configuration files, for example:

  • {countlydir}/plugins/drill/config.js

Copy or rename the config.sample.js files located at the same directory to easily create a configuration. Otherwise, the config.js files will be generated by installation scripts with default values.

File config.js by itself is a simple nodejs module file with config object properties inside. An example of config.js content appears as follows:

var countlyConfig = {
    mongodb: {
        host: "localhost",
        db: "countly",
        port: 27017,
        max_pool_size: 500,
	//username: test,
	//password: test
    /*  or for a replica set
    mongodb: {
        replSetServers : [
        db: "countly",
	username: test,
	password: test,
        max_pool_size: 100
    /*  or define as a url
	mongodb: "localhost:27017/countly",
    web: {
        port: 6001,
        host: "localhost",
        use_intercom: true
    production: false,
	path: "",
	cdn: "",
	session_timeout: 2*60*1000

module.exports = countlyConfig;

Configuring Connection to MongoDB

The main thing you need to specify in config.js is the connection setting to your MongoDB in the mongodb property.

You may specify connection settings as a string whose format is described by MongoDB docs.

Here is an example:


You may also define configuration as an object with properties such as:

mongodb: {
        host: "localhost",
        db: "countly",
        port: 27017,
        max_pool_size: 500,
	username: "test",
	password: "test"

In addition, you may define replica sets:

mongodb: {
        replSetServers : [
        replicaName: "rs0",
        db: "countly",
	username: "test",
	password: "test",
        max_pool_size: 100

Note that in order for the MongoDB server to handle incoming connections from a remote server, you will need to modify the bind_ip directive in /etc/mongodb.conf, so it can accept connections from the Countly server.

A Note About Remote Databases

If your Countly instance can successfully connect to the MongoDB instance, then there is no further configuration necessary. You don't need to create any databases or collections - Countly will take care of those.

Configuration Options on the Dashboard

Countly stores configurations in a database, which enables easier use across multiple servers. To change configurations, simply go to Management -> Configurations.

The configuration options in this screen are mostly self-explanatory. You may find each option and description below:

  • Production mode: When enabled, this mode serves minified, combined files.
  • Theme: Select one or more themes here to change the look and feel of the UI.
  • Session timeout in ms: The dashboard session timeout is given in milliseconds. After this amount of time, the user will be forced to logout if they don’t perform any actions.
  • Server URL: This is the full qualified domain name used in outgoing emails.
  • Safer API responses: If disabled, the server will respond successfully without verifying parameters, resulting in a faster response. If enabled, the server will verify the app_key, api_key, etc. parameters and then respond with either an error or success.
  • Maximal Session Duration: Maximum amount of time that should pass before the server closes the session.
  • Track city data: Enable tracking city level data on the dashboard.
  • Max unique event keys: Number of event keys stored on the DB.
  • Max segmentation in each event: Number of maximum segmentations per event.
  • Max unique values in each segmentation: This is the maximum number of unique values in each segmentation.
  • Default Country: Default country used when creating an app with an API, while not providing a country value.
  • Default Category: Default category used when creating an app with an API, while not providing a country value.
  • Logs (debug, info, warning..): Level of debug info to output into the log file under /log.
  • Amount of reports displayed: Amount of reports to display in each crash group's page.

Make the changes you need to the configurations and press the Apply Changes button in the top right corner.

Using Countly from a Subdirectory

If you don’t end up having a separate domain for the Countly installation or you can't use subdomains, you have the option to use Countly from a subdirectory, such as

Using a Subdirectory for the Install Path

Countly is a software that is meant to run on an instance alone. Therefore, using a subdirectory, such as /countly, for installation is not recommended or supported.

If you would prefer to go forward with this option, you will need to change a few settings. First, you will need to change the nginx configuration path, which is usually stored under /etc/nginx/sites-enabled/default, by adding /countly/.

server {
    listen   80;
    server_name  localhost;

    access_log  off;

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

    location = /countly/o {

    location /countly/ {
        proxy_set_header Host $http_host;

Next, restart the nginx server by executing command: /etc/init.d/nginx restart.

Now you need to add the same path to both the frontend and API config.js files.

path: "/countly"

The final step is to restart Countly, so it may reload the new config files, by executing restart countly-supervisor.

Browser Side Configuration

Additionally, there is the {countly}/frontend/express/public/javascripts/countly/countly.config.js file which provides some web end configurations such as:

countlyCommon.DEBUG = false;
countlyCommon.API_URL = countlyGlobal["path"] || "";
countlyCommon.API_PARTS = {
        "w":countlyCommon.API_URL + "/i",
        "r":countlyCommon.API_URL + "/o"
        "w":countlyCommon.API_URL + "/i/apps",
        "r":countlyCommon.API_URL + "/o/apps"
        "w":countlyCommon.API_URL + "/i/users",
        "r":countlyCommon.API_URL + "/o/users"
countlyCommon.DASHBOARD_REFRESH_MS = 10000;
countlyCommon.DASHBOARD_IDLE_MS = 3000000;
countlyCommon.GRAPH_COLORS = ["#88BBC8", "#ED8662", "#A0ED62", "#ed6262", "#edb762", "#ede262", "#62edb0", "#62beed", "#6279ed", "#c162ed", "#ed62c7", "#9A1B2F"];
countlyCommon.CITY_DATA = true;

As you can see, you may set the refresh rate, set some graph colors, or define the API URL end points from this file.

Configure the Shared File System Between Multiple Countly Servers

In cases when you have multiple Countly servers behind a load balancer, you will want them to share files.

If not, then uploading a file, such as an app icon or symbolication file, will only be uploaded to a random server. Also, it might request it from another server which does not have that file.

This is why servers should share these files through a common database named countly_fs, which uses MongoDB GridFS to store and retrieve files.

To do so, you must complete these changes on each Countly server you have behind the load balancer:

1) Edit file countly/api/config.jsYou will need to change the property fileStorage value from fs to gridfs inside countly/api/config.js.

2) Restart the Countly process by running the following:

countly restart

3) Transfer existing uploads (if any) to GridFS

To transfer all existing uploaded files that are already on a disk into a shared filesystem in the database (gridfs), you will need to run the following:

countly fs migrate fs gridfs

Now all servers will be uploading and taking files from MongoDB’s shared file system, called GridFS.

Looking for help?