Skip to main content
Sparklytics ships as a single Docker image with the backend, dashboard, and GeoIP database bundled together. No separate database container required.

​
Quick Start

The fastest way to get Sparklytics running:
1

Download docker-compose.yml

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

Start the container

docker compose up -d
3

Access the dashboard

Open http://your-server-ip:3000 in your browser. You’ll be guided through one-time setup to create your admin account.

​
Docker Compose Configuration

Here’s the complete docker-compose.yml file: 
version: '3.8'
services:
  sparklytics:
    image: sparklytics/sparklytics:latest
    ports:
      - "3000:3000"
    volumes:
      - sparklytics-data:/data
    environment:
      # Auth mode: "local" (recommended), "password", or "none"
      - SPARKLYTICS_AUTH=local

      # IMPORTANT: keep "true" (default) when accessed over HTTPS.
      # Only set to "false" for plain-HTTP local development.
      - SPARKLYTICS_HTTPS=true

      # DuckDB query memory. Raise to 2GB–8GB on a larger VPS.
      - SPARKLYTICS_DUCKDB_MEMORY=1GB

      # Restrict which origins can query the analytics API from a browser.
      # Uncomment and set to your site(s):
      # - SPARKLYTICS_CORS_ORIGINS=https://yoursite.com,https://www.yoursite.com
    restart: unless-stopped

volumes:
  sparklytics-data:

​
Key Configuration Points

The sparklytics-data named volume stores your DuckDB database file. This ensures data persists across container restarts.To use a host directory instead:
volumes:
  - ./data:/data
SPARKLYTICS_AUTH controls the authentication behavior:
ModeValueFirst-run UXBest for
Local auth (recommended)localRedirects to /setup once, then /loginMost self-hosted production installs
Env passwordpasswordRedirects directly to /loginSimple single-password deployments
Open modenoneNo login/setup; dashboard opens directlyLocal development only
For password mode, add:
- SPARKLYTICS_PASSWORD=your-strong-password
SPARKLYTICS_DUCKDB_MEMORY sets the query memory limit. Default is 1GB.For better performance on larger VPS instances (16–32 GB RAM):
- SPARKLYTICS_DUCKDB_MEMORY=4GB
Accepts any DuckDB size string: 512MB, 1GB, 2GB, 8GB, etc.

​
Running Without docker-compose

If you prefer docker run directly: 
docker run -d \
  --name sparklytics \
  -p 3000:3000 \
  -v sparklytics-data:/data \
  -e SPARKLYTICS_AUTH=local \
  -e SPARKLYTICS_HTTPS=true \
  -e SPARKLYTICS_DUCKDB_MEMORY=1GB \
  sparklytics/sparklytics:latest

​
Environment Variables Reference

VariableDefaultDescription
SPARKLYTICS_AUTHlocalAuth mode: none, password, or local
SPARKLYTICS_PASSWORD—Required when SPARKLYTICS_AUTH=password
SPARKLYTICS_HTTPStrueSet false only for plain-HTTP local dev
SPARKLYTICS_PORT3000Listen port
SPARKLYTICS_DATA_DIR/dataDuckDB data directory (inside container)
SPARKLYTICS_DUCKDB_MEMORY1GBQuery memory limit
SPARKLYTICS_CORS_ORIGINS—Comma-separated allowed origins for analytics API
SPARKLYTICS_RETENTION_DAYS365How long to keep raw events
SPARKLYTICS_GEOIP_PATH/geoip/dbip-city-lite.mmdbPath to city MMDB (bundled in Docker image)

​
First Launch Verification

After starting the container, verify everything works:
1

Check health endpoint

curl http://localhost:3000/health
Expected response:
{"status":"ok"}
2

Complete setup (local mode only)

Visit http://localhost:3000/dashboard — you’ll be redirected to /setup.Set your admin password (minimum 12 characters), then log in.
3

Send a test pageview

curl -X POST http://localhost:3000/api/collect \
  -H 'content-type: application/json' \
  -d '{
    "website_id":"site_default",
    "type":"pageview",
    "url":"/test",
    "referrer":"",
    "screen":"1440x900",
    "language":"en-US"
  }'
Expected response:
{"ok":true}

​
Common Issues

Cause: Running over plain HTTP with SPARKLYTICS_HTTPS=true, so browser drops the Secure cookie.Fix: Set SPARKLYTICS_HTTPS=false for localhost/non-TLS environments and restart:
docker compose down
docker compose up -d
Cause: No persistent volume mounted.Fix: Ensure your docker-compose.yml has the volumes section:
volumes:
  - sparklytics-data:/data
Cause: Missing SPARKLYTICS_PASSWORD environment variable.Fix: Add the password to your compose file:
- SPARKLYTICS_PASSWORD=your-strong-password

​
Docker with Caddy (HTTPS)

For production deployments with automatic HTTPS, see the Reverse Proxy Setup guide. Quick preview: 
curl -O https://raw.githubusercontent.com/Sparklytics/sparklytics/main/docker-compose.caddy.yml
# Edit Caddyfile — replace analytics.example.com with your domain
docker compose -f docker-compose.caddy.yml up -d

​
Pre-built Images

Sparklytics provides multi-arch Docker images:
  • sparklytics/sparklytics:latest — latest stable release
  • sparklytics/sparklytics:v1.0.0 — specific version tag
Supported architectures:
  • linux/amd64
  • linux/arm64
Docker automatically pulls the correct image for your platform.

​
Updating

To update to the latest version: 
docker compose pull
docker compose up -d
Your data persists in the sparklytics-data volume.

​
Next Steps

Reverse Proxy Setup

Configure Caddy, Nginx, or Traefik for HTTPS

HTTPS Setup

SSL/TLS configuration and certificate management

Performance Tuning

Optimize for high-traffic deployments

HTML Snippet

Add tracking to your website

Build docs developers (and LLMs) love

Get started for freeTalk to us