Deploying Liwan

Introduction

Liwan is a lightweight, privacy-first web analytics platform designed for developers who want insights without compromising user privacy. Written in Rust for maximum performance and efficiency, Liwan operates without cookies, cross-site tracking, or persistent identifiers. The entire application runs as a single binary with data stored in a local DuckDB or SQLite file, making it incredibly easy to deploy and maintain.

Unlike traditional analytics platforms that harvest user data, Liwan provides accurate visitor statistics while respecting privacy by design. Bot and crawler traffic is automatically filtered using user-agent analysis and referrer lists, ensuring your data reflects real human visitors. The modern dashboard, built with Astro and D3.js, delivers fast, interactive visualizations.

Key highlights of Liwan:

Privacy-First Design: No cookies, no cross-site tracking, no persistent identifiers
Lightweight: Single binary with embedded database, minimal resource usage
Fast Performance: Built with Rust and Tokio for high-throughput async I/O
Real-Time Analytics: See visitor activity as it happens
Bot Filtering: Automatic detection and filtering of bots and crawlers
Query Caching: Intelligent caching reduces database load
Flexible Storage: Choose between DuckDB or SQLite backends
Interactive Charts: Client-side D3 visualizations for responsive dashboards
Easy Setup: Deploy in minutes with minimal configuration
GDPR Compliant: No consent banners required
Open Source: Apache 2.0 licensed with active development

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

Why Deploy Liwan on Klutch.sh

Deploying Liwan on Klutch.sh provides several advantages:

Complete Data Control: Self-hosting means your analytics data stays on your infrastructure with no third-party access.

Simple Deployment: Liwan’s single-binary design makes deployment straightforward with minimal configuration.

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

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure tracking script delivery.

GitHub Integration: Connect your configuration repository directly from GitHub. Push updates to trigger automatic redeployments.

Cost-Effective: Liwan’s minimal resource requirements keep hosting costs low while delivering powerful analytics.

Custom Domains: Use your own domain for your analytics dashboard and tracking endpoint.

Privacy Compliance: No cookies means no consent banners required for GDPR compliance.

Prerequisites

Before deploying Liwan 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
Websites you want to track
(Optional) A custom domain for your analytics

Understanding Liwan Architecture

Liwan uses a streamlined architecture optimized for performance and simplicity:

Rust Backend: The core application is built with Rust, using Tokio for async I/O. This provides excellent performance with low memory footprint.

DuckDB/SQLite Storage: Analytics data is stored in either DuckDB (default) or SQLite. Both are embedded databases that don’t require separate services.

Query Caching: Frequently requested data is cached to reduce database load and speed up dashboard queries.

Astro Frontend: The dashboard is built with Astro for fast loading, with D3.js providing interactive chart visualizations.

Event Processing: Pageviews and custom events are processed asynchronously using Tokio channels, with bot filtering applied before storage.

Preparing Your Repository

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

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/explodingcamera/liwan:latest

# Set environment variables
ENV LIWAN_PORT=9042
ENV LIWAN_HOST=0.0.0.0
ENV LIWAN_DATA_DIR=/data

# Create data directory
RUN mkdir -p /data

# Expose the web interface port
EXPOSE 9042

# 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

Environment Variables Reference

Liwan supports configuration through environment variables:

Variable	Required	Default	Description
`LIWAN_PORT`	No	`9042`	Port to listen on
`LIWAN_HOST`	No	`127.0.0.1`	Host address to bind
`LIWAN_DATA_DIR`	No	`./data`	Directory for database storage
`LIWAN_DATABASE`	No	`duckdb`	Database backend: `duckdb` or `sqlite`
`LIWAN_SECRET`	Recommended	-	Secret key for session management

Deploying Liwan on Klutch.sh

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

Generate a Secret Key

Generate a secure secret for session management:

openssl rand -hex 32

Save this securely for the environment variables configuration.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore
git commit -m "Initial Liwan deployment configuration"
git remote add origin https://github.com/yourusername/liwan-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 “liwan” 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 Liwan configuration.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 9042

Set Environment Variables

In the environment variables section, add:

Variable	Value
`LIWAN_PORT`	`9042`
`LIWAN_HOST`	`0.0.0.0`
`LIWAN_DATA_DIR`	`/data`
`LIWAN_SECRET`	Your generated secret key

Attach Persistent Volumes

Add persistent storage for your analytics data:

Mount Path	Recommended Size	Purpose
`/data`	5 GB	Analytics database and configuration

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

Access Liwan

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

Initial Setup

First-Time Configuration

When you first access Liwan:

Create Admin Account: Set up your administrator credentials
Add Website: Register your first website to track
Get Tracking Script: Copy the tracking code for installation

Adding Websites

Navigate to Settings → Websites
Click Add Website
Enter your website domain
Copy the generated tracking script

Integrating Tracking

Basic Tracking Script

Add the tracking script to your website:

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

Place this in your <head> tag for best results.

Single Page Applications

For SPAs (React, Vue, Angular), use the JavaScript API:

// Track page views on route change
window.liwan.trackPageview();

// Track with custom properties
window.liwan.trackPageview({
  url: window.location.href,
  referrer: document.referrer
});

Custom Events

Track custom events for deeper insights:

// Track a button click
window.liwan.trackEvent('signup_click');

// Track with properties
window.liwan.trackEvent('purchase', {
  product: 'Premium Plan',
  value: 99.99
});

Framework Integration

Next.js

// pages/_app.js or app/layout.js
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <Script
          defer
          src="https://your-liwan.klutch.sh/js/script.js"
          data-domain="yourdomain.com"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

Vue/Nuxt

export default {
  head: {
    script: [
      {
        src: 'https://your-liwan.klutch.sh/js/script.js',
        defer: true,
        'data-domain': 'yourdomain.com'
      }
    ]
  }
}

Dashboard Features

Real-Time Overview

The main dashboard shows:

Current Visitors: Live count of active visitors
Page Views: Total and per-page breakdown
Unique Visitors: Distinct visitor counts
Bounce Rate: Single-page visit percentage
Visit Duration: Average time on site

Traffic Sources

Understand where visitors come from:

Referrers: Sites linking to you
Search Engines: Organic search traffic
Social Media: Traffic from social platforms
Direct: Visitors typing your URL directly

Geographic Data

See visitor locations:

Countries: Visitor distribution by country
Regions: Regional breakdown where available
Cities: City-level data for detailed analysis

Technology Breakdown

Understand visitor technology:

Browsers: Chrome, Firefox, Safari, etc.
Operating Systems: Windows, macOS, Linux, iOS, Android
Device Types: Desktop, mobile, tablet

Custom Events

Track and analyze custom events:

View event counts over time
Break down by event properties
Compare event performance

Bot Filtering

Automatic Detection

Liwan automatically filters:

Known bot user agents
Search engine crawlers
Monitoring services
Automated tools

Filtering Methods

Bot detection uses:

User-Agent Analysis: Pattern matching against known bots
Referrer Lists: Filtering spam referrers
Behavior Analysis: Detecting automated patterns

Production Best Practices

Security Recommendations

Secure Secret: Use a strong, unique LIWAN_SECRET
HTTPS Only: Ensure tracking script is served over HTTPS
Access Control: Protect your dashboard with strong passwords

Performance Optimization

Query Caching: Enabled by default for better performance
Database Selection: DuckDB is recommended for analytics workloads
Resource Allocation: Start small and scale based on traffic

Data Management

Retention Policies: Configure how long to keep historical data
Regular Backups: Back up your data directory regularly
Export Options: Use the API for data export

Backup Strategy

Protect your analytics data:

Database Backup: Back up /data directory regularly
Configuration Export: Save website configurations
Automation: Set up automated backup schedules

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 data-domain matches your registered domain
Test in incognito mode (ad blockers may interfere)

Dashboard Loading Slowly

Symptoms: Charts take long to load.

Solutions:

Check available resources
Enable query caching
Review date range selections (smaller ranges load faster)
Check database file size

Bot Traffic Appearing

Symptoms: Suspicious traffic patterns in data.

Solutions:

Update to the latest Liwan version
Check bot filtering configuration
Review referrer filtering lists
Report false negatives to the project

Data Discrepancies

Symptoms: Numbers don’t match expectations.

Solutions:

Compare with server access logs
Check for multiple tracking scripts
Verify domain configuration
Review bot filtering impact

Additional Resources

Conclusion

Deploying Liwan on Klutch.sh gives you a fast, privacy-respecting analytics platform with minimal overhead. The Rust-based architecture delivers excellent performance while the embedded database keeps deployment simple and resource-efficient.

With automatic bot filtering, real-time analytics, and custom event tracking, Liwan provides the insights you need without compromising visitor privacy. The GDPR-compliant design means no cookie consent banners are required, improving user experience while staying compliant with privacy regulations.

Whether you’re tracking a personal blog or multiple business websites, Liwan on Klutch.sh provides a reliable, self-hosted analytics solution that respects both your users’ privacy and your need for actionable data.