Configuring Countly


As Countly is divided in two parts: frontend and api, both have it's own additional configuration options, that you might want to change when installing Countly.

Location of configuration files are:

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

As well some plugins may have their own configuration files as, for example.

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

To create configuration simply copy or rename config.sample.js files located at the same directory, or else 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. Example contents of config.js look like:

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: 500
    /*  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

Main thing what you need to specify in config.js are connection setting to your MongoDB in mongodb property.

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

Here is an example:


You can also define configuration as object with properties like:

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

You can also define replica sets:

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

Note that in order MongoDB server to handle incoming connections from a remote server, you need to modify bind_ip directive in /etc/mongodb.conf so it can accept connections from 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 dashboard

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

Configuration options in this screen are mostly self explanatory. You can find each options and descriptions below:

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

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

Using Countly from a subdirectory

If you won't have separate domain for Countly installation or you can't use subdomains, you have an option to use Countly from subdirectory, like

Using a subdirectory for install path

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

To achieve that you would need to change couple of settings. First you need to change nginx configuration path usually stored at /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;

After that restart nginx server by executing command: /etc/init.d/nginx restart

Then you need to add same path to both frontend and api config.js files

path: "/countly"

After that restart your Countly to reload new config files by executing restart countly-supervisor

Browser side configuration

Additionally there is {countly}/frontend/express/public/javascripts/countly/countly.config.js file which provides some web end configurations 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 can set refresh rate, set some graph colors or define API URL end points from this file.

Configure shared file system between multiple Countly server

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

If not, then when uploading files like app icon or symbolication file, it will only upload it to one random server, and when requesting it, it might request it from other server, which does not have that file.

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

To achieve that, you must complete these changes on each countly server you have behind the load balancer:

1) Edit file countly/api/config.js Inside countly/api/config.js you need to change property fileStorage value from default fs to gridfs

2) Restart countly process by running

countly restart

3) Transfer existing uploads (if any) to GridFS

To transfer all existing uploaded files that are already on disk into shared filesystem in the dabatase (gridfs) you need to run

countly fs migrate fs gridfs

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

Was this article helpful?
0 out of 0 found this helpful

Looking for help?