Litlyx on Ubuntu 24.04 on Azure User Guide

Overview

This image runs Litlyx 0.0.19, the open source, privacy-first analytics platform - a cookie-free, self-hosted alternative to Google Analytics 4, PostHog and Mixpanel - on Ubuntu 24.04 LTS. Litlyx tracks page visits, unique visitors, referrers, devices and your own custom product events in real time, and presents them through a clean dashboard - without cookies and without profiling individual visitors.

Litlyx self-hosts as a small set of services, orchestrated by Docker Compose and managed by systemd. A lightweight producer service receives tracking events on an ingest endpoint and pushes them onto a Redis stream; a consumer service reads that stream and writes visits and events into a local MongoDB database; and a Nuxt dashboard serves the analytics UI and API. All of these run on the instance only - nginx on port 80 is the single public listener, routing the tracking ingest paths to the producer and everything else to the dashboard. MongoDB and Redis are never exposed off the instance.

What is included:

• Litlyx 0.0.19 self-host stack (producer, consumer, Nuxt dashboard) built from the pinned upstream source and run under Docker Compose via a litlyx.service systemd unit
• The dashboard and tracking ingest on :80 (nginx routes /event, /visit, /keep_alive to the producer and everything else to the dashboard)
• A per-VM admin account whose password is generated on first boot and recorded in a root-only file
• Every application secret (MongoDB password, Redis password, session/JWT secret, admin password) generated fresh per-VM on first boot - no baked default survives into the image
• MongoDB and Redis bound to the instance, with all analytics data on a dedicated Azure data disk at /var/lib/litlyx
• An unauthenticated /healthz endpoint for Azure Load Balancer health probes
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a sensible starting point; size up for busy sites. NSG inbound: allow 22/tcp from your management network and 80/tcp for the dashboard and the tracking script. Litlyx serves plain HTTP on port 80; for production, terminate TLS in front of it with your own domain, since browsers increasingly require HTTPS for pages that embed third-party scripts.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Litlyx by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). Review the dedicated data disk on the Disks tab, then Review + create then Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name litlyx \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name litlyx --port 80 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

On the very first boot, litlyx-firstboot.service generates every per-VM secret, brings the Compose stack up and creates the admin account. On a fresh VM this takes a minute or two; the commands below wait for nothing once it has finished.

Step 4 - Confirm the services are running

Litlyx runs as a Docker Compose stack behind nginx. Confirm the systemd units are active and the five containers are up:

systemctl is-active docker nginx litlyx litlyx-firstboot
sudo docker compose -f /opt/litlyx/docker-compose.yml ps

Expected output:

active
active
active
active
SERVICE     STATUS          PORTS
consumer    Up 13 minutes
dashboard   Up 13 minutes   127.0.0.1:3000->3000/tcp
mongo       Up 13 minutes   27017/tcp
producer    Up 13 minutes   127.0.0.1:3001->3001/tcp
redis       Up 13 minutes   6379/tcp

Only the dashboard (3000) and producer (3001) are published, and only to 127.0.0.1; MongoDB and Redis stay on the internal Compose network. nginx is the single public listener on :80.

Step 5 - Retrieve your admin password

On the first boot of every VM, litlyx-firstboot.service generates a unique administrator password - together with every other secret in the stack - and writes the admin email, password and dashboard URL into a root-only file. Read it with:

sudo cat /root/litlyx-credentials.txt

Expected output (your password will differ):

# Litlyx self-host - generated on first boot by litlyx-firstboot.service
# These credentials are unique to this VM. Store them somewhere safe.

LITLYX_URL=http://<vm-public-ip>/
LITLYX_ADMIN_EMAIL=admin@litlyx.local
LITLYX_ADMIN_PASSWORD=<LITLYX_ADMIN_PASSWORD>

The upstream project ships fixed default credentials for its datastores, session secret and admin login; none of them survive into this image. Every one is regenerated on first boot, so no two instances share a secret and the upstream default never governs a running dashboard.

Step 6 - Confirm the stack and health endpoint

nginx serves an unauthenticated /healthz endpoint for load balancer probes. Confirm it answers, the dashboard responds, and check the bundled MongoDB and Docker versions:

curl -sI http://127.0.0.1/healthz | head -1
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/
sudo docker exec litlyx-mongo-1 mongod --version | head -1
sudo docker --version

Expected output:

HTTP/1.1 200 OK
200
db version v8.0.26
Docker version 29.6.2, build dfc4efb

Step 7 - Sign in to the dashboard

Browse to http://<vm-public-ip>/. Enter the admin email (admin@litlyx.local) and the password from Step 5.

Step 8 - Read the real-time dashboard

The Web Analytics view is the default after signing in. It summarises total visits, unique visitors, bounce rate and average visit duration across your project, with a live trend chart of views, visitors and events over your selected date range. It updates as traffic arrives once you add the tracking script to your site.

Step 9 - Track custom events

Beyond page visits, Litlyx tracks your own custom events - a signup, a purchase, a download, or anything else that matters - each with optional structured metadata. The Custom Events view ranks your most frequent events and charts them over time, so you can measure the actions users take, not just the pages they see.

Step 10 - Add the tracking script to your site

Open Settings from the left navigation. Under General you will find the project's Workspace id and a ready-made tracking Script tag. Copy the workspace id, then add the snippet to your own site, pointing it at this instance so events are sent to your self-hosted producer:

<script defer
  data-project="<your-workspace-id>"
  data-host="<vm-public-ip>" data-port="80" data-secure="false"
  src="https://cdn.jsdelivr.net/gh/litlyx/litlyx-js/browser/litlyx.js"></script>

Once the script is live, page visits appear on the dashboard in real time. To track a custom event from your own code, call Lit.event('signup') (optionally with a metadata object). Because Litlyx sets no cookies and stores no personal data, no cookie banner is required in most jurisdictions - check your own compliance requirements before relying on this.

Step 11 - Confirm analytics data lives on the dedicated disk

All MongoDB and Redis data - every visit, event and session, plus the built Litlyx images - lives under /var/lib/litlyx, the Docker data-root relocated onto a dedicated Azure data disk that is captured into the image and re-provisioned on every VM:

df -h /var/lib/litlyx | tail -1
findmnt -no SOURCE,TARGET,FSTYPE /var/lib/litlyx
sudo docker info --format '{{.DockerRootDir}}'

Expected output:

/dev/sda         30G  213M   28G   1% /var/lib/litlyx
/dev/sda /var/lib/litlyx ext4
/var/lib/litlyx/docker

The disk is mounted by UUID with nofail, so it survives Azure device-name reordering across reboots.

Maintenance

• Back up your analytics data: everything Litlyx stores lives in the MongoDB and Redis volumes under /var/lib/litlyx. Snapshot the data disk, or use mongodump/mongorestore against the mongo container for logical backups.
• AI insights (optional): Litlyx can summarise your data with an LLM. This needs your own OpenAI key - set NUXT_AI_KEY (and NUXT_PUBLIC_AI_ENABLED=true) in /opt/litlyx/.env and run sudo systemctl restart litlyx. No AI key is bundled, and the core analytics work fully without one.
• Restart the stack: sudo systemctl restart litlyx brings the Compose stack down and back up; sudo docker compose -f /opt/litlyx/docker-compose.yml logs -f dashboard tails the dashboard logs.
• Security updates: unattended security upgrades are enabled, so the OS keeps itself patched. Reboot when a new kernel is installed.
• TLS: for production, front Litlyx with your own domain and a TLS-terminating reverse proxy or Azure Application Gateway, and set data-secure="true" in the tracking snippet - most browsers restrict third-party script behaviour on plain HTTP pages.

Support

cloudimg provides 24/7/365 expert technical support for this image. Contact support@cloudimg.co.uk. Litlyx is licensed under the Apache License 2.0. This image is provided by cloudimg; additional charges apply for build, maintenance and 24/7 support.