Self-Hosted Installation

Deploy Entrolytics on your own infrastructure for complete data control and privacy. This guide covers Docker, Docker Compose, and manual installation methods.

Why Self-Host?

🔐 Complete data ownership - All analytics data stays on your servers
🌐 Custom domain - Use your own domain (e.g., analytics.yourdomain.com)
⚙️ Full control - Customize, extend, and integrate as needed
🔒 Enhanced privacy - No data ever leaves your infrastructure
💰 Cost-effective - No per-seat or per-view pricing

System Requirements

Minimum Specifications

Component	Requirement
CPU	1 core (2+ recommended)
RAM	1GB (2GB+ recommended)
Storage	10GB (grows with data)
Node.js	24.x or later
PostgreSQL	14 or later (15+ recommended)
OS	Linux, macOS, or Windows

Recommended for Production

Component	Specification
CPU	2-4 cores
RAM	4GB
Storage	50GB SSD
PostgreSQL	15+ with connection pooling
Reverse Proxy	Nginx or Caddy

Quick Start with Docker

Pull the Image

docker pull entrolytics/entrolytics:latest

Set Up Database

You need a PostgreSQL database. Choose your method:

Recommended for production

Go to neon.tech
Create a free account
Create a new project
Copy the connection string

Example:

postgresql://user:password@ep-example-123.us-east-2.aws.neon.tech/entrolytics?sslmode=require

Run Entrolytics

docker run -d \
  --name entrolytics \
  -p 3000:3000 \
  -e DATABASE_URL="postgresql://user:pass@host:5432/entrolytics" \
  -e APP_SECRET="your-secret-key-min-32-chars" \
  ghcr.io/entrolytics/entrolytics:latest

Replace:

DATABASE_URL with your PostgreSQL connection string
APP_SECRET with a random 32+ character string

Access Entrolytics

Open your browser to http://localhost:3000 and create your admin account.

Docker Compose (Recommended)

For a complete, production-ready setup:

Create docker-compose.yml

Create a new file docker-compose.yml:

docker-compose.yml

version: '3.8'

services:
  entrolytics:
    image: ghcr.io/entrolytics/entrolytics:latest
    container_name: entrolytics
    ports:
      - '3000:3000'
    environment:
      DATABASE_URL: postgresql://entrolytics:${DB_PASSWORD}@db:5432/entrolytics
      APP_SECRET: ${APP_SECRET}
      DISABLE_TELEMETRY: '1'
      # Clerk authentication
      NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: ${CLERK_PUBLISHABLE_KEY}
      CLERK_SECRET_KEY: ${CLERK_SECRET_KEY}
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
    networks:
      - entrolytics-network

  db:
    image: postgres:16-alpine
    container_name: entrolytics-db
    environment:
      POSTGRES_DB: entrolytics
      POSTGRES_USER: entrolytics
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - '5432:5432'
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U entrolytics']
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - entrolytics-network

volumes:
  postgres_data:

networks:
  entrolytics-network:
    driver: bridge

Create .env File

.env

# Database
DB_PASSWORD=your_secure_database_password_here

# Application
APP_SECRET=your_32_char_minimum_secret_key_here

# Clerk Authentication
CLERK_PUBLISHABLE_KEY=pk_test_your_key
CLERK_SECRET_KEY=sk_test_your_key

# Optional: Disable telemetry
DISABLE_TELEMETRY=1

Start Services

# Start in background
docker-compose up -d

# View logs
docker-compose logs -f entrolytics

# Check status
docker-compose ps

Initialize Database

On first run, the database is automatically initialized with the schema.

Access Application

Navigate to http://localhost:3000 and create your first account.

Manual Installation

For development or custom deployments:

Install Prerequisites

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL <https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh>)"

# Install Node.js 22
brew install node@22

# Install PostgreSQL
brew install postgresql@16
brew services start postgresql@16

# Install pnpm
npm install -g pnpm

Clone Repository

# Clone the repository
git clone https://github.com/entrolytics/entrolytics.git
cd entrolytics

Install Dependencies

# Install all dependencies
pnpm install

Configure Environment

# Copy example env file
cp .env.example .env

# Edit .env with your configuration
nano .env

Required environment variables:

.env

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/entrolytics

# Application
APP_SECRET=your-32-character-minimum-secret

# Clerk Auth
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_your_key
CLERK_SECRET_KEY=sk_test_your_key

# Optional
DISABLE_TELEMETRY=1
NODE_ENV=production

Create Database

# Create database
createdb entrolytics

# Run migrations
pnpm db:migrate

Build Application

# Build for production
pnpm build

Start Server

# Start production server
pnpm start

# Or for development
pnpm dev

The application will be available at http://localhost:3000.

Environment Variables

Required Variables

Variable	Description	Example
`DATABASE_URL`	PostgreSQL connection string	`postgresql://user:pass@localhost:5432/entrolytics`
`APP_SECRET`	Secret key for encryption (32+ chars)	`your-long-random-secret-key`
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	Clerk publishable key	`pk_test_...`
`CLERK_SECRET_KEY`	Clerk secret key	`sk_test_...`

Optional Variables

Variable	Description	Default
`PORT`	Server port	`3000`
`DISABLE_TELEMETRY`	Disable anonymous usage stats	`false`
`LOG_LEVEL`	Logging level (debug, info, warn, error)	`info`
`COLLECT_API_ENDPOINT`	Custom collect endpoint	`/api/send`
`TRACKER_SCRIPT_NAME`	Custom script filename	`script.js`

Clerk Authentication

Entrolytics uses Clerk for authentication:

Create Clerk Account

Go to clerk.com
Sign up for a free account

Create Application

Create a new application in Clerk dashboard
Choose Email and OAuth providers (Google, GitHub)

Get API Keys

Copy your Publishable Key and Secret Key from the Clerk dashboard.

Add to Environment

Add the keys to your .env file:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

Production Deployment

Reverse Proxy Setup

/etc/nginx/sites-available/entrolytics

server {
    listen 80;
    server_name analytics.yourdomain.com;

    # Redirect to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name analytics.yourdomain.com;

    # SSL Configuration
    ssl_certificate /etc/letsencrypt/live/analytics.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/analytics.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable and restart:

sudo ln -s /etc/nginx/sites-available/entrolytics /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

SSL Certificate

Using Certbot:

# Install Certbot
sudo apt install certbot python3-certbot-nginx

# Get certificate
sudo certbot --nginx -d analytics.yourdomain.com

# Auto-renewal (already configured by default)
sudo certbot renew --dry-run

Process Management

Recommended for Node.js applications

# Install PM2
npm install -g pm2

# Start Entrolytics
pm2 start pnpm --name entrolytics -- start

# Auto-restart on reboot
pm2 startup
pm2 save

# View logs
pm2 logs entrolytics

# Monitor
pm2 monit

Database Management

Migrations

# Run pending migrations
pnpm db:migrate

# Rollback last migration
pnpm db:migrate:rollback

# Reset database (⚠️ deletes all data)
pnpm db:reset

Backups

Troubleshooting

Updating Entrolytics

# Pull latest image
docker pull ghcr.io/entrolytics/entrolytics:latest

# Restart container
docker-compose down
docker-compose up -d

# Or with plain Docker
docker stop entrolytics
docker rm entrolytics
docker run -d --name entrolytics ...

Next Steps

After installation:

Create Admin Account - Sign up on your instance
Add First Website - Configure your first site to track
Configure Tracking - Add tracking script to your websites
Install SDKs - Add Entrolytics SDKs to your applications
Set Up Backups - Automate database backups
Configure Monitoring - Set up uptime monitoring

Installing SDKs and Packages

Entrolytics provides a comprehensive ecosystem of SDKs and packages organized in the packages/ folder:

Frontend Framework SDKs

npm install @entrolytics/react-sdk
# or
pnpm add @entrolytics/react-sdk

Backend Clients

npm install @entrolytics/node-client
# or
pnpm add @entrolytics/node-client

Framework Middleware

npm install @entrolytics/express-middleware
# or
pnpm add @entrolytics/express-middleware

Platform Integrations

Install via Vercel marketplace or:

npm install @entrolytics/vercel-plugin

Developer Tools

# CLI Tool
npm install -g @entrolytics/cli-tools

# or
pnpm add -g @entrolytics/cli-tools

Package Structure Reference

packages/
├── client/           # HTTP clients for different languages

├── middleware/       # Framework middleware and integrations

├── mobile/          # Mobile SDKs (React Native, Android, iOS)

├── plugin/          # Platform integrations (Vercel, Netlify, etc.)

├── sdk/             # Frontend framework SDKs

├── shared/          # Shared utilities and types

├── tools/           # Developer tools (CLI, etc.)

└── utilities/       # Common utilities

📖 Getting Started Guide 📦 SDK Documentation

Installation

Automated Backups

Restore from Backup

Database connection failed

Migration errors

Application won't start

Clerk authentication issues

On this page