Countly: A Complete Checklist for Self-Hosting Success

Countly is an open-source product analytics and customer engagement platform designed for developers and businesses that want complete control over their data. By self-hosting Countly, you gain full access to granular analytics, enhanced customization options, and robust data privacy, making it an excellent choice for organizations with strict compliance or advanced integration needs. This guide will walk you through deploying, configuring, and managing Countly, including installation, reverse proxy setup, logging, backup strategies, updates, and leveraging its powerful features.

Installing Countly

📦 Docker/Docker Compose Setup

Countly provides an official Docker image, which makes deployment quick and straightforward. Here's how to configure and deploy Countly using Docker Compose.

1. Create a docker-compose.yml file:

version: '3.7'

services:

countly:

image: countly/api:latest

container_name: countly

ports:

- "80:80"

- "443:443"

volumes:

- countly_data:/var/lib/mongodb

- countly_config:/etc/countly

environment:

- COUNTLY_MONGO=mongodb://localhost:27017/countly

- COUNTLY_PLUGINS_DEFAULT=true

volumes:

countly_data:

countly_config:

2. Deploy the application:

docker-compose up -d

3. Verify that the Countly container is running:

docker ps

🚀 Manual Installation

For manual installation on a Linux server, follow these steps:

1. Update the server and install dependencies:

sudo apt update && sudo apt upgrade -y

sudo apt install -y build-essential mongodb nodejs npm nginx

2. Clone the Countly repository:

git clone https://github.com/Countly/countly-server.git

cd countly-server

3. Install Node.js packages and build the frontend:

npm install

grunt dist-build

4. Start the Countly process:

sudo node api/api.js &

sudo node frontend/express.js &

5. Confirm the app is running on http://<your_server_ip>.

Configuring Nginx as a Reverse Proxy

🌐 Nginx Configuration

Nginx can be used to route traffic to Countly and handle HTTPS connections. Here's how to configure a server block for Countly.

1. Create a configuration file:

sudo nano /etc/nginx/sites-available/countly

2. Add the following content:

server {

listen 80;

server_name analytics.example.com;

location / {

proxy_pass http://127.0.0.1:3001;

proxy_http_version 1.1;

proxy_set_header Upgrade $http_upgrade;

proxy_set_header Connection 'upgrade';

proxy_set_header Host $host;

proxy_cache_bypass $http_upgrade;

}

}

3. Enable the configuration and restart Nginx:

sudo ln -s /etc/nginx/sites-available/countly /etc/nginx/sites-enabled/

sudo nginx -t

sudo systemctl restart nginx

🔒 SSL/TLS Setup

To secure your Countly instance with HTTPS, use Let’s Encrypt.

1. Install Certbot:

sudo apt install certbot python3-certbot-nginx -y

2. Obtain and configure an SSL certificate:

sudo certbot --nginx -d analytics.example.com

3. Set up automatic renewal:

sudo systemctl enable certbot.timer

Logging and Debugging Countly

🗃️ Enabling Debug Logs

To enable debug-level logging for better issue analysis, modify the Countly configuration file.

1. Edit api/config.js:

nano /path/to/countly/api/config.js

2. Set the logging level:

"logging": {

"default": "debug"

}

3. Restart the Countly service:

sudo systemctl restart countly

📄 Viewing Logs

Access Countly logs using Docker or directly from the filesystem.

For Docker:

docker logs countly

For manual installations:

tail -f /var/log/countly/countly.log

🛠️ Troubleshooting Common Issues

If Countly fails to start, check:

1. MongoDB status:

sudo systemctl status mongod

2. Port conflicts:

sudo netstat -tuln | grep 3001

Backup and Restore

🗂️ File-Based Backups

Back up configuration and plugins:

tar -czvf countly_backup.tar.gz /path/to/countly

🔄 Database Backups

For MongoDB:

mongodump --db countly --out /backup/countly_data

📅 Automated Backup Scripts

Schedule backups with a cron job:

crontab -e

Add:

0 2 * * * tar -czvf /backup/countly_$(date +\%F).tar.gz /path/to/countly

Updating and Upgrading Countly

⬆️ Updating Docker Images

Pull the latest Countly image and restart the container:

docker-compose pull

docker-compose up -d

🛠️ Manual Updates

For manual installations:

1. Pull the latest code:

git pull origin master

2. Rebuild the frontend:

grunt dist-build

🔍 Checking for Updates

Visit the official Countly GitHub repository to monitor new releases:

https://github.com/Countly/countly-server/releases

Leveraging Countly’s Unique Features

🔧 Enabling APIs

Activate Countly APIs for data integration.

1. Update api/config.js to allow external API calls:

"api": {

"safe": false

}

2. Test the API with curl:

curl -X GET "http://<your_server>/o/users" -H "Authorization: Bearer <API_KEY>"

🌟 Advanced Configurations

Enable plugins for extended functionality:

node plugins/scripts/install.js push

node plugins/scripts/install.js funnels

Restart the app:

sudo systemctl restart countly

Wrapping Up

This guide provided a comprehensive walkthrough for deploying, configuring, and managing a self-hosted Countly instance. From installation to advanced configurations, you now have the tools to unlock the full potential of Countly. Take control of your data and start exploring the powerful analytics and engagement features tailored to your needs.