Deploying Medama Analytics

Introduction

Medama Analytics is a lightweight, privacy-focused web analytics platform designed as an alternative to Google Analytics. Built with Go for high performance and minimal resource usage, Medama provides essential website metrics without using cookies or collecting personal data, making it compliant with GDPR and other privacy regulations.

The platform focuses on simplicity and speed, offering a clean dashboard that shows the metrics that matter most: page views, unique visitors, referrers, and geographic distribution. With a tracking script under 1KB, Medama has minimal impact on your website’s loading performance.

Key highlights of Medama Analytics:

• Privacy-First: No cookies, no personal data collection, fully GDPR compliant
• Lightweight Script: Under 1KB tracking script that won’t slow down your site
• Fast Performance: Built with Go for minimal server resource usage
• Simple Dashboard: Clean, intuitive interface showing essential metrics
• Self-Hosted: Complete control over your analytics data
• Real-Time Stats: View visitor activity as it happens
• Multi-Site Support: Track multiple websites from a single instance
• Open Source: Transparent, auditable codebase

This guide walks through deploying Medama Analytics on Klutch.sh using Docker, configuring persistent storage for your analytics data, and integrating the tracking script into your websites.

Why Deploy Medama Analytics on Klutch.sh

Deploying Medama Analytics on Klutch.sh provides several advantages for privacy-focused web analytics:

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

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

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure transmission of analytics data.

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

Scalable Resources: Allocate CPU and memory based on your traffic volume and analytics needs.

Custom Domains: Assign a custom domain to your analytics instance, which can help avoid ad blockers that target known analytics domains.

Always-On Availability: Your analytics service remains accessible 24/7, ensuring no data gaps.

Prerequisites

Before deploying Medama Analytics 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 add analytics tracking
• (Optional) A custom domain for your analytics instance

Preparing Your Repository

To deploy Medama Analytics on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/medama-io/medama:latest

# Set environment variables
ENV MEDAMA_DATABASE_PATH=/data/medama.db
ENV MEDAMA_PORT=8080

# Create data directory
RUN mkdir -p /data

# Expose the web interface port
EXPOSE 8080

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

Environment Variables Reference

Variable	Required	Default	Description
MEDAMA_DATABASE_PATH	No	./medama.db	Path to SQLite database file
MEDAMA_PORT	No	8080	Port for the web interface
MEDAMA_SECRET_KEY	Yes	-	Secret key for session encryption
MEDAMA_ADMIN_EMAIL	No	-	Admin account email
MEDAMA_ADMIN_PASSWORD	No	-	Admin account password

Deploying on Klutch.sh

Generate a Secret Key

Before deployment, generate a secure secret key:

openssl rand -hex 32

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Medama Analytics configuration"
git remote add origin https://github.com/yourusername/medama-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 “medama” 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 Medama Dockerfile.

Configure HTTP Traffic

Medama serves its web interface over HTTP. In the deployment settings:

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

Set Environment Variables

Add the following environment variables:

Variable	Value
MEDAMA_SECRET_KEY	Your generated secret key
MEDAMA_DATABASE_PATH	/data/medama.db
MEDAMA_ADMIN_EMAIL	Your admin email
MEDAMA_ADMIN_PASSWORD	Your admin password

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/data	5 GB	SQLite database for analytics data

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

Access Medama Analytics

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

Initial Setup

Creating Your Account

1. Navigate to your Medama Analytics dashboard
2. If admin credentials were set via environment variables, log in with those
3. Otherwise, follow the setup wizard to create your first account

Adding Your First Website

1. Click Add Website in the dashboard
2. Enter your website’s domain (e.g., example.com)
3. Copy the generated tracking script

Installing the Tracking Script

Add the tracking script to your website’s HTML, just before the closing </head> tag:

<script defer src="https://your-medama.klutch.sh/js/script.js" data-website-id="YOUR_WEBSITE_ID"></script>

Dashboard Features

Visitor Metrics

The dashboard displays:

• Unique Visitors: Individual users visiting your site
• Page Views: Total pages viewed
• Bounce Rate: Percentage of single-page sessions
• Session Duration: Average time spent on site

Traffic Sources

See where your visitors come from:

• Referrers: Websites linking to you
• Direct Traffic: Visitors who typed your URL directly
• Search Engines: Organic search traffic

Geographic Data

View visitor locations:

• Countries: Distribution by country
• Regions: More specific geographic data (when available)

Page Performance

Track individual page metrics:

• Top Pages: Most visited pages
• Entry Pages: Where visitors land first
• Exit Pages: Where visitors leave

Privacy Compliance

How Medama Protects Privacy

• No Cookies: Uses a hash-based system instead of cookies
• No Personal Data: Doesn’t collect IP addresses or personal identifiers
• Anonymized Data: All metrics are aggregated and anonymized
• Minimal Tracking: Only collects essential metrics

GDPR Compliance

Medama’s privacy-first approach means:

• No cookie consent banner required
• No personal data processing
• Data stays on your server
• Users cannot be individually identified

Multi-Site Tracking

Adding Additional Websites

1. Navigate to Settings > Websites
2. Click Add Website
3. Enter the domain and get the tracking code
4. Install the tracking script on the new site

Switching Between Sites

Use the dropdown in the dashboard header to switch between tracked websites.

Troubleshooting

Tracking Not Working

• Verify the script is loaded correctly (check browser console)
• Ensure the website ID matches your configuration
• Check that your analytics domain is accessible
• Verify HTTPS is working correctly

Dashboard Not Loading

• Check container logs for errors
• Verify the database path is correct
• Ensure the persistent volume is mounted

Missing Data

• Confirm visitors are reaching pages with the tracking script
• Check that the script isn’t being blocked by ad blockers
• Verify your site’s Content Security Policy allows the script

Additional Resources

• Medama Analytics GitHub Repository
• Medama Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Medama Analytics on Klutch.sh gives you a privacy-focused, self-hosted analytics solution that respects your visitors while still providing valuable insights. The combination of Medama’s lightweight architecture and Klutch.sh’s reliable infrastructure delivers fast, always-available analytics without compromising user privacy.

Whether you’re required to be GDPR compliant or simply want to offer your visitors a privacy-respecting experience, Medama Analytics on Klutch.sh provides the foundation for ethical web analytics that you fully control.