Countly Lite Analytics on AWS User Guide

Overview

This image runs Countly Lite, the free Community Edition of Countly. It is an open source, self hosted product, mobile and web analytics platform that captures sessions, custom events, funnels, retention and crash data from your apps and websites, and presents them through a rich web dashboard and a simple HTTP API. Everything runs on infrastructure you control, so your product data never leaves your own account.

The stack is three tiers on one instance. A browser reaches nginx on port 80, nginx proxies the ingest and read APIs to the Countly api process and the dashboard to the Countly dashboard process, and both store their data in a local MongoDB 8.0 database. MongoDB binds to the loopback interface only and never accepts a connection from the network.

The image is secure by default and ships no account and no default credential of any kind. On the first boot of every instance a unique administrator password, session secret and password secret are generated, a single administrator is created from them, and the credentials are written to a root only file. The public dashboard is opened only after that per instance administrator exists, so the first visitor never lands on an unconfigured setup wizard.

Architecture

The api process, the dashboard process and MongoDB all bind to the loopback interface, so only ports 22, 80 and 443 need an inbound rule in your security group.

Connecting to your instance

Connect over SSH as the default login user for your operating system variant. This listing currently ships one variant:

ssh -i /path/to/your-key.pem ubuntu@<instance-public-ip>

Replace <instance-public-ip> with the public IPv4 address of your instance and your-key.pem with the private key you selected at launch.

Confirming the services are running

The three services start automatically on boot. Confirm they are active:

sudo systemctl is-active mongod.service countly.service nginx.service

active
active
active

Checking the health endpoints

nginx serves an unauthenticated static /health endpoint for load balancer probes, and proxies the api health check at /o/ping. Once the per instance administrator has been seeded on first boot, the dashboard also answers /login:

curl -s -o /dev/null -w 'health:  HTTP %{http_code}\n' http://127.0.0.1/health
curl -s -o /dev/null -w 'o/ping:  HTTP %{http_code}\n' http://127.0.0.1/o/ping
curl -s -o /dev/null -w 'login:   HTTP %{http_code}\n' http://127.0.0.1/login

health:  HTTP 200
o/ping:  HTTP 200
login:   HTTP 200

Retrieving your administrator credentials

The per instance administrator, its password, its API key and the dashboard URL are written to /root/countly-credentials.txt on first boot. View the non secret fields:

sudo grep -E '^COUNTLY_(URL|ADMIN_USERNAME|ADMIN_EMAIL)=' /root/countly-credentials.txt

COUNTLY_URL=http://<instance-public-ip>/
COUNTLY_ADMIN_USERNAME=admin
COUNTLY_ADMIN_EMAIL=admin@localhost

Print the administrator password when you are ready to sign in, with sudo grep '^COUNTLY_ADMIN_PASSWORD=' /root/countly-credentials.txt | cut -d= -f2-. Run it only when you are about to use the value, and avoid leaving it in your shell history or terminal scrollback. The file also holds COUNTLY_ADMIN_API_KEY, the admin API key used to authenticate the read and write APIs.

Signing in to the dashboard

Browse to http://<instance-public-ip>/ and sign in with the username admin and the password from the credentials file. The installation is already complete, so there is no setup wizard.

The Home dashboard opens on the application overview, with audience metrics, a sessions time series, and quick links into each analytics area.

You can verify the administrator login from the command line without a browser. A successful sign in returns HTTP 302 and redirects to /dashboard:

PW=$(sudo grep '^COUNTLY_ADMIN_PASSWORD=' /root/countly-credentials.txt | cut -d= -f2-)
JAR=$(mktemp)
CSRF=$(curl -s -c "$JAR" http://127.0.0.1/login | grep -oE 'name="_csrf"[^>]*value="[^"]+"|value="[^"]+"[^>]*name="_csrf"' | grep -oE 'value="[^"]+"' | head -1 | sed -E 's/value="([^"]+)"/\1/')
curl -s -b "$JAR" -c "$JAR" -o /dev/null -w 'sign in: HTTP %{http_code} redirect %{redirect_url}\n' \
  --data-urlencode "username=admin" --data-urlencode "password=$PW" --data-urlencode "_csrf=$CSRF" http://127.0.0.1/login
rm -f "$JAR"

sign in: HTTP 302 redirect http://127.0.0.1/dashboard

Creating an application and sending data

Countly organises analytics per application. Create your first application from the dashboard, or from the administration area under Management > Applications, where each application shows its App ID and App Key.

Each application has an App Key that your SDK or HTTP client uses to send data. With the App Key you can begin a session and send a custom event through the /i write API, for example:

# begin a session for a device
curl "http://<instance-public-ip>/i?app_key=<app_key>&device_id=device-123&begin_session=1"

# send a custom event
curl "http://<instance-public-ip>/i?app_key=<app_key>&device_id=device-123" \
  --data-urlencode 'events=[{"key":"purchase","count":1,"sum":42}]'

For a real integration use one of the official Countly SDKs for web, iOS, Android or your server language, which handle sessions, events, views, crashes and user properties for you.

Exploring analytics

The Analytics section breaks your traffic down by sessions, visitors, page views, acquisition, technology and geography. The Session Analytics view shows total, new and unique sessions over time:

The Technology view breaks sessions down by platform, device, resolution, app version and browser:

The MongoDB data volume

The MongoDB database lives on a dedicated EBS volume mounted at /var/lib/mongodb, separate from the operating system disk and independently resizable. It is mounted by filesystem UUID so the layout persists on every instance launched from the image:

df -h /var/lib/mongodb | tail -1
grep mongodb /etc/fstab

/dev/nvme1n1     30G  214M   28G   1% /var/lib/mongodb
UUID=76ba1d12-f75c-43f9-96c9-d88a1f3e1447 /var/lib/mongodb ext4 defaults,nofail 0 2

MongoDB, the api process and the dashboard process all listen on the loopback interface only, so none of them is reachable from the network:

sudo ss -tlnp | grep -E ':27017|:3001|:6001' | sed -E 's/users:.*//'

LISTEN 0      511        127.0.0.1:6001       0.0.0.0:*
LISTEN 0      511        127.0.0.1:3001       0.0.0.0:*
LISTEN 0      4096       127.0.0.1:27017      0.0.0.0:*

To grow the database volume, expand the EBS volume in the AWS console, then extend the filesystem with sudo resize2fs /dev/nvme1n1.

Component versions

echo "Node.js $(node -v)"
echo "MongoDB $(mongod --version | awk '/db version/{print $3}')"
echo "nginx $(nginx -v 2>&1 | sed 's|nginx version: nginx/||')"

Node.js v20.20.2
MongoDB v8.0.28
nginx 1.30.4

This image ships Countly Community Edition 25.03.49.

Restarting and maintaining the services

Manage the services with systemctl. To restart Countly after a configuration change:

sudo systemctl restart countly.service

The services are ordered so that a reboot brings up MongoDB, then the first boot initialisation if it has not run, then Countly, then nginx.

Enabling HTTPS

Countly is served over plain HTTP on port 80. Before exposing it to production traffic, terminate TLS with your own domain and certificate. Point a DNS record at the instance, open port 443 in your security group, and use certbot with the nginx plugin to obtain and install a certificate:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d analytics.your-domain.com

certbot edits the nginx configuration to serve HTTPS and set up automatic renewal.

Support

Every deployment is backed by cloudimg engineers, available around the clock by email at support@cloudimg.co.uk and by live chat. Support covers deployment guidance and instance sizing, MongoDB administration and backup, nginx reverse proxy and TLS termination, Countly upgrades and migration assistance, and performance tuning. Critical issues receive a one hour average response time.