Skip to main content
Sparklytics supports three authentication modes: local (recommended), password, and none. Choose the mode that fits your deployment scenario.

​
Authentication Modes Overview

ModeSPARKLYTICS_AUTHFirst-Run UXBest For
Local (recommended)local/setup page once, then /loginProduction self-hosted deployments
Single passwordpasswordDirect /login with env passwordSimple single-user setups
Open (no auth)noneDashboard opens directlyLocal dev behind trusted network
The authentication mode cannot be changed after initial setup without clearing the database. Choose carefully before first launch.
Best for: Production self-hosted deployments where you want secure password storage and the ability to change credentials without redeploying.

​
How It Works

  1. First visit to /dashboard redirects to /setup
  2. Admin creates a password (stored hashed with Argon2id)
  3. Subsequent visits require login at /login
  4. Password is stored in DuckDB, not in environment variables

​
Configuration

SPARKLYTICS_AUTH=local
SPARKLYTICS_HTTPS=true  # false for localhost development
SPARKLYTICS_SESSION_DAYS=7

​
First Launch Flow

1

Start Sparklytics

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

Visit setup page

Open http://localhost:3000 in your browser. You’ll be redirected to /setup.
3

Create admin password

Enter a password (minimum 12 characters recommended). Click Create Account.Password requirements:
  • At least 1 character long (12+ recommended)
  • Cannot be only whitespace
4

Login

After setup completes, you’ll be redirected to /login. Sign in with your new password.
5

Access dashboard

You’ll land on /dashboard/site_default — your analytics dashboard.

​
Password Requirements

  • Minimum length: 1 character (12+ strongly recommended)
  • Cannot be whitespace-only
  • Stored hashed with Argon2id (64 MB memory cost by default)

​
Advanced: Argon2 Tuning

​
SPARKLYTICS_ARGON2_MEMORY_KB
number
default:"65536"
Argon2id memory cost in KB (64 MB default).Higher values increase security against brute-force attacks but use more RAM during login/setup.
SPARKLYTICS_ARGON2_MEMORY_KB=131072  # 128 MB

​
Changing Your Password

Currently, password changes require database access: 
# Stop Sparklytics
docker stop sparklytics

# Delete the admin user from DuckDB
# (This will trigger setup flow on next visit)
docker run --rm -v sparklytics-data:/data -it sparklytics/sparklytics:latest \
  duckdb /data/sparklytics.db -c "DELETE FROM local_api_keys WHERE key_type = 'admin'"

# Restart and visit /setup
docker start sparklytics
A dashboard password change feature is planned for v1.1.

​
Password Mode

Best for: Simple single-user deployments where you’re comfortable storing the password in environment variables.

​
How It Works

  1. Password is set via SPARKLYTICS_PASSWORD environment variable
  2. No setup page — dashboard redirects directly to /login
  3. All logins use the environment variable password
  4. To change password, update env var and restart

​
Configuration

SPARKLYTICS_PASSWORD is required. The server will refuse to start without it in password mode.
SPARKLYTICS_AUTH=password
SPARKLYTICS_PASSWORD='your-secure-password-here'
SPARKLYTICS_HTTPS=true
SPARKLYTICS_SESSION_DAYS=7

​
Docker Example

docker run -d \
  --name sparklytics \
  -p 3000:3000 \
  -v sparklytics-data:/data \
  -e SPARKLYTICS_AUTH=password \
  -e SPARKLYTICS_PASSWORD='replace-with-strong-password' \
  -e SPARKLYTICS_HTTPS=true \
  sparklytics/sparklytics:latest

​
Security Considerations

  • Store SPARKLYTICS_PASSWORD securely (use Docker secrets, vault, or encrypted env files)
  • Never commit .env files with passwords to version control
  • Use a strong password (12+ characters, mixed case, numbers, symbols)

​
Changing the Password

  1. Update SPARKLYTICS_PASSWORD in your environment/config
  2. Restart Sparklytics
  3. Existing sessions remain valid until they expire (SPARKLYTICS_SESSION_DAYS)

​
None Mode (Development Only)

Best for: Local development when running on localhost behind a trusted network.
Never use none mode in production. Anyone who can reach your server can access all analytics data and modify settings.

​
How It Works

  1. No login or setup screens
  2. /dashboard opens directly
  3. /api/auth/status endpoint returns 404 (not registered)
  4. All dashboard routes are accessible without authentication

​
Configuration

SPARKLYTICS_AUTH=none
SPARKLYTICS_HTTPS=false  # Usually for localhost

​
Docker Example

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

​
When to Use None Mode

  • Local development on localhost
  • Running behind another authentication layer (OAuth proxy, VPN, etc.)
  • Testing integrations where login flow is cumbersome

​
When NOT to Use None Mode

  • Production deployments
  • Any server accessible from the internet
  • Shared development environments

​
Session Management

​
Session Lifetime

​
SPARKLYTICS_SESSION_DAYS
number
default:"7"
JWT session cookie lifetime in days (1-30).Applies to both local and password modes.
SPARKLYTICS_SESSION_DAYS=14  # 2 weeks

​
Secure Cookies

​
SPARKLYTICS_HTTPS
boolean
default:"true"
Controls the Secure flag on session cookies.
  • true: Cookies sent only over HTTPS (required for production)
  • false: Cookies sent over HTTP (localhost development only)
# Production (behind HTTPS reverse proxy)
SPARKLYTICS_HTTPS=true

# Local development (http://localhost:3000)
SPARKLYTICS_HTTPS=false
Sparklytics session cookies use these security flags:
  • HttpOnly: Prevents JavaScript access (XSS protection)
  • SameSite=Lax: CSRF protection
  • Secure: Only sent over HTTPS (when SPARKLYTICS_HTTPS=true)

​
API Key Authentication

In addition to dashboard authentication, Sparklytics uses API keys for:
  • Website tracking (public API keys, POST /api/collect)
  • Programmatic access (private API keys, analytics queries)
API keys are generated with mode-aware prefixes:
  • Self-hosted: spk_selfhosted_...
  • Cloud: spk_live_...
API key management is separate from dashboard authentication. See API Reference for details.

​
Troubleshooting

​
”Setup required” Loop

If you’re stuck in a redirect loop:
  1. Check docker logs sparklytics for errors
  2. Verify SPARKLYTICS_AUTH=local is set
  3. Ensure /data volume is writable
  4. Try deleting the DuckDB file and restarting (loses all data)

​
“Invalid password” on First Login (Password Mode)

  1. Check that SPARKLYTICS_PASSWORD is set correctly
  2. Look for trailing spaces or quotes in the env var
  3. Restart the container after changing env vars

​
Cookies Not Persisting

  1. If testing on http://localhost, set SPARKLYTICS_HTTPS=false
  2. Check browser DevTools → Application → Cookies
  3. Ensure your browser allows cookies (not in private/incognito mode)

​
404 on /api/auth/status (None Mode)

This is expected behavior. In none mode, auth endpoints are not registered.

​
Migration Between Modes

Changing authentication modes requires clearing the database. Plan migrations carefully.
To switch modes:
  1. Backup your data (export events if needed)
  2. Stop Sparklytics
  3. Delete the DuckDB file (./data/sparklytics.db)
  4. Update SPARKLYTICS_AUTH and related env vars
  5. Restart Sparklytics
  6. Complete new setup flow (if applicable)

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us