Configuring HTTPS and SSL

HTTPS and SSL for Nginx

Configure your Countly installation to use the HTTPS connection you need to modify your Nginx configuration.

The directory of Nginx configuration depends on the operating system you use, but for our recommended Ubuntu, the Nginx configuration is under /etc/nginx/sites-available/default.

If you would like to have an HTTPS-only connection, then replace the current server clause with the one provided, assuming you would like to have HTTP and HTTPS simultaneously, then add this server clause to the configuration file:

server {
  listen   443;
  server_name  localhost;
  access_log  off;
  ssl on;
  ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
  ssl_prefer_server_ciphers on;
  ssl_ciphers 'kEECDH+ECDSA+AES128 kEECDH+ECDSA+AES256 kEECDH+AES128 kEECDH+AES256 kEDH+AES128 kEDH+AES256 DES-CBC3-SHA +SHA !aNULL !eNULL !LOW !kECDH !DSS !MD5 !EXP !PSK !SRP !CAMELLIA !SEED';
  ssl_session_cache builtin:1000 shared:SSL:10m;
  ssl_stapling on;

  # Use 2048 bit Diffie-Hellman RSA key parameters
  # (otherwise Nginx defaults to 1024 bit, lowering the strength of encryption 
  # when using PFS)
  # Generated by OpenSSL with the following command:
  # openssl dhparam -outform pem -out /etc/nginx/ssl/dhparam2048.pem 2048
        
  ssl_dhparam /etc/nginx/ssl/dhparam2048.pem;
  ssl_certificate /etc/nginx/ssl/certificate.crt;
  ssl_certificate_key /etc/nginx/ssl/server.key;

  location = /i {
    proxy_pass http://127.0.0.1:3001;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Real-IP $remote_addr;
  }
	
  location ^~ /i/ {
    proxy_pass http://127.0.0.1:3001;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Real-IP $remote_addr;
  }

  location = /o {
    proxy_pass http://127.0.0.1:3001;
  }
	
  location ^~ /o/ {
    proxy_pass http://127.0.0.1:3001;
  }

  location / {
    proxy_pass http://127.0.0.1:6001;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Real-IP $remote_addr;
  }
}

This configuration uses the latest and most secure protocols and ciphers.

If your localhost is already taken, replace the server_name value from localhost to the name you would like to use.

Also check that the ssl_certificate points to your certificate bundle and that ssl_certificate_key points to your server key.

If you would like to create a self-signed ssl_certificate and ssl_certificate_key simply run:

sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/nginx/ssl/server.key -out /etc/nginx/ssl/certificate.crt

By default, the Nginx server will use 1024-bit long RSA key parameters to comply with the latest security recommendations. We recommend switching to 2048 bits.

That means you would need to generate your own 2048-bit long params. To do so, run:

openssl dhparam -outform pem -out /etc/nginx/ssl/dhparam2048.pem 2048

(this command could take some time, around a few minutes).

Then set ssl_dhparam to point to your generated dh param file (it already points to the right path with this command).

If you receive the "/etc/nginx/ssl/dhparam2048.pem: No such file or directory" error, run the following code to create the needed directory:

sudo mkdir /etc/nginx/ssl
sudo chown -R root:root /etc/nginx/ssl
sudo chmod -R 600 /etc/nginx/ssl

Then generate your own 2048-bit long params again.

openssl dhparam -outform pem -out /etc/nginx/ssl/dhparam2048.pem 2048

If you replaced your current configuration with the example provided, then you will also want to redirect all HTTP traffic to HTTPS. To do so, add this server clause in the beginning of the configuration file:

server {
        listen      80;
        server_name localhost;
        access_log  off;
        rewrite ^ https://$host$request_uri? permanent;
}

Replace yourdomain.com with your domain or the IP address where your Countly server is located. Also, use the same value for localhost that you used in the previous example.

If you did not replace your current configuration with the provided example and would like to Force Redirect Dashboard traffic to HTTPS, modify the "location /" section for the 80 port as shown below:

server {
	listen   443;
	server_name  localhost;
	access_log  off;
  ssl on;
  ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
  ssl_prefer_server_ciphers on;
  ssl_ciphers 'kEECDH+ECDSA+AES128 kEECDH+ECDSA+AES256 kEECDH+AES128 kEECDH+AES256 kEDH+AES128 kEDH+AES256 DES-CBC3-SHA +SHA !aNULL !eNULL !LOW !kECDH !DSS !MD5 !EXP !PSK !SRP !CAMELLIA !SEED';
  ssl_session_cache builtin:1000 shared:SSL:10m;
  ssl_stapling on;

  # Use 2048 bit Diffie-Hellman RSA key parameters
  # (otherwise Nginx defaults to 1024 bit, lowering the strength of encryption 
  # when using PFS)
  # Generated by OpenSSL with the following command:
  # openssl dhparam -outform pem -out /etc/nginx/ssl/dhparam2048.pem 2048
        
  ssl_dhparam /etc/nginx/ssl/dhparam2048.pem;
  ssl_certificate /etc/nginx/ssl/certificate.crt;
  ssl_certificate_key /etc/nginx/ssl/server.key;

	location / {
		 rewrite ^ https://yourdomain.com$request_uri? permanent;
	}
  
	location = /i {
		proxy_pass http://127.0.0.1:3001;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header X-Real-IP $remote_addr;
	}
	
	location ^~ /i/ {
		proxy_pass http://127.0.0.1:3001;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header X-Real-IP $remote_addr;
	}

	location = /o {
		proxy_pass http://127.0.0.1:3001;
	}
	
	location ^~ /o/ {
		proxy_pass http://127.0.0.1:3001;
	}
  
}

Replace yourdomain.com with your domain or the IP address where your Countly server is located.

All that is left to do is reload the Nginx configuration, and the HTTPS connection should work:

sudo nginx -s reload

HTTPS and SSL for Countly Server

This guide explains how to enable SSL/TLS (HTTPS) for both the API and Frontend servers in Countly.

Prepare Your SSL Certificates

You need the following files:

- Private key file (.key): e.g., private.key 
- Certificate file (.crt): e.g., certificate.crt
- CA bundle file (.crt, optional): e.g., ca_bundle.crt (for client certificate verification)

If you would like to create a self-signed ssl_certificate and ssl_certificate_key you can run

sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout private.key -out certificate.crt

It will generate the files private.key and certificate.crt in your current directory. Place these files in a secure location on your Countly instance server, for example in /etc/countly/ssl. Make sure that the owner of these files is the same as the user that runs Countly processes (usually the user is 'countly').

Update API Server Configuration

File: /countly_dir/api/config.js (see api/config.sample.js as reference)

Find the 'api' section and add or update the 'ssl' configuration:

api: {
  port: 3001,
  host: "localhost",
  // ...other options
  ssl: {
    enabled: true, // <--- Set to true to enable SSL
    key: "/path/to/ssl/private.key", // Path to your private key file
    cert: "/path/to/ssl/certificate.crt", // Path to your certificate file
    ca: "/path/to/ssl/ca_bundle.crt" // Optional: Path to CA bundle file
  }
}

If using docker, use these variables to set the configuration

COUNTLY_CONFIG_API_API_SSL_ENABLED
COUNTLY_CONFIG_API_API_SSL_KEY
COUNTLY_CONFIG_API_API_SSL_CERT
COUNTLY_CONFIG_API_API_SSL_CA

Update Frontend Server Configuration

File: /countly_dir/frontend/express/config.js (see frontend/express/config.sample.js as reference)

Find the 'web' section and add or update the 'ssl' configuration:

web: {
  port: 6001,
  host: "localhost",
  // ...other options
  ssl: {
    enabled: true, // <--- Set to true to enable SSL
    key: "/path/to/ssl/private.key", // Path to your private key file
    cert: "/path/to/ssl/certificate.crt", // Path to your certificate file
    ca: "/path/to/ssl/ca_bundle.crt" // Optional: Path to CA bundle file
  }
}

If using docker, use these variables to set the configuration

COUNTLY_CONFIG_FRONTEND_WEB_SSL_ENABLED
COUNTLY_CONFIG_FRONTEND_WEB_SSL_KEY
COUNTLY_CONFIG_FRONTEND_WEB_SSL_CERT
COUNTLY_CONFIG_FRONTEND_WEB_SSL_CA

Restart Countly

After configuring SSL, restart both the API and Frontend servers for changes to take effect.

sudo countly restart

Update Nginx/Proxy (If Used)

If you use Nginx or another reverse proxy, update its config to point to the corresponding HTTPS servers.
An example file is provided in: 'bin/config/nginx.server.internal_ssl.conf'.

Verify

Visit your Countly dashboard using a browser to make sure that it is accessible.