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	22.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 entro314labs/entrolytics:latest

docker pull ghcr.io/entro314-labs/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

If you have PostgreSQL installed locally:

# Create database
createdb entrolytics

# Connection string
postgresql://user:password@localhost:5432/entrolytics

Run PostgreSQL in Docker:

docker run -d \
  --name entrolytics-db \
  -e POSTGRES_DB=entrolytics \
  -e POSTGRES_USER=entrolytics \
  -e POSTGRES_PASSWORD=your_password \
  -p 5432:5432 \
  -v postgres_data:/var/lib/postgresql/data \
  postgres:16-alpine

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/entro314-labs/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/entro314-labs/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

# Update package list
sudo apt update

# Install Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# Install PostgreSQL
sudo apt install -y postgresql postgresql-contrib
sudo systemctl start postgresql

# Install pnpm
npm install -g pnpm

Using Windows Subsystem for Linux (WSL) is recommended

Install Node.js 22 from official website
Install PostgreSQL
Install pnpm:

npm install -g pnpm

Clone Repository

# Clone the repository
git clone https://github.com/entro314-labs/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

/etc/caddy/Caddyfile

analytics.yourdomain.com {
    reverse_proxy localhost:3000
}

Caddy automatically handles HTTPS certificates via Let's Encrypt.

sudo systemctl restart caddy

/etc/apache2/sites-available/entrolytics.conf

<VirtualHost *:80>
    ServerName analytics.yourdomain.com
    Redirect permanent / https://analytics.yourdomain.com/
</VirtualHost>

<VirtualHost *:443>
    ServerName analytics.yourdomain.com

    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/live/analytics.yourdomain.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/analytics.yourdomain.com/privkey.pem

    ProxyPreserveHost On
    ProxyPass / http://localhost:3000/
    ProxyPassReverse / http://localhost:3000/
</VirtualHost>

Enable and restart:

sudo a2enmod ssl proxy proxy_http
sudo a2ensite entrolytics
sudo systemctl restart apache2

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

Add your domain to Cloudflare
Point analytics subdomain to your server IP
Enable Proxy status (orange cloud)
SSL/TLS mode: Full (strict)

Cloudflare automatically provides SSL.

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

Create systemd service:

/etc/systemd/system/entrolytics.service

[Unit]
Description=Entrolytics Analytics
After=network.target postgresql.service

[Service]
Type=simple
User=entrolytics
WorkingDirectory=/opt/entrolytics
Environment=NODE_ENV=production
EnvironmentFile=/opt/entrolytics/.env
ExecStart=/usr/bin/pnpm start
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable entrolytics
sudo systemctl start entrolytics
sudo systemctl status entrolytics

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/entro314-labs/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 ...

# Navigate to installation directory
cd /opt/entrolytics

# Pull latest changes
git pull origin main

# Install dependencies
pnpm install

# Run migrations
pnpm db:migrate

# Rebuild
pnpm build

# Restart
pm2 restart entrolytics
# or
sudo systemctl restart 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
Set Up Backups - Automate database backups
Configure Monitoring - Set up uptime monitoring

📖 Getting Started Guide

Installation

Automated Backups

Restore from Backup

Database connection failed

Migration errors

Application won't start

Clerk authentication issues

Table of Contents