Skip to main content
Get Sparklytics deployed and tracking your first website in under 5 minutes.

​
What you’ll accomplish

1

Deploy Sparklytics

Start Sparklytics on your server using Docker
2

Create your account

Complete the one-time setup and create your admin account
3

Add your website

Register your first website in the dashboard
4

Install tracking

Add the tracking script to your website

​
Deploy Sparklytics

If you’re running Sparklytics locally over plain HTTP (not HTTPS), set SPARKLYTICS_HTTPS=false in your environment variables. See HTTPS Setup for production deployment.

​
Complete first-run setup

  1. Open http://your-server-ip:3000 in your browser
  2. You’ll be redirected to the setup page
  3. Create your admin account:
    • Email: Your admin email
    • Password: Choose a strong password (min 8 characters)
  4. Click Create Account
You’ll be automatically logged in and redirected to the dashboard.
By default, Sparklytics uses “local” authentication mode. Your credentials are stored securely with Argon2id password hashing. See Authentication for other auth modes.

​
Add your first website

1

Navigate to websites

From the dashboard, click Websites in the sidebar or click + New Website.
2

Fill in website details

  • Name: A friendly name (e.g., “My Blog”)
  • Domain: Your website domain (e.g., myblog.com)
  • Timezone: Your preferred timezone for date ranges
3

Create the website

Click Create Website. You’ll see your new website in the list with a generated Website ID (format: site_XXXXXXXXXX).

​
Install tracking

Choose the integration method that fits your stack:
Add this script tag before the closing </body> tag on every page you want to track:
<!-- Add before </body> -->
<script 
  defer 
  src="https://your-analytics-domain.com/s.js" 
  data-website-id="site_XXXXXXXXXX">
</script>
Replace:
  • your-analytics-domain.com with your Sparklytics instance domain
  • site_XXXXXXXXXX with your actual Website ID from step 3
That’s it! Pageviews will appear in your dashboard within seconds.

​
Verify tracking is working

1

Visit your website

Open your website in a browser (in a different tab/window from your Sparklytics dashboard).
2

Check the dashboard

Return to your Sparklytics dashboard. Within a few seconds, you should see:
  • 1 active visitor in the real-time panel
  • 1 pageview in the stats overview
  • Your recent pageview in the “Recent Events” list
3

Verify the event

The recent event should show:
  • Correct page URL
  • Your location (country/city from GeoIP)
  • Browser and device information
Events are buffered for 5 seconds before being written to the database. If you don’t see your event immediately, wait a few seconds and refresh the dashboard.

​
Track custom events

Beyond pageviews, you can track custom user actions: 
// Track a button click
document.getElementById('signup-btn').addEventListener('click', () => {
  window.sparklytics?.track('signup_click', { plan: 'pro' })
})

// Track with properties
window.sparklytics?.track('purchase', {
  product: 'Pro Plan',
  amount: 29.99,
  currency: 'USD'
})
Custom events appear in the dashboard under Events and can be used in funnels, retention analysis, and journey tracking.

​
What’s next?

Custom Events

Track user actions beyond pageviews

Funnels

Measure conversion rates through multi-step journeys

Retention

Analyze cohort retention over time

API Reference

Explore the analytics API

​
Troubleshooting

Check these common issues:
  1. Verify the tracking script is loaded
    • Open browser DevTools → Network tab
    • Look for a request to /s.js
    • Check for a POST request to /api/collect
  2. Check the Website ID
    • Ensure data-website-id matches your actual Website ID from the dashboard
    • Website IDs start with site_
  3. CORS / Mixed Content
    • If your site is HTTPS, your analytics server must also be HTTPS
    • Check browser console for CORS or mixed content errors
  4. Ad blockers
    • Some ad blockers block analytics scripts
    • Test in an incognito window or with ad blockers disabled
If you’re stuck in a redirect loop:
  1. Check that SPARKLYTICS_AUTH=local is set
  2. Delete the data volume and restart: 
    docker compose down -v
docker compose up -d
  3. Access the setup page at http://your-server-ip:3000/setup
Common issues:
  1. HTTPS cookie issues
    • If running locally over HTTP, set SPARKLYTICS_HTTPS=false
    • The Secure cookie flag requires HTTPS in production
  2. Wrong auth mode
    • Verify SPARKLYTICS_AUTH=local in your environment
    • If using password mode, use SPARKLYTICS_PASSWORD instead
  3. Clear browser data
    • Clear cookies for the Sparklytics domain
    • Try in an incognito window
For more detailed installation options, see the Installation Guide. For production deployments, review the Docker Deployment and HTTPS Setup guides.

Build docs developers (and LLMs) love

Get started for freeTalk to us