Deploying GoatCounter

Introduction

GoatCounter is an open-source web analytics platform that provides meaningful insights without tracking personal data or using cookies. Designed as a privacy-friendly alternative to Google Analytics, GoatCounter gives you the statistics you need while respecting your visitors’ privacy.

Built with simplicity in mind, GoatCounter is lightweight (adding only ~3.5KB to your page), fast, and easy to deploy. The platform tracks page views, referrers, browser information, and more without requiring GDPR consent notices or cookie banners.

Key highlights of GoatCounter:

• No Cookies: Completely cookieless analytics - no consent banners needed
• Privacy-First: No personal data collection or user tracking
• GDPR Compliant: Works without requiring privacy notices
• Lightweight: Adds only ~3.5KB to your website
• Simple Dashboard: Clean, easy-to-understand analytics interface
• SQLite or PostgreSQL: Flexible database options
• Public Statistics: Option to make your stats publicly viewable
• CSV Export: Export your data anytime
• API Access: Full API for custom integrations
• 100% Open Source: Licensed under EUPL with no restrictions

This guide walks through deploying GoatCounter on Klutch.sh using Docker, configuring your analytics, and integrating with your website.

Why Deploy GoatCounter on Klutch.sh

Deploying GoatCounter on Klutch.sh provides several advantages for privacy-friendly analytics:

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

Persistent Storage: Attach persistent volumes for your database and configuration. Analytics data survives container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure data collection.

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

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

Custom Domains: Assign a custom domain for your analytics instance.

Always-On Availability: Your analytics collection remains active 24/7.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your GoatCounter configuration
• A website to add analytics to
• Basic familiarity with Docker and containerization concepts
• (Optional) A custom domain for your GoatCounter instance

Understanding GoatCounter Architecture

GoatCounter is designed for simplicity:

Go Backend: Written in Go for excellent performance and minimal resource usage.

Database Options: Supports SQLite for small to medium sites or PostgreSQL for larger deployments.

Tracking Script: A lightweight JavaScript snippet collects pageview data.

Dashboard: A clean web interface displays your analytics.

API: RESTful API for data export and integration.

Preparing Your Repository

To deploy GoatCounter on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM arp242/goatcounter:latest

# Set environment variables
ENV GOATCOUNTER_LISTEN=:8080
ENV GOATCOUNTER_DB=sqlite3:/goatcounter/db/goatcounter.sqlite3

# Create database directory
RUN mkdir -p /goatcounter/db

# Expose the web interface port
EXPOSE 8080

# Default command
CMD ["serve", "-listen", ":8080", "-db", "sqlite3:/goatcounter/db/goatcounter.sqlite3", "-tls", "none"]

Advanced Dockerfile with PostgreSQL

For larger deployments:

FROM arp242/goatcounter:latest

# Database Configuration (PostgreSQL)
ENV GOATCOUNTER_DB=${GOATCOUNTER_DB}

# 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/ || exit 1

# Command to run GoatCounter
CMD ["serve", "-listen", ":8080", "-db", "${GOATCOUNTER_DB}", "-tls", "none"]

Creating the .dockerignore File

Create a .dockerignore file:

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

Environment Variables Reference

Variable	Required	Default	Description
GOATCOUNTER_LISTEN	No	:8080	Address and port to listen on
GOATCOUNTER_DB	Yes	-	Database connection string
GOATCOUNTER_SMTP	No	-	SMTP server for email notifications
GOATCOUNTER_EMAIL_FROM	No	-	From address for emails

Database connection string formats:

• SQLite: sqlite3:/path/to/db.sqlite3
• PostgreSQL: postgresql://user:password@host:port/database

Deploying GoatCounter on Klutch.sh

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

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

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

Configure HTTP Traffic

GoatCounter 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

In the environment variables section, add:

Variable	Value
GOATCOUNTER_DB	sqlite3:/goatcounter/db/goatcounter.sqlite3

For PostgreSQL, use the connection string from your database. See the PostgreSQL deployment guide.

Attach Persistent Volumes

Persistent storage is essential for GoatCounter. Add the following volume:

Mount Path	Recommended Size	Purpose
/goatcounter/db	10 GB	SQLite database storing all 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 GoatCounter container
• Provision an HTTPS certificate

Create Your First Site

After deployment, create your first site. Access the container and run:

goatcounter db create site -vhost="stats.example.com" -user.email="your@email.com"

Replace stats.example.com with your Klutch.sh URL or custom domain.

Access GoatCounter

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

Adding GoatCounter to Your Website

Basic Integration

Add this script tag to your website:

<script data-goatcounter="https://your-app-name.klutch.sh/count"
        async src="//your-app-name.klutch.sh/count.js"></script>

Tracking Options

GoatCounter supports various tracking configurations:

<script>
    window.goatcounter = {
        path: function(p) { return location.host + p },
        // Custom path function

        title: 'Custom Page Title',
        // Override the page title

        referrer: 'https://example.com',
        // Override the referrer

        event: true,
        // Track as an event rather than pageview
    }
</script>
<script data-goatcounter="https://your-app-name.klutch.sh/count"
        async src="//your-app-name.klutch.sh/count.js"></script>

Manual Tracking (No JavaScript)

For users with JavaScript disabled, use a tracking pixel:

<noscript>
    <img src="https://your-app-name.klutch.sh/count?p=/page-path">
</noscript>

Event Tracking

Track custom events:

// Track a button click
document.querySelector('#signup-button').addEventListener('click', function() {
    goatcounter.count({
        path: 'signup-button-click',
        title: 'Signup Button Click',
        event: true,
    });
});

Understanding the Dashboard

Available Metrics

GoatCounter tracks several privacy-friendly metrics:

Metric	Description
Page Views	Total and unique page views
Visitors	Estimated unique visitors (without cookies)
Pages	Most viewed pages
Referrers	Where visitors come from
Browsers	Browser breakdown
Systems	Operating system breakdown
Screen Sizes	Viewport dimensions
Locations	Visitor countries
Languages	Browser language preferences

Date Range Selection

Filter data by date range:

• Today, Yesterday, Last 7 days, Last 30 days
• Custom date ranges
• Compare periods

Exporting Data

Export your data for external analysis:

1. Navigate to Settings > Export
2. Select date range and format (CSV)
3. Download your data

Managing Multiple Sites

GoatCounter supports multiple sites from a single installation:

1. Access settings in the dashboard
2. Navigate to Sites
3. Add new sites with different vhosts
4. Each site gets its own tracking code

API Integration

GoatCounter provides a full REST API:

Authentication

Create an API token in Settings > API.

Example: Get Page Views

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://your-app-name.klutch.sh/api/v0/stats/total"

Example: Export Data

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://your-app-name.klutch.sh/api/v0/export" > export.csv

Security Considerations

Access Control

• Admin Accounts: Use strong passwords for admin accounts
• API Tokens: Treat API tokens as sensitive credentials
• Public Stats: Decide if your statistics should be public

Data Privacy

• No PII: GoatCounter doesn’t collect personally identifiable information
• Data Retention: Configure how long to keep data
• GDPR Compliance: No consent required, but review your specific requirements

Troubleshooting Common Issues

Tracking Not Working

Symptoms: Page views not appearing in dashboard.

Solutions:

• Verify the tracking script is loading (check browser console)
• Ensure the data-goatcounter URL is correct
• Check for ad blockers that might block the script
• Verify HTTPS is working on both sites

Dashboard Access Issues

Symptoms: Cannot access the dashboard.

Solutions:

• Verify the deployment is running
• Check database connectivity
• Review application logs for errors
• Ensure the site is created in the database

Database Errors

Symptoms: Application crashes or data not saving.

Solutions:

• Verify persistent volume is mounted
• Check database file permissions
• Ensure sufficient disk space
• For PostgreSQL, verify connection credentials

Additional Resources

• Official GoatCounter Website
• GoatCounter Documentation
• GoatCounter GitHub Repository
• GoatCounter API Documentation
• Klutch.sh PostgreSQL Guide
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying GoatCounter on Klutch.sh gives you a privacy-friendly analytics platform that respects your visitors while providing meaningful insights. The combination of GoatCounter’s lightweight design and Klutch.sh’s deployment simplicity means you can track your website’s performance without the complexity of traditional analytics platforms.

With no cookies, no personal data collection, and GDPR compliance built-in, GoatCounter lets you understand your audience without compromising their privacy. Whether you’re running a personal blog or a business website, GoatCounter on Klutch.sh delivers the analytics you need without the privacy concerns.