Deploying Litlyx

Introduction

Litlyx is a modern, open-source web analytics platform that puts privacy first without sacrificing insights. As a powerful alternative to Google Analytics, Mixpanel, Plausible, Umami, and Matomo, Litlyx provides comprehensive visitor tracking, custom events, and user funnel analysis while remaining fully GDPR compliant. The platform can be set up in just 30 seconds and displays all your data on a simple, AI-powered dashboard.

Built with a focus on simplicity and privacy, Litlyx collects anonymous website data including visits, custom events, and user journeys without requiring cookie consent banners. The AI-enhanced dashboard helps you understand your data faster, surfacing insights that might otherwise go unnoticed.

Key highlights of Litlyx:

• 30-Second Setup: One-line integration with any technology stack
• Privacy-First Design: GDPR-compliant tracking without cookies or consent banners
• AI-Powered Dashboard: Intelligent insights and automated data analysis
• Custom Events: Track any user interaction meaningful to your business
• User Funnels: Understand how users navigate through your site
• Real-Time Analytics: See visitor activity as it happens
• Fully Self-Hostable: Complete control over your data with Docker deployment
• EU Hosting Compliance: Host within the EU for full data sovereignty
• Technology Agnostic: Works with any frontend framework or backend stack
• Open Source: Transparent codebase with active community development

This guide walks through deploying Litlyx on Klutch.sh using Docker, configuring your analytics dashboard, and integrating tracking into your websites.

Why Deploy Litlyx on Klutch.sh

Deploying Litlyx on Klutch.sh provides several advantages for your analytics operations:

Complete Data Ownership: Self-hosting means your analytics data never leaves your infrastructure. You maintain full control and compliance.

Simple Deployment: Klutch.sh automatically builds and deploys your Litlyx container from Docker Compose configurations. One command gets you running.

Persistent Storage: Attach persistent volumes for your database and analytics data. Historical metrics survive container restarts and redeployments.

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

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

Scalable Resources: Allocate CPU and memory based on traffic volume. Start small and scale as your tracked sites grow.

Environment Variable Security: Store database credentials and API keys securely through Klutch.sh’s environment variable system.

Custom Domains: Use your own domain for your analytics dashboard, maintaining brand consistency.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Litlyx configuration
• Basic familiarity with Docker and containerization concepts
• Websites you want to track with Litlyx analytics
• (Optional) A custom domain for your analytics dashboard

Understanding Litlyx Architecture

Litlyx uses a modern architecture designed for performance and privacy:

Dashboard Application: The main web interface provides visualization, configuration, and management of your analytics data through an intuitive, AI-enhanced interface.

Data Ingestion: Lightweight tracking scripts send anonymous visitor data to your Litlyx instance for processing and storage.

Database Layer: Analytics data is stored in a database for historical analysis and reporting.

API Layer: RESTful APIs enable integration with external tools and custom dashboards.

Preparing Your Repository

To deploy Litlyx on Klutch.sh, create a GitHub repository containing your Docker configuration.

Repository Structure

litlyx-deploy/
├── docker-compose.yml
├── Dockerfile
└── .dockerignore

Creating the Docker Configuration

Create a docker-compose.yml in your repository:

version: '3.8'

services:
  litlyx:
    image: litlyx/litlyx:latest
    container_name: litlyx
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - NEXTAUTH_SECRET=${NEXTAUTH_SECRET}
      - NEXTAUTH_URL=${NEXTAUTH_URL}
    volumes:
      - litlyx_data:/app/data

volumes:
  litlyx_data:

Creating the Dockerfile

Create a Dockerfile for Klutch.sh deployment:

FROM litlyx/litlyx:latest

# Set environment variables
ENV NODE_ENV=production

# Expose the dashboard port
EXPOSE 3000

# The base image includes the default entrypoint

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local
node_modules

Environment Variables Reference

Litlyx requires several environment variables for operation:

Variable	Required	Description
DATABASE_URL	Yes	Connection string for your database
NEXTAUTH_SECRET	Yes	Secret key for session encryption
NEXTAUTH_URL	Yes	Public URL of your Litlyx instance

Deploying Litlyx on Klutch.sh

Once your repository is prepared, follow these steps to deploy Litlyx:

Generate Security Keys

Generate a secure secret for session management:

openssl rand -base64 32

Save this key securely for the environment variables configuration.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile docker-compose.yml .dockerignore
git commit -m "Initial Litlyx deployment configuration"
git remote add origin https://github.com/yourusername/litlyx-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “litlyx” or “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 Litlyx configuration.

Configure HTTP Traffic

In the deployment settings:

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

Set Environment Variables

In the environment variables section, add the following:

Variable	Value
DATABASE_URL	Your database connection string
NEXTAUTH_SECRET	Your generated secret key
NEXTAUTH_URL	https://your-app-name.klutch.sh

Attach Persistent Volumes

Add persistent storage for your analytics data:

Mount Path	Recommended Size	Purpose
/app/data	10 GB	Analytics data and application state

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Litlyx container
• Provision an HTTPS certificate

Access Litlyx

Once deployment completes, access your analytics dashboard at https://your-app-name.klutch.sh.

Initial Setup and Configuration

Creating Your First Project

After accessing your Litlyx dashboard:

1. Create Account: Register your admin account
2. Create Project: Add your first website to track
3. Get Tracking Code: Copy the tracking snippet for integration
4. Configure Settings: Set up project-specific options

Dashboard Overview

The Litlyx dashboard provides several key views:

• Overview: Real-time visitor counts and key metrics
• Visitors: Detailed visitor analysis and demographics
• Pages: Most visited pages and content performance
• Sources: Traffic sources and referral analysis
• Events: Custom event tracking and conversions
• Funnels: User journey and conversion funnel analysis

Integrating Litlyx Tracking

JavaScript Integration

Add the Litlyx tracking script to your website:

<script defer src="https://your-litlyx-instance.klutch.sh/js/script.js"
        data-project="YOUR_PROJECT_ID"></script>

Self-Hosted Instance Configuration

When forwarding data to your self-hosted instance, configure these variables in your tracking code:

• data-host: Your Litlyx instance hostname
• data-port: The port your instance runs on
• data-secure: Set to true for HTTPS, false for HTTP

Framework-Specific Integration

React/Next.js

import { useEffect } from 'react';

export default function Analytics() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://your-litlyx-instance.klutch.sh/js/script.js';
    script.defer = true;
    script.dataset.project = 'YOUR_PROJECT_ID';
    document.body.appendChild(script);
  }, []);

  return null;
}

Vue.js

<script setup>
import { onMounted } from 'vue';

onMounted(() => {
  const script = document.createElement('script');
  script.src = 'https://your-litlyx-instance.klutch.sh/js/script.js';
  script.defer = true;
  script.dataset.project = 'YOUR_PROJECT_ID';
  document.body.appendChild(script);
});
</script>

Custom Event Tracking

Track custom events for deeper insights:

// Track a button click
litlyx.track('button_click', {
  button_name: 'signup',
  page: 'homepage'
});

// Track a purchase
litlyx.track('purchase', {
  product_id: 'SKU123',
  amount: 49.99,
  currency: 'USD'
});

AI-Powered Insights

Understanding AI Features

Litlyx’s AI capabilities help you:

• Identify Trends: Automatically detect unusual traffic patterns
• Surface Insights: Highlight important metrics you might miss
• Generate Reports: Create natural language summaries of your data
• Predict Behavior: Forecast future traffic based on historical patterns

Configuring AI Analysis

1. Access Settings → AI Features
2. Enable the insights you want to track
3. Configure notification preferences
4. Review AI-generated reports in the dashboard

Production Best Practices

Security Recommendations

• Secure Secrets: Use strong, unique values for NEXTAUTH_SECRET
• HTTPS Only: Ensure all tracked sites use HTTPS
• Access Control: Implement user authentication for dashboard access
• Regular Updates: Keep your Litlyx image updated for security patches

Performance Optimization

• Script Loading: Use defer attribute for non-blocking script loading
• Data Retention: Configure appropriate data retention policies
• Database Optimization: Regular database maintenance for large datasets

Privacy Compliance

• GDPR Compliance: Litlyx is designed to be GDPR-compliant out of the box
• No Cookies: By default, Litlyx doesn’t use cookies
• Data Minimization: Only collect data necessary for analytics
• Privacy Policy: Update your site’s privacy policy to mention analytics

Backup Strategy

Protect your analytics data:

1. Database Backups: Regularly back up your database
2. Configuration Export: Export project settings periodically
3. Data Export: Use the API to export raw analytics data

Troubleshooting Common Issues

Tracking Not Working

Symptoms: No data appearing in dashboard.

Solutions:

• Verify tracking script is loaded correctly
• Check browser console for JavaScript errors
• Ensure project ID matches your configuration
• Verify network requests are reaching your Litlyx instance

Dashboard Not Loading

Symptoms: Cannot access analytics dashboard.

Solutions:

• Verify deployment is running in Klutch.sh dashboard
• Check environment variables are set correctly
• Review deployment logs for errors
• Ensure NEXTAUTH_URL matches your actual URL

Data Discrepancies

Symptoms: Numbers don’t match expected traffic.

Solutions:

• Check for ad blockers affecting tracking
• Verify script is on all pages
• Review bot filtering settings
• Compare with server access logs

Performance Issues

Symptoms: Dashboard loads slowly.

Solutions:

• Increase allocated resources
• Check database performance
• Review data retention policies
• Optimize queries for large datasets

Additional Resources

• Litlyx GitHub Repository
• Litlyx Documentation
• Litlyx Docker Self-Hosting Guide
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Litlyx on Klutch.sh gives you a powerful, privacy-first analytics platform with complete data ownership. The combination of Litlyx’s simple setup, AI-powered insights, and GDPR compliance with Klutch.sh’s deployment automation means you can understand your users without compromising their privacy.

With support for custom events, user funnels, and real-time tracking, Litlyx provides the insights you need to grow your website. The self-hosted approach ensures your analytics data stays under your control, meeting even the strictest compliance requirements.

Whether you’re tracking a personal blog or multiple enterprise websites, Litlyx on Klutch.sh provides a reliable, privacy-respecting analytics solution that scales with your needs.