Codakey
Play
← Back to swetrix

How to Deploy & Use swetrix

Swetrix Deployment & Usage Guide

1. Prerequisites

Software Requirements

  • Node.js (v18 or higher)
  • npm or yarn package manager
  • Docker and Docker Compose (recommended for self-hosting)
  • MySQL (v8.0+) or ClickHouse database
  • Redis (v7.0+)

Cloud Services (Optional)

  • Google OAuth credentials (for Google authentication)
  • GitHub OAuth credentials (for GitHub authentication)
  • Telegram Bot Token (for notifications)
  • OpenRouter API Key (for AI features in Cloud edition)

System Requirements

  • Minimum 2GB RAM (4GB+ recommended for production)
  • 10GB+ disk space for data storage
  • Linux/Unix environment (Windows requires WSL2 for development)

2. Installation

Clone the Repository

git clone https://github.com/Swetrix/swetrix.git
cd swetrix

Install Dependencies

# Install root dependencies
npm install

# Install backend dependencies
cd backend && npm install

# Install frontend dependencies
cd ../frontend && npm install

Quick Start with Docker (Recommended)

# Clone and navigate to docker directory
git clone https://github.com/Swetrix/swetrix.git
cd swetrix/docker

# Copy environment file
cp .env.example .env

# Edit .env file with your configuration
nano .env

# Start all services
docker-compose up -d

The Docker setup includes:

  • Swetrix API (backend)
  • Swetrix Dashboard (frontend)
  • MySQL database
  • Redis cache
  • ClickHouse analytics database
  • Nginx reverse proxy

3. Configuration

Environment Variables

Create a .env file in your backend directory with these essential variables:

# Database
DATABASE_URL=mysql://user:password@localhost:3306/swetrix
CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=password
REDIS_URL=redis://localhost:6379

# JWT Tokens
JWT_ACCESS_TOKEN_SECRET=your-access-token-secret-here
JWT_REFRESH_TOKEN_SECRET=your-refresh-token-secret-here
JWT_ACCESS_TOKEN_LIFETIME=15m
JWT_REFRESH_TOKEN_LIFETIME=7d

# Application
NODE_ENV=production
PORT=3001
FRONTEND_URL=http://localhost:3000
API_URL=http://localhost:3001
ORIGIN=http://localhost:3000

# Authentication
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

# Email (SMTP)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM=noreply@swetrix.com

# Security
CAPTCHA_SECRET_KEY=your-captcha-secret-key
SELFHOSTED_GEOIP_DB_PATH=/path/to/GeoLite2-City.mmdb

# AI Features (Cloud Edition Only)
OPENROUTER_API_KEY=your-openrouter-api-key

Database Setup

# Create MySQL database
mysql -u root -p -e "CREATE DATABASE swetrix CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# Create ClickHouse database
clickhouse-client --query "CREATE DATABASE IF NOT EXISTS swetrix;"

GeoIP Database

Download and place the MaxMind GeoLite2 City database:

wget https://geolite.maxmind.com/download/geoip/database/GeoLite2-City.tar.gz
tar -xzf GeoLite2-City.tar.gz
mv GeoLite2-City_*/GeoLite2-City.mmdb /path/to/GeoLite2-City.mmdb

4. Build & Run

Development Mode

# Start backend in development
cd backend
npm run start:dev

# Start frontend in development (separate terminal)
cd frontend
npm run dev

Production Build

# Build backend
cd backend
npm run build

# Build frontend
cd ../frontend
npm run build

# Start production server
cd ../backend
npm run start:prod

Using Docker Build

# Build Docker images
docker build -t swetrix-backend -f backend/Dockerfile .
docker build -t swetrix-frontend -f frontend/Dockerfile .

# Or use docker-compose
docker-compose build
docker-compose up -d

5. Deployment

Platform Recommendations

Option 1: Docker on VPS (Recommended)

  • Platform: DigitalOcean, Linode, Hetzner, AWS EC2
  • Requirements: Ubuntu 22.04+, Docker, Docker Compose
  • Setup:
# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Install Docker Compose
sudo apt-get install docker-compose-plugin

# Deploy Swetrix
git clone https://github.com/Swetrix/swetrix.git
cd swetrix/docker
docker-compose up -d

Option 2: Kubernetes

# Example deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: swetrix-backend
spec:
  replicas: 2
  selector:
    matchLabels:
      app: swetrix-backend
  template:
    metadata:
      labels:
        app: swetrix-backend
    spec:
      containers:
      - name: backend
        image: swetrix/swetrix-backend:latest
        envFrom:
        - configMapRef:
            name: swetrix-config
        ports:
        - containerPort: 3001

Option 3: Traditional Server

# Install Node.js and dependencies
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install MySQL and Redis
sudo apt-get install mysql-server redis-server

# Clone and setup
git clone https://github.com/Swetrix/swetrix.git
cd swetrix

# Follow build instructions from section 4

Reverse Proxy Setup (Nginx)

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_certificate /etc/letsencrypt/live/analytics.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/analytics.yourdomain.com/privkey.pem;
    
    # Frontend
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        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;
    }
    
    # API
    location /api {
        proxy_pass http://localhost:3001;
        proxy_set_header Host $host;
        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;
    }
    
    # WebSocket support
    location /socket.io {
        proxy_pass http://localhost:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Database Backups

# MySQL backup script
mysqldump -u username -p swetrix > swetrix_backup_$(date +%Y%m%d).sql

# ClickHouse backup (using clickhouse-backup)
clickhouse-backup create swetrix_backup_$(date +%Y%m%d)

# Automated backup with cron
0 2 * * * /path/to/backup-script.sh

6. Troubleshooting

Common Issues

1. Database Connection Errors

# Check MySQL is running
sudo systemctl status mysql

# Check ClickHouse connection
curl http://localhost:8123/ping

# Verify credentials in .env file
mysql -u username -p -e "USE swetrix; SHOW TABLES;"

2. Redis Connection Issues

# Test Redis connection
redis-cli ping

# Check Redis logs
sudo journalctl -u redis-server -f

3. Build Failures

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

# Check Node.js version
node --version  # Should be >= 18

# Check TypeScript compilation
npx tsc --noEmit

4. ClickHouse Performance Issues

# Monitor ClickHouse
clickhouse-client --query "SELECT * FROM system.processes"

# Check disk space
df -h

# Optimize tables periodically
clickhouse-client --query "OPTIMIZE TABLE swetrix.events FINAL"

5. GeoIP Database Not Found

# Download GeoIP database manually
mkdir -p /usr/share/GeoIP
cd /usr/share/GeoIP
wget https://geolite.maxmind.com/download/geoip/database/GeoLite2-City.tar.gz
tar -xzf GeoLite2-City.tar.gz
mv GeoLite2-City_*/GeoLite2-City.mmdb .

6. Authentication Issues

  • Verify OAuth credentials are correctly set in environment variables
  • Check callback URLs match your deployment URL
  • Ensure JWT secrets are strong and unique
  • Check that FRONTEND_URL and API_URL are correctly configured

7. Rate Limiting Errors

Adjust rate limits in your configuration:

# Increase rate limits if needed
RATE_LIMIT_WINDOW=900000  # 15 minutes in milliseconds
RATE_LIMIT_MAX_REQUESTS=1000

8. Memory Issues

# Monitor memory usage
free -h

# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=4096"

# Optimize ClickHouse memory settings in config.xml
# <max_memory_usage>10000000000</max_memory_usage>

Logs and Monitoring

# View Docker logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f backend

# Check application logs
tail -f backend/logs/app.log

# Monitor system resources
htop

Getting Help

← Project overviewView alternatives to swetrix →