Deploying Aptabase

Aptabase is an open-source, privacy-first analytics platform designed specifically for mobile, desktop, and web applications. Unlike traditional analytics tools that rely on invasive tracking and unique identifiers, Aptabase focuses on session-based metrics while maintaining full compliance with GDPR, CCPA, and PECR regulations. With extensive SDK support for Swift, Kotlin, React Native, Flutter, Electron, Tauri, and many more frameworks, Aptabase provides developers with actionable insights without compromising user privacy.

This guide walks you through deploying a self-hosted Aptabase instance on Klutch.sh using Docker, complete with PostgreSQL for metadata storage and ClickHouse for high-performance event analytics.

Why Choose Aptabase?

Privacy-First Analytics

Collect meaningful metrics without invasive tracking or unique identifiers. Fully GDPR, CCPA, and PECR compliant by design.

Extensive SDK Support

Native SDKs for Swift, Kotlin, React Native, Flutter, Electron, Tauri, .NET MAUI, Unity, Unreal Engine, and more.

Simple Dashboard

Built-in, user-friendly dashboard provides essential metrics at a glance without overwhelming complexity.

100% Open Source

Complete transparency with AGPLv3 licensed server code and MIT licensed SDKs.

Prerequisites

Before deploying Aptabase on Klutch.sh, ensure you have the following:

• A GitHub account for repository hosting
• A Klutch.sh account for deployment
• A PostgreSQL database (for metadata storage)
• A ClickHouse database (for event analytics)

Database Options

Aptabase requires both PostgreSQL and ClickHouse databases. You can deploy these on Klutch.sh as separate projects or use managed database services like Neon for PostgreSQL and ClickHouse Cloud for analytics storage.

Architecture Overview

Aptabase uses a dual-database architecture:

• PostgreSQL: Stores user accounts, app configurations, and metadata
• ClickHouse: Handles high-performance event ingestion and analytics queries

┌─────────────────┐     ┌──────────────────┐     ┌────────────────┐
│   Your Apps     │────▶│    Aptabase      │────▶│   PostgreSQL   │
│   (SDKs)        │     │    (Port 8080)   │     │   (Metadata)   │
└─────────────────┘     └──────────────────┘     └────────────────┘
                               │
                               │
                               ▼
                        ┌────────────────┐
                        │   ClickHouse   │
                        │   (Events)     │
                        └────────────────┘

Creating the Dockerfile

Create a Dockerfile in your project root that builds upon the official Aptabase image:

Dockerfile

FROM ghcr.io/aptabase/aptabase:main

# Set the working directory
WORKDIR /app

# Expose the application port
EXPOSE 8080

# The base image already includes the ENTRYPOINT
# Environment variables will be configured through Klutch.sh

Official Image

The ghcr.io/aptabase/aptabase:main image is the official Aptabase container maintained by the Aptabase team. It includes both the .NET backend and the React frontend pre-built and optimized.

Environment Variables

Aptabase requires several environment variables for proper configuration. Configure these in the Klutch.sh dashboard:

Required Variables

Variable	Description	Example
BASE_URL	The public URL of your Aptabase instance	https://analytics.example-app.klutch.sh
AUTH_SECRET	A strong random secret for signing auth tokens (32+ characters)	c4rI4x8kz5DgKJ1is5Eiu9bNncSQ6ROD
DATABASE_URL	PostgreSQL connection string in .NET format	Server=host;Port=5432;User Id=user;Password=pass;Database=aptabase
CLICKHOUSE_URL	ClickHouse connection string	Host=host;Port=8123;Username=user;Password=pass

Optional Variables (SMTP for Email)

Variable	Description	Example
SMTP_HOST	SMTP server hostname	smtp.sendgrid.net
SMTP_PORT	SMTP server port	587
SMTP_USERNAME	SMTP authentication username	apikey
SMTP_PASSWORD	SMTP authentication password	your-smtp-password
SMTP_FROM_ADDRESS	Email sender address	noreply@yourdomain.com

OAuth Configuration (Optional)

Variable	Description
OAUTH_GITHUB_CLIENT_ID	GitHub OAuth client ID
OAUTH_GITHUB_CLIENT_SECRET	GitHub OAuth client secret
OAUTH_GOOGLE_CLIENT_ID	Google OAuth client ID
OAUTH_GOOGLE_CLIENT_SECRET	Google OAuth client secret

Generate a Strong Secret

Use a cryptographically secure random string generator for your AUTH_SECRET. You can generate one at randomkeygen.com or by running openssl rand -base64 32 in your terminal.

Setting Up Databases

Option 1: Deploy PostgreSQL on Klutch.sh

First, deploy a PostgreSQL database as a separate Klutch.sh project:

Dockerfile.postgres

FROM postgres:15-alpine

ENV POSTGRES_USER=aptabase
ENV POSTGRES_PASSWORD=your-strong-password
ENV POSTGRES_DB=aptabase

EXPOSE 5432

Option 2: Deploy ClickHouse on Klutch.sh

Deploy ClickHouse as another separate project:

Dockerfile.clickhouse

FROM clickhouse/clickhouse-server:23.8.4.69-alpine

ENV CLICKHOUSE_USER=aptabase
ENV CLICKHOUSE_PASSWORD=your-strong-password

EXPOSE 8123

# Increase file descriptor limits for ClickHouse performance

Using TCP Traffic

When deploying PostgreSQL and ClickHouse on Klutch.sh, select TCP traffic in the deployment settings. You’ll be able to connect to these databases externally on port 8000, with traffic routed to the internal container port.

Option 3: Use Managed Database Services

For production deployments, consider using managed services:

PostgreSQL:

• Neon - Serverless PostgreSQL
• Supabase - PostgreSQL with extras
• ElephantSQL - Managed PostgreSQL

ClickHouse:

• ClickHouse Cloud - Official managed service

Project Structure

Your Aptabase project repository should have the following structure:

aptabase-deploy/
├── Dockerfile
└── README.md

Deploying to Klutch.sh

1. Push your repository to GitHub

   Create a new repository on GitHub and push your Dockerfile:

   git init
   git add .
   git commit -m "Initial Aptabase deployment configuration"
   git branch -M main
   git remote add origin https://github.com/yourusername/aptabase-deploy.git
   git push -u origin main

2. Connect to Klutch.sh

   Navigate to klutch.sh/app and sign in with your GitHub account. Click New Project to begin the deployment process.

3. Select your repository

   Choose the GitHub repository containing your Aptabase Dockerfile. Klutch.sh will automatically detect the Dockerfile in your project root.

4. Configure environment variables

   Add the required environment variables in the Klutch.sh dashboard:

   • BASE_URL - Your Aptabase instance URL (e.g., https://analytics.example-app.klutch.sh)
   • AUTH_SECRET - A strong 32+ character random string
   • DATABASE_URL - PostgreSQL connection string
   • CLICKHOUSE_URL - ClickHouse connection string

5. Set the internal port

   Configure the internal port to 8080 where Aptabase listens for HTTP traffic.

6. Add persistent storage (optional)

   If you want to persist any local data, add a persistent volume:

   Mount Path	Size
   /app/data	1 GB

7. Deploy your application

   Click Deploy to start the deployment process. Klutch.sh will build the Docker image and deploy your Aptabase instance.

First-Time Setup

After deployment, you’ll need to create your first account:

1. Access your Aptabase instance

   Navigate to your deployed Aptabase URL (e.g., https://analytics.example-app.klutch.sh).

2. Register a new account

   Click the registration link and enter your email address. Since SMTP may not be configured initially, you’ll need to find the activation link in your container logs.

3. Find the activation link

   In your Klutch.sh dashboard, check the deployment logs to find the email activation link. Copy the link and paste it into your browser to activate your account.

4. Create your first app

   Once logged in, create a new app in Aptabase to get your App Key. You’ll use this key to initialize the SDK in your applications.

Integrating SDKs

React Native

Install the Aptabase SDK:

npm install @aptabase/react-native

Initialize in your app:

App.tsx

import Aptabase from '@aptabase/react-native';

// Initialize with your App Key and custom host
Aptabase.init('A-YOUR-APP-KEY', {
  host: 'https://analytics.example-app.klutch.sh'
});

// Track an event
Aptabase.trackEvent('app_started');

// Track with properties
Aptabase.trackEvent('button_clicked', {
  buttonName: 'submit',
  screenName: 'checkout'
});

Flutter

Add to your pubspec.yaml:

pubspec.yaml

dependencies:
  aptabase_flutter: ^0.0.8

Initialize in your app:

main.dart

import 'package:aptabase_flutter/aptabase_flutter.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Aptabase.init(
    'A-YOUR-APP-KEY',
    InitOptions(host: 'https://analytics.example-app.klutch.sh'),
  );

  runApp(MyApp());
}

// Track events
Aptabase.instance.trackEvent('app_started');
Aptabase.instance.trackEvent('purchase_completed', {
  'amount': 29.99,
  'currency': 'USD',
});

Electron

Install the SDK:

npm install @aptabase/electron

Initialize in your main process:

main.ts

import { initialize, trackEvent } from '@aptabase/electron';

// Initialize with your App Key
initialize('A-YOUR-APP-KEY', {
  host: 'https://analytics.example-app.klutch.sh'
});

// Track events
trackEvent('app_started');
trackEvent('file_opened', { fileType: 'pdf' });

Tauri

Add to your Cargo.toml:

Cargo.toml

[dependencies]
tauri-plugin-aptabase = "2"

Configure in your Tauri app:

src-tauri/src/main.rs

use tauri_plugin_aptabase::Builder;

fn main() {
    tauri::Builder::default()
        .plugin(
            Builder::new("A-YOUR-APP-KEY")
                .with_host("https://analytics.example-app.klutch.sh")
                .build(),
        )
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

Web Applications

Install the SDK:

npm install @aptabase/web

Initialize in your web app:

analytics.ts

import { init, trackEvent } from '@aptabase/web';

// Initialize with your App Key
init('A-YOUR-APP-KEY', {
  host: 'https://analytics.example-app.klutch.sh'
});

// Track events
trackEvent('page_view', { page: '/home' });
trackEvent('signup_completed');

Custom Domain Setup

To use a custom domain with your Aptabase deployment:

1. Add your domain in Klutch.sh

   Navigate to your project settings in the Klutch.sh dashboard and add your custom domain (e.g., analytics.yourdomain.com).

2. Configure DNS records

   Add a CNAME record pointing to your Klutch.sh deployment:

   Type	Name	Value
   CNAME	analytics	example-app.klutch.sh

3. Update BASE_URL

   Update the BASE_URL environment variable in Klutch.sh to match your custom domain:

   BASE_URL=https://analytics.yourdomain.com

4. Wait for SSL provisioning

   Klutch.sh automatically provisions SSL certificates for custom domains. This may take a few minutes.

Local Development with Docker Compose

For local development and testing, you can use Docker Compose:

docker-compose.yml

services:
  postgres:
    image: postgres:15-alpine
    restart: always
    volumes:
      - postgres-data:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: aptabase
      POSTGRES_PASSWORD: local_dev_password
      POSTGRES_DB: aptabase
    ports:
      - "5432:5432"

  clickhouse:
    image: clickhouse/clickhouse-server:23.8.4.69-alpine
    restart: always
    volumes:
      - clickhouse-data:/var/lib/clickhouse
    environment:
      CLICKHOUSE_USER: aptabase
      CLICKHOUSE_PASSWORD: local_dev_password
    ulimits:
      nofile:
        soft: 262144
        hard: 262144
    ports:
      - "8123:8123"

  aptabase:
    image: ghcr.io/aptabase/aptabase:main
    restart: always
    depends_on:
      - postgres
      - clickhouse
    ports:
      - "8000:8080"
    environment:
      BASE_URL: http://localhost:8000
      AUTH_SECRET: local_development_secret_key_32chars
      DATABASE_URL: Server=postgres;Port=5432;User Id=aptabase;Password=local_dev_password;Database=aptabase
      CLICKHOUSE_URL: Host=clickhouse;Port=8123;Username=aptabase;Password=local_dev_password

volumes:
  postgres-data:
  clickhouse-data:

Start the local development environment:

docker-compose up -d

Access Aptabase at http://localhost:8000.

Troubleshooting

Account Activation Without SMTP

If you haven’t configured SMTP, account activation emails won’t be sent. Check your container logs in the Klutch.sh dashboard to find the activation link.

Database Connection Issues

Verify your connection strings are in the correct .NET format:

PostgreSQL:

Server=hostname;Port=5432;User Id=username;Password=password;Database=aptabase

ClickHouse:

Host=hostname;Port=8123;Username=username;Password=password

Events Not Recording

Ensure your SDK is configured with the correct host parameter pointing to your self-hosted instance, not the default Aptabase cloud.

ClickHouse Performance

ClickHouse requires high file descriptor limits. If you’re deploying ClickHouse on Klutch.sh, ensure your container has adequate resources allocated.

Resources

• Aptabase GitHub Repository
• Self-Hosting Documentation
• Official Aptabase Documentation
• Aptabase Discord Community

Next Steps

After deploying Aptabase, consider:

• Setting up SMTP for proper email notifications
• Configuring OAuth providers for easier sign-in
• Creating multiple apps for different projects
• Setting up automated backups for your PostgreSQL and ClickHouse databases
• Exploring the Aptabase dashboard to understand your app analytics