Skip to content
Klutch.sh Docs

Deploying Vince

Introduction

Vince is an open-source, privacy-focused web analytics platform that provides insights into your website traffic without compromising visitor privacy. Built as a lightweight alternative to traditional analytics platforms, Vince respects user privacy while delivering the metrics you need to understand your audience.

Key highlights of Vince:

  • Privacy First: No cookies, no personal data collection, GDPR compliant
  • Lightweight Script: Minimal JavaScript snippet under 1KB
  • Real-Time Analytics: View visitor data as it happens
  • Simple Dashboard: Clean, intuitive interface for key metrics
  • Self-Hosted: Full control over your analytics data
  • No Cookies: Works without cookie consent banners
  • Open Source: Transparent codebase with community contributions
  • Fast: Minimal impact on page load times

This guide walks through deploying Vince on Klutch.sh using Docker, configuring the analytics platform, and integrating it with your websites.

Why Deploy Vince on Klutch.sh

Deploying Vince on Klutch.sh provides several advantages for web analytics:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Vince without complex orchestration. Push to GitHub, and your analytics platform deploys automatically.

Persistent Storage: Attach persistent volumes for your analytics database. Your historical data survives container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure data transmission from your websites.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Always Available: Your analytics keep running 24/7 without managing your own infrastructure.

Prerequisites

Before deploying Vince on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • Basic familiarity with Docker and containerization concepts
  • A website where you want to track analytics

Preparing Your Repository

Create a GitHub repository containing your Dockerfile for Vince deployment.

Repository Structure

vince-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

FROM vinceanalytics/vince:latest


# Set environment variables
ENV DATABASE_URL=${DATABASE_URL:-sqlite:///data/vince.db}
ENV SECRET_KEY_BASE=${SECRET_KEY_BASE}
ENV BASE_URL=${BASE_URL}
ENV DISABLE_REGISTRATION=${DISABLE_REGISTRATION:-false}


# Create data directory
RUN mkdir -p /data


# Expose the web interface port
EXPOSE 8000


# Volume for persistent data
VOLUME ["/data"]


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8000/health || exit 1

Environment Variables Reference

VariableRequiredDefaultDescription
DATABASE_URLNosqlite:///data/vince.dbDatabase connection string
SECRET_KEY_BASEYes-Secret key for session encryption (64+ characters)
BASE_URLYes-Public URL of your Vince instance
DISABLE_REGISTRATIONNofalseDisable new user registrations

Deploying Vince on Klutch.sh

    Generate a Secret Key

    Generate a secure secret key for your deployment:

    Terminal window
    openssl rand -hex 64

    Push Your Repository to GitHub

    Initialize your repository and push to GitHub with your Dockerfile and configuration files.

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “vince-analytics” or “web-analytics”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Vince Dockerfile.

    Configure HTTP Traffic

    In the deployment settings:

    • Select HTTP as the traffic type
    • Set the internal port to 8000

    Set Environment Variables

    Add the following environment variables:

    VariableValue
    SECRET_KEY_BASEYour generated 64+ character secret
    BASE_URLhttps://your-app-name.klutch.sh
    DISABLE_REGISTRATIONtrue (after creating your account)

    Attach Persistent Volumes

    Add the following volume:

    Mount PathRecommended SizePurpose
    /data5 GBSQLite database with analytics data

    Deploy Your Application

    Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and provision an HTTPS certificate.

    Access Vince

    Once deployment completes, access your Vince instance at https://your-app-name.klutch.sh. Register your admin account.

Adding Your Website

Creating a Site

  1. Log in to your Vince dashboard
  2. Click Add Site
  3. Enter your website domain
  4. Copy the provided tracking script

Installing the Tracking Script

Add the tracking script to your website’s HTML:

<script defer data-domain="yourdomain.com" src="https://your-vince-instance.klutch.sh/js/script.js"></script>

Place this in the <head> section of your pages or before the closing </body> tag.

Verifying Installation

  1. Visit your website in a browser
  2. Check the Vince dashboard for incoming data
  3. Verify page views are being recorded

Understanding Your Analytics

Key Metrics

  • Unique Visitors: Individual users visiting your site
  • Page Views: Total pages viewed
  • Bounce Rate: Single-page sessions percentage
  • Visit Duration: Average time spent on site
  • Top Pages: Most visited pages
  • Referrers: Traffic sources
  • Countries: Geographic distribution
  • Devices: Browser and device breakdown

Filtering Data

  • Select date ranges for historical analysis
  • Filter by specific pages or paths
  • View traffic by source or medium
  • Compare time periods

Advanced Configuration

Custom Events

Track specific user actions:

// Track button clicks
document.getElementById('signup-btn').addEventListener('click', function() {
    plausible('Signup');
});


// Track form submissions
document.querySelector('form').addEventListener('submit', function() {
    plausible('Form Submit', { props: { form: 'contact' } });
});

Goal Tracking

  1. Navigate to Site Settings > Goals
  2. Add custom goals for conversions
  3. Track goal completions in your dashboard

Multiple Sites

Track multiple websites from one Vince instance:

  1. Add each site in the dashboard
  2. Use the appropriate tracking script for each domain
  3. View analytics per-site or aggregated

Privacy Considerations

Vince is designed with privacy in mind:

  • No cookies required
  • No personal data stored
  • IP addresses are never logged
  • Data stays on your server
  • Compliant with GDPR, CCPA, and PECR

Troubleshooting

No Data Appearing

  • Verify the tracking script is installed correctly
  • Check that the domain matches your site configuration
  • Disable ad blockers that might block the script
  • Verify CORS settings allow your domain

Script Not Loading

  • Confirm your Vince instance is running
  • Check browser console for errors
  • Verify HTTPS is working correctly

Additional Resources

Conclusion

Deploying Vince on Klutch.sh gives you privacy-focused web analytics with full control over your data. The combination of Vince’s lightweight approach and Klutch.sh’s deployment simplicity means you can quickly gain insights into your website traffic while respecting visitor privacy and avoiding cookie consent requirements.