Skip to content
Klutch.sh Docs

Deploying LHA

Introduction

LHA (Link Hover Analytics) is a lightweight, privacy-focused analytics platform designed to track user interactions on your website without the overhead of traditional analytics solutions. It provides insights into how users engage with links and interactive elements on your pages.

Built for simplicity and performance, LHA captures essential interaction data while respecting user privacy. The application runs as a small service that receives tracking events from a lightweight JavaScript snippet embedded in your pages.

Key features of LHA:

  • Link Click Tracking: Monitor which links users click
  • Hover Analytics: Track user attention through hover events
  • Lightweight Script: Minimal JavaScript footprint for fast page loads
  • Privacy-Focused: No personal data collection or cookies
  • Real-Time Dashboard: View analytics as they happen
  • Custom Events: Track custom interactions beyond links
  • API Access: Retrieve analytics data programmatically
  • Self-Hosted: Complete control over your analytics data
  • Easy Integration: Simple script tag to add to your site
  • Open Source: Fully transparent codebase

This guide walks through deploying LHA on Klutch.sh using Docker, integrating the tracking script, and viewing your analytics data.

Why Deploy LHA on Klutch.sh

Deploying LHA on Klutch.sh provides several advantages for analytics:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds LHA without complex orchestration.

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

HTTPS by Default: Klutch.sh provides automatic SSL certificates, required for cross-origin tracking.

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

Low Resource Usage: LHA is lightweight and cost-effective to run.

Environment Variable Management: Securely store configuration without exposing in code.

Custom Domains: Use your own domain for the analytics endpoint.

Always-On Availability: Analytics collection runs 24/7.

Prerequisites

Before deploying LHA 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 to add tracking to
  • (Optional) A custom domain for your analytics endpoint

Preparing Your Repository

Create a GitHub repository containing your Dockerfile for deploying LHA on Klutch.sh.

Repository Structure

lha-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM node:18-alpine


# Set working directory
WORKDIR /app


# Clone LHA (replace with actual repository if available)
RUN apk add --no-cache git && \
    git clone https://github.com/lha-analytics/lha.git .


# Install dependencies
RUN npm install


# Build for production
RUN npm run build


# Set environment variables
ENV NODE_ENV=production
ENV PORT=3000


# Expose port
EXPOSE 3000


# Start the application
CMD ["npm", "start"]

Environment Variables Reference

VariableRequiredDefaultDescription
PORTNo3000Port for the API server
DATABASE_URLYes-Database connection string
ALLOWED_ORIGINSYes-Comma-separated list of allowed domains
SECRET_KEYYes-Secret for API authentication
RETENTION_DAYSNo90Days to keep analytics data

Deploying LHA on Klutch.sh

    Generate a Secret Key

    Generate a secure secret key:

    Terminal window
    openssl rand -hex 32

    Push Your Repository to GitHub

    Initialize your repository and push to GitHub:

    Terminal window
    git init
    git add Dockerfile .dockerignore README.md
    git commit -m "Initial LHA deployment configuration"
    git remote add origin https://github.com/yourusername/lha-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 “lha” 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 LHA Dockerfile.

    Configure HTTP Traffic

    In the deployment settings:

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

    Set Environment Variables

    Add the following environment variables:

    VariableValue
    DATABASE_URLYour database connection string
    ALLOWED_ORIGINShttps://yourwebsite.com
    SECRET_KEYYour generated secret key
    NODE_ENVproduction

    Attach Persistent Volumes

    Add volumes for data persistence:

    Mount PathRecommended SizePurpose
    /app/data10 GBAnalytics database

    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 LHA container
    • Provision an HTTPS certificate

    Access LHA

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

Integrating the Tracking Script

Adding to Your Website

Add the tracking script to your website’s HTML:

<script>
(function() {
  var lha = document.createElement('script');
  lha.src = 'https://your-lha-domain.klutch.sh/tracker.js';
  lha.async = true;
  document.head.appendChild(lha);
})();
</script>

Tracking Custom Events

Track custom interactions:

// Track a custom event
LHA.track('button_click', {
  button_id: 'signup-button',
  page: window.location.pathname
});

Links are automatically tracked, but you can add metadata:

<a href="/pricing" data-lha-category="navigation" data-lha-label="pricing">
  Pricing
</a>

Viewing Analytics

Dashboard Overview

The LHA dashboard shows:

  • Total link clicks
  • Click heatmaps
  • Popular pages
  • Traffic trends
  • Referrer sources

API Access

Retrieve analytics programmatically:

Terminal window
curl -X GET https://your-lha-domain.klutch.sh/api/v1/analytics \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json"

Troubleshooting Common Issues

Tracking Not Working

  • Verify ALLOWED_ORIGINS includes your website
  • Check browser console for CORS errors
  • Ensure HTTPS is used on both ends

Data Not Persisting

  • Verify volume is mounted correctly
  • Check database connection string
  • Review container logs for errors

Dashboard Not Loading

  • Verify the application is running
  • Check environment variables are set
  • Review application logs

Additional Resources

Conclusion

Deploying LHA on Klutch.sh gives you a lightweight, privacy-focused analytics platform with automatic builds and secure HTTPS access. Track user interactions without compromising privacy or page performance.