Skip to content
Klutch.sh Docs

Deploying Ackee

Introduction

Ackee is a self-hosted, privacy-focused web analytics tool that provides valuable insights into your website’s traffic while respecting user privacy. Unlike traditional analytics platforms, Ackee doesn’t use cookies, doesn’t track users across sites, and is fully GDPR-compliant out of the box. Built with Node.js and MongoDB, Ackee offers a clean, modern interface with real-time analytics tracking.

Ackee stands out for its:

  • Privacy-First Approach: No cookies, no persistent tracking, and full GDPR compliance
  • Self-Hosted Control: Complete ownership of your analytics data
  • Real-Time Insights: Live visitor tracking and instant metrics
  • Beautiful Interface: Clean, modern dashboard with intuitive data visualization
  • Lightweight: Minimal resource usage with efficient data storage
  • GraphQL API: Flexible data access for custom integrations
  • Multiple Domain Support: Track analytics for multiple websites from a single instance

This comprehensive guide walks you through deploying Ackee analytics on Klutch.sh using Docker, including detailed installation steps, sample configurations, persistent storage setup, and production-ready best practices.

Prerequisites

Before you begin, ensure you have the following:

Installation and Setup

Step 1: Create Your Project Directory

First, create a new directory for your Ackee deployment project:

Terminal window
mkdir ackee-klutch
cd ackee-klutch
git init

Step 2: Create the Dockerfile

Create a Dockerfile in your project root directory. This will define your Ackee container configuration:

FROM node:18-alpine


# Set working directory
WORKDIR /app


# Install Ackee globally
RUN npm install -g ackee


# Create data directory for MongoDB
RUN mkdir -p /data/db


# Expose the default Ackee port
EXPOSE 3000


# Set default environment variables
ENV ACKEE_MONGODB=mongodb://localhost:27017/ackee
ENV ACKEE_USERNAME=admin
ENV ACKEE_PASSWORD=password


# Start MongoDB and Ackee
CMD mongod --fork --logpath /var/log/mongodb.log && ackee server

Note: This Dockerfile uses Node.js Alpine image for a lightweight production deployment. For a more robust setup with a separate MongoDB instance, see the advanced configuration section below.

Step 3: Advanced Dockerfile with MongoDB

For a production-ready setup with MongoDB included in the same container:

FROM node:18-alpine


# Install MongoDB
RUN apk add --no-cache mongodb mongodb-tools


# Set working directory
WORKDIR /app


# Install Ackee
RUN npm install -g ackee@3.4.0


# Create necessary directories
RUN mkdir -p /data/db /var/log


# Expose Ackee port
EXPOSE 3000


# Set environment variables (override these in Klutch.sh dashboard)
ENV ACKEE_MONGODB=mongodb://localhost:27017/ackee
ENV ACKEE_USERNAME=admin
ENV ACKEE_PASSWORD=changeme
ENV NODE_ENV=production


# Create startup script
RUN echo '#!/bin/sh' > /start.sh && \
    echo 'mongod --bind_ip 127.0.0.1 --fork --logpath /var/log/mongodb.log' >> /start.sh && \
    echo 'sleep 3' >> /start.sh && \
    echo 'ackee server' >> /start.sh && \
    chmod +x /start.sh


# Start services
CMD ["/start.sh"]

Step 4: Create Environment Configuration

Create a .env.example file to document the required environment variables:

Terminal window
# Ackee Configuration
ACKEE_MONGODB=mongodb://localhost:27017/ackee
ACKEE_USERNAME=admin
ACKEE_PASSWORD=your-secure-password-here


# Optional: Custom port (default is 3000)
ACKEE_PORT=3000


# Optional: CORS settings for tracking script
ACKEE_ALLOW_ORIGIN=*


# Optional: Auto SSL
ACKEE_AUTO_SSL=false

Security Note: Never commit actual passwords or sensitive data to your repository. Use environment variables in Klutch.sh dashboard.

Step 5: Test Locally (Optional)

Before deploying to Klutch.sh, you can test your Ackee setup locally:

Terminal window
# Build the Docker image
docker build -t my-ackee .


# Run the container
docker run -d \
  --name ackee-test \
  -p 3000:3000 \
  -e ACKEE_USERNAME=admin \
  -e ACKEE_PASSWORD=test123 \
  my-ackee


# View logs
docker logs -f ackee-test


# Access Ackee at http://localhost:3000


# Stop and remove the test container when done
docker stop ackee-test
docker rm ackee-test

Step 6: Create Sample Tracking Script Documentation

Create a README.md file with tracking script instructions:

# Ackee Analytics Deployment


## Adding Tracking to Your Website


Once Ackee is deployed, add this script to your website's HTML:


<script async src="https://example-app.klutch.sh/tracker.js" data-ackee-server="https://example-app.klutch.sh" data-ackee-domain-id="YOUR_DOMAIN_ID"></script>


Replace:
- `example-app.klutch.sh` with your actual Klutch.sh app URL
- `YOUR_DOMAIN_ID` with the domain ID from your Ackee dashboard


## Getting Your Domain ID


1. Log in to Ackee at your deployment URL
2. Go to Settings > Domains
3. Create a new domain or copy the ID of an existing one
4. Use this ID in your tracking script

Step 7: Push to GitHub

Commit your Dockerfile and configuration files to your GitHub repository:

Terminal window
git add Dockerfile .env.example README.md
git commit -m "Add Ackee Dockerfile and configuration"
git remote add origin https://github.com/yourusername/ackee-klutch.git
git push -u origin main

Deploying to Klutch.sh

Now that your Ackee project is ready and pushed to GitHub, follow these steps to deploy it on Klutch.sh with persistent storage.

Deployment Steps

    1. Log in to Klutch.sh

      Navigate to klutch.sh/app and sign in to your account.

    2. Create a New Project

      Go to Create Project and give your project a meaningful name (e.g., “Ackee Analytics”).

    3. Create a New App

      Navigate to Create App and configure the following settings:

    4. Select Your Repository

      • Choose GitHub as your Git source
      • Select the repository containing your Dockerfile
      • Choose the branch you want to deploy (usually main or master)

    5. Configure Traffic Type

      • Traffic Type: Select HTTP (Ackee serves a web interface and tracking script via HTTP)
      • Internal Port: Set to 3000 (the default port that Ackee listens on)

    6. Set Environment Variables

      Add the following environment variables for your Ackee configuration:

      • ACKEE_USERNAME: Your Ackee admin username (e.g., admin)
      • ACKEE_PASSWORD: A strong password for your admin account (use a secure password generator)
      • ACKEE_MONGODB: MongoDB connection string (e.g., mongodb://localhost:27017/ackee)
      • ACKEE_PORT: (Optional) Port number, defaults to 3000
      • ACKEE_ALLOW_ORIGIN: (Optional) Set to * for tracking from any domain, or specify your domain

      Security Note: Always use strong, unique passwords for production deployments.

    7. Attach a Persistent Volume

      This is critical for ensuring your MongoDB database data persists across deployments and restarts:

      • In the Volumes section, click “Add Volume”
      • Mount Path: Enter /data/db (this is where MongoDB stores its database files)
      • Size: Choose an appropriate size based on your expected traffic (e.g., 5GB for small sites, 20GB+ for high-traffic sites)

      Important: Ackee requires persistent storage to maintain your analytics data between container restarts.

    8. Configure Additional Settings

      • Region: Select the region closest to your users for optimal latency
      • Compute Resources: Choose CPU and memory based on your traffic (minimum 512MB RAM recommended)
      • Instances: Start with 1 instance (you can scale up later as traffic grows)

    9. Deploy Your Application

      Click “Create” to start the deployment. Klutch.sh will:

      • Automatically detect your Dockerfile in the repository root
      • Build the Docker image
      • Attach the persistent volume
      • Start your Ackee container
      • Assign a URL for external access

    10. Access Your Ackee Dashboard

      Once deployment is complete, you’ll receive a URL like example-app.klutch.sh. Navigate to this URL in your browser to access your Ackee dashboard:

      https://example-app.klutch.sh

      Log in using the username and password you set in the environment variables.

Configuring Domains and Tracking

After your Ackee instance is deployed, you need to set up domains for tracking:

Adding a Domain

  1. Log in to your Ackee dashboard at https://example-app.klutch.sh
  2. Navigate to Settings → Domains
  3. Click “New Domain”
  4. Enter your website’s domain name (e.g., mywebsite.com)
  5. Copy the generated Domain ID (you’ll need this for the tracking script)

Installing the Tracking Script

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

<script async
  src="https://example-app.klutch.sh/tracker.js"
  data-ackee-server="https://example-app.klutch.sh"
  data-ackee-domain-id="YOUR_DOMAIN_ID">
</script>

Replace:

  • example-app.klutch.sh with your actual Klutch.sh app URL
  • YOUR_DOMAIN_ID with the domain ID from your Ackee dashboard

Tracking Options

Ackee’s tracking script supports several attributes for customization:

<script async
  src="https://example-app.klutch.sh/tracker.js"
  data-ackee-server="https://example-app.klutch.sh"
  data-ackee-domain-id="YOUR_DOMAIN_ID"
  data-ackee-opts='{"ignoreLocalhost": true, "detailed": false}'>
</script>

Available options:

  • ignoreLocalhost: Don’t track visits from localhost (default: true)
  • detailed: Record detailed information like screen size and browser (default: false)
  • ignoreOwnVisits: Ignore visits when logged into Ackee (default: false)

Environment Variables Reference

Complete list of Ackee environment variables you can configure in Klutch.sh:

VariableDescriptionRequiredDefault
ACKEE_MONGODBMongoDB connection stringYesmongodb://localhost:27017/ackee
ACKEE_USERNAMEAdmin username for Ackee dashboardYesNone
ACKEE_PASSWORDAdmin password for Ackee dashboardYesNone
ACKEE_PORTPort for Ackee serverNo3000
ACKEE_ALLOW_ORIGINCORS origin for tracking scriptNo*
ACKEE_AUTO_SSLEnable automatic SSL (not needed on Klutch.sh)Nofalse
ACKEE_TRACKERCustom tracker script filenameNotracker.js
NODE_ENVNode environmentNoproduction

Using an External MongoDB Database

For production deployments with higher traffic, you may want to use an external MongoDB instance instead of the built-in one. Here’s how:

Option 1: Deploy MongoDB Separately on Klutch.sh

  1. Follow the MongoDB deployment guide to create a separate MongoDB instance
  2. Use a simplified Dockerfile for Ackee only:
FROM node:18-alpine


WORKDIR /app


# Install Ackee
RUN npm install -g ackee@3.4.0


# Expose Ackee port
EXPOSE 3000


ENV NODE_ENV=production


# Start Ackee
CMD ["ackee", "server"]
  1. Set the ACKEE_MONGODB environment variable to your MongoDB connection string: 
    ACKEE_MONGODB=mongodb://username:password@mongodb-app.klutch.sh:8000/ackee

Option 2: Use MongoDB Atlas

  1. Create a free MongoDB Atlas cluster at mongodb.com
  2. Get your connection string from Atlas
  3. Set the ACKEE_MONGODB environment variable to your Atlas connection string: 
    ACKEE_MONGODB=mongodb+srv://username:password@cluster.mongodb.net/ackee

Production Best Practices

Security Recommendations

  • Strong Passwords: Use a password manager to generate strong, random passwords for ACKEE_PASSWORD
  • Environment Variables: Store all sensitive credentials as environment variables in Klutch.sh, never in your Dockerfile
  • HTTPS Only: Klutch.sh provides HTTPS by default; ensure you access Ackee only via HTTPS
  • Regular Backups: Implement a backup strategy for your MongoDB data using volume snapshots or database exports
  • Update Regularly: Keep Ackee updated to the latest version for security patches and new features
  • Restrict CORS: In production, set ACKEE_ALLOW_ORIGIN to your specific domain instead of *

Performance Optimization

  • Database Indexing: MongoDB automatically creates indexes, but monitor query performance
  • Data Retention: Configure Ackee to automatically clean up old data to manage database size
  • Caching: Ackee includes built-in caching; ensure it’s enabled for optimal performance
  • Resource Allocation: Monitor your application and increase compute resources if response times slow down
  • CDN Integration: Consider using a CDN for the tracking script to improve loading times globally

Monitoring and Maintenance

Monitor your Ackee deployment for:

  • Response Times: Ensure the dashboard loads quickly and tracking script responds promptly
  • Database Size: Watch for unexpected growth in MongoDB storage
  • Memory Usage: Ackee should use minimal memory, but monitor for memory leaks
  • Tracking Errors: Check logs for any tracking script errors
  • Uptime: Use external monitoring services to alert you if Ackee goes down

Data Management

  • Regular Exports: Periodically export your analytics data for long-term archival
  • Database Backups: Create regular backups of your MongoDB volume
  • Data Cleanup: Configure retention policies to remove old data and control database growth
  • Analytics Review: Regularly review your analytics to ensure tracking is working correctly

Accessing Analytics via API

Ackee provides a GraphQL API for programmatic access to your analytics data. This is useful for custom dashboards, reporting, and integrations.

Authentication

First, obtain an authentication token:

Terminal window
curl -X POST https://example-app.klutch.sh/api \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation {createToken(input:{username:\"admin\",password:\"your-password\"}) {payload {id}}}"}'

Example Query

Once you have a token, you can query analytics data:

Terminal window
curl -X POST https://example-app.klutch.sh/api \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"query":"query {domains {id title}}"}'

GraphQL Playground

Access the GraphQL playground at:

https://example-app.klutch.sh/api

Troubleshooting

Cannot Access Ackee Dashboard

  • Verify your app is running in the Klutch.sh dashboard
  • Check that the internal port is set to 3000
  • Ensure HTTP traffic type is selected
  • Review application logs for startup errors

Tracking Script Not Working

  • Verify the domain is added in Ackee settings
  • Check that the Domain ID is correct in your tracking script
  • Ensure ACKEE_ALLOW_ORIGIN allows your website’s domain
  • Test the tracking script URL directly in your browser

MongoDB Connection Errors

  • Verify the persistent volume is correctly attached at /data/db
  • Check MongoDB is starting correctly in the logs
  • Ensure sufficient disk space is allocated to the volume
  • Verify the ACKEE_MONGODB connection string format

Data Not Persisting

  • Confirm the persistent volume is attached at /data/db
  • Check the volume has sufficient space
  • Verify MongoDB is writing to the correct directory

Performance Issues

  • Monitor CPU and memory usage in Klutch.sh dashboard
  • Consider increasing compute resources
  • Check MongoDB queries aren’t blocking the application
  • Review analytics data size and implement retention policies

Upgrading Ackee

To upgrade Ackee to a new version:

  1. Update the version in your Dockerfile:

    RUN npm install -g ackee@3.5.0

  2. Commit and push the changes to GitHub:

    Terminal window
    git add Dockerfile
    git commit -m "Upgrade Ackee to version 3.5.0"
    git push

  3. Klutch.sh will automatically rebuild and redeploy your application

  4. Your data will be preserved because it’s stored in the persistent volume

Additional Resources

Conclusion

Deploying Ackee to Klutch.sh with Docker provides a privacy-focused, self-hosted analytics solution with persistent storage and easy scalability. By following this guide, you’ve set up a production-ready Ackee instance with proper data persistence, security configurations, and tracking capabilities. Your analytics platform is now ready to provide valuable insights into your website’s traffic while respecting user privacy and maintaining full control over your data.