Installation - Sparklytics

Choose your deployment method

Sparklytics supports multiple installation methods to fit your infrastructure.

Docker Compose

Recommended for most users — persistent volumes and easy configuration

Docker Run

Quick single-container deployment for testing

Binary

Direct execution — no container runtime required

Docker Compose (Recommended)

The easiest way to deploy Sparklytics with persistent data storage.

Download docker-compose.yml

curl -O https://raw.githubusercontent.com/Sparklytics/sparklytics/main/docker-compose.yml

The default configuration:

docker-compose.yml

version: '3.8'
services:
  sparklytics:
    image: sparklytics/sparklytics:latest
    ports:
      - "3000:3000"
    volumes:
      - sparklytics-data:/data
    environment:
      - SPARKLYTICS_AUTH=local
      - SPARKLYTICS_HTTPS=true
      - SPARKLYTICS_DUCKDB_MEMORY=1GB
    restart: unless-stopped

volumes:
  sparklytics-data:

Configure environment variables

Edit docker-compose.yml to customize your deployment:

environment:
  - SPARKLYTICS_AUTH=local
  - SPARKLYTICS_HTTPS=false  # Plain HTTP for localhost
  - SPARKLYTICS_DUCKDB_MEMORY=1GB

IMPORTANT: Set SPARKLYTICS_HTTPS=false only when testing on plain http://localhost. For production deployments behind HTTPS, keep it true or the browser will reject authentication cookies.

Start the service

docker compose up -d

Verify it’s running:

docker compose ps
docker compose logs -f

Open http://localhost:3000 to complete setup.

Docker Compose with Caddy (HTTPS)

For production deployments with automatic TLS certificates:

curl -O https://raw.githubusercontent.com/Sparklytics/sparklytics/main/docker-compose.caddy.yml

Edit the Caddyfile and replace analytics.example.com with your domain:

Caddyfile

analytics.yourdomain.com {
  reverse_proxy sparklytics:3000
}

Start with Caddy:

docker compose -f docker-compose.caddy.yml up -d

Caddy automatically obtains and renews Let’s Encrypt certificates — no manual certbot setup required.

For Nginx or Traefik reverse proxy configurations, see docs/reverse-proxy.md.

Docker Run

Deploy a single container with persistent storage.

Local Auth (Recommended)

docker run -d \
  --name sparklytics \
  -p 3000:3000 \
  -v sparklytics-data:/data \
  -e SPARKLYTICS_AUTH=local \
  -e SPARKLYTICS_HTTPS=false \
  -e SPARKLYTICS_DUCKDB_MEMORY=1GB \
  sparklytics/sparklytics:latest

Password Auth

docker run -d \
  --name sparklytics \
  -p 3000:3000 \
  -v sparklytics-data:/data \
  -e SPARKLYTICS_AUTH=password \
  -e SPARKLYTICS_PASSWORD='your-strong-password' \
  -e SPARKLYTICS_HTTPS=false \
  -e SPARKLYTICS_DUCKDB_MEMORY=1GB \
  sparklytics/sparklytics:latest

In password mode, SPARKLYTICS_PASSWORD is required — the container will fail to start without it.

Open Mode (No Authentication)

docker run -d \
  --name sparklytics \
  -p 3000:3000 \
  -v sparklytics-data:/data \
  -e SPARKLYTICS_AUTH=none \
  -e SPARKLYTICS_DUCKDB_MEMORY=1GB \
  sparklytics/sparklytics:latest

Security risk: Open mode allows anyone to access your analytics dashboard. Only use this for local development or when Sparklytics is behind a trusted network firewall.

View logs

docker logs -f sparklytics

Stop and remove

docker stop sparklytics
docker rm sparklytics

The named volume sparklytics-data persists your analytics data even after removing the container. To delete all data: docker volume rm sparklytics-data.

Binary Installation

Run Sparklytics directly without Docker.

Download the binary

Download the latest release for your platform from GitHub Releases:

# Linux AMD64
curl -LO https://github.com/Sparklytics/sparklytics/releases/latest/download/sparklytics-linux-amd64
chmod +x sparklytics-linux-amd64
mv sparklytics-linux-amd64 sparklytics

curl -LO https://github.com/Sparklytics/sparklytics/releases/latest/download/sparklytics-linux-arm64
chmod +x sparklytics-linux-arm64
mv sparklytics-linux-arm64 sparklytics

Download GeoIP database

Sparklytics uses a GeoIP database for country/city analytics. Docker images bundle this automatically, but binary installations need it downloaded manually.

# Download DB-IP City Lite database
curl -O https://download.db-ip.com/free/dbip-city-lite-$(date +%Y-%m).mmdb.gz
gunzip dbip-city-lite-*.mmdb.gz
mv dbip-city-lite-*.mmdb dbip-city-lite.mmdb

You can also use MaxMind GeoLite2-City.mmdb — just point SPARKLYTICS_GEOIP_PATH at it.

Create data directory

mkdir -p ./data

Run Sparklytics

SPARKLYTICS_DATA_DIR=./data \
SPARKLYTICS_AUTH=local \
SPARKLYTICS_HTTPS=false \
SPARKLYTICS_DUCKDB_MEMORY=1GB \
SPARKLYTICS_GEOIP_PATH=./dbip-city-lite.mmdb \
./sparklytics

The dashboard is embedded in the binary — no separate web server needed.

Verify it's running

curl http://localhost:3000/health

Expect:

{"status":"ok"}

Run as a systemd service

For production deployments, run Sparklytics as a systemd service:

/etc/systemd/system/sparklytics.service

[Unit]
Description=Sparklytics Analytics
After=network.target

[Service]
Type=simple
User=sparklytics
WorkingDirectory=/opt/sparklytics
Environment="SPARKLYTICS_DATA_DIR=/opt/sparklytics/data"
Environment="SPARKLYTICS_AUTH=local"
Environment="SPARKLYTICS_HTTPS=true"
Environment="SPARKLYTICS_DUCKDB_MEMORY=2GB"
Environment="SPARKLYTICS_GEOIP_PATH=/opt/sparklytics/dbip-city-lite.mmdb"
ExecStart=/opt/sparklytics/sparklytics
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable sparklytics
sudo systemctl start sparklytics
sudo systemctl status sparklytics

Environment Variables Reference

Authentication

Variable	Default	Description
`SPARKLYTICS_AUTH`	`local`	Auth mode: `local` (one-time setup), `password` (env password), or `none` (no auth)
`SPARKLYTICS_PASSWORD`	—	Required when `SPARKLYTICS_AUTH=password`
`SPARKLYTICS_SESSION_DAYS`	`7`	JWT session expiry in days (1–30)

Network

Variable	Default	Description
`SPARKLYTICS_PORT`	`3000`	HTTP listen port
`SPARKLYTICS_HTTPS`	`true`	Set `false` only for plain HTTP (localhost/dev). Keep `true` for HTTPS deployments or cookies will be rejected.
`SPARKLYTICS_CORS_ORIGINS`	—	Comma-separated allowed origins for analytics API (e.g., `https://yoursite.com,https://www.yoursite.com`)

Storage

Variable	Default	Description
`SPARKLYTICS_DATA_DIR`	`./data`	DuckDB data directory
`SPARKLYTICS_DUCKDB_MEMORY`	`1GB`	Query memory limit. Raise to `2GB`–`8GB` on larger VPS for better query performance.
`SPARKLYTICS_RETENTION_DAYS`	`365`	How long to keep raw events (days)
`SPARKLYTICS_GEOIP_PATH`	`./GeoLite2-City.mmdb`	Path to GeoIP MMDB file. Docker images use bundled `/geoip/dbip-city-lite.mmdb`.

Security

Variable	Default	Description
`SPARKLYTICS_ARGON2_MEMORY_KB`	`65536`	Argon2id memory cost in KB (64 MB). Only used in `local` auth mode.

Authentication Modes

Local Mode (`local`, recommended)

One-time setup page on first run:

Visit http://localhost:3000
Redirected to /setup
Create admin password (min 12 characters)
Log in with the new password

Best for: Most self-hosted production deployments.

Password Mode (`password`)

Set SPARKLYTICS_PASSWORD in your deployment config
Visit http://localhost:3000
Redirected to /login
Enter the password from SPARKLYTICS_PASSWORD

Best for: Simple single-password deployments where env vars are secure.

SPARKLYTICS_PASSWORD is required in password mode — the service will fail to start without it.

Open Mode (`none`)

No authentication — dashboard opens directly:

Visit http://localhost:3000
Dashboard loads immediately
No login or setup screens

Best for: Local development or deployments behind a trusted network firewall.

Security risk: Anyone who can reach your Sparklytics server can view and modify analytics data. Only use this mode when Sparklytics is not publicly accessible.

Upgrading

Docker Compose

docker compose pull
docker compose up -d

Your data persists in the named volume across upgrades.

Docker Run

docker pull sparklytics/sparklytics:latest
docker stop sparklytics
docker rm sparklytics
# Run the updated container (same command as initial deployment)

Binary

Download the latest release and replace the binary:

curl -LO https://github.com/Sparklytics/sparklytics/releases/latest/download/sparklytics-linux-amd64
chmod +x sparklytics-linux-amd64
sudo systemctl stop sparklytics
sudo mv sparklytics-linux-amd64 /opt/sparklytics/sparklytics
sudo systemctl start sparklytics

Data Persistence

Docker volumes

Sparklytics stores all data in /data inside the container. The docker-compose.yml mounts a named volume:

volumes:
  - sparklytics-data:/data

This persists across container restarts and upgrades. Backup your data:

docker run --rm -v sparklytics-data:/data -v $(pwd):/backup ubuntu tar czf /backup/sparklytics-backup.tar.gz /data

Restore from backup:

docker run --rm -v sparklytics-data:/data -v $(pwd):/backup ubuntu tar xzf /backup/sparklytics-backup.tar.gz -C /

Binary installations

Set SPARKLYTICS_DATA_DIR to a persistent directory:

SPARKLYTICS_DATA_DIR=/opt/sparklytics/data ./sparklytics

Backup:

tar czf sparklytics-backup.tar.gz /opt/sparklytics/data

Troubleshooting

Container fails to start

Check logs:

docker compose logs

Common issues:

Missing SPARKLYTICS_PASSWORD in password mode
Port 3000 already in use
Permission errors on data volume

Binary fails with “file not found”

Linux binaries are statically linked with musl. Ensure you downloaded the correct architecture:

uname -m  # Should match: x86_64 = amd64, aarch64 = arm64

GeoIP not working

Verify the GeoIP database exists:

# Docker
docker exec sparklytics ls -lh /geoip/dbip-city-lite.mmdb

# Binary
ls -lh ./dbip-city-lite.mmdb

If missing, download it manually (see Binary Installation step 2).

Data disappears after restart

Docker: You didn’t mount a persistent volume. Fix: Add -v sparklytics-data:/data to your docker run command or use docker-compose. Binary: SPARKLYTICS_DATA_DIR points to a temporary directory. Fix: Set an absolute path like /opt/sparklytics/data.

Next Steps

Quick Start

Track your first event and verify data collection

Enable HTTPS

Secure your analytics dashboard with automatic TLS

Tracking Script

Add the tracking snippet to your website

Environment Variables

Full reference for all configuration options

Get Started

Core Features

Integrations

Configuration

Self-Hosting

​Choose your deployment method

Docker Compose

Docker Run

Binary

​Docker Compose (Recommended)

​Docker Compose with Caddy (HTTPS)

​Docker Run

​Local Auth (Recommended)

​Password Auth

​Open Mode (No Authentication)

​View logs

​Stop and remove

​Binary Installation

​Run as a systemd service

​Environment Variables Reference

​Authentication

​Network

​Storage

​Security

​Authentication Modes

​Local Mode (local, recommended)

​Password Mode (password)

​Open Mode (none)

​Upgrading

​Docker Compose

​Docker Run

​Binary

​Data Persistence

​Docker volumes

​Binary installations

​Troubleshooting

​Container fails to start

​Binary fails with “file not found”

​GeoIP not working

​Data disappears after restart

​Next Steps

Quick Start

Enable HTTPS

Tracking Script

Environment Variables

Build docs developers (and LLMs) love

Choose your deployment method

Docker Compose (Recommended)

Docker Compose with Caddy (HTTPS)

Docker Run

Local Auth (Recommended)

Password Auth

Open Mode (No Authentication)

View logs

Stop and remove

Binary Installation

Run as a systemd service

Environment Variables Reference

Authentication

Network

Storage

Security

Authentication Modes

Local Mode (`local`, recommended)

Password Mode (`password`)

Open Mode (`none`)

Upgrading

Docker Compose

Docker Run

Binary

Data Persistence

Docker volumes

Binary installations

Troubleshooting

Container fails to start

Binary fails with “file not found”

GeoIP not working

Data disappears after restart

Next Steps