Deployment Guide

Deploy Vemetric using Docker Compose or manual setup

Deployment Guide

This guide covers deploying Vemetric using Docker Compose for local development and production environments.

Prerequisites

1. Install Dependencies

   Ensure you have the following installed:

   • Bun v1.2.23 or higher
   • Docker v20.10+ and Docker Compose v2.0+
   • Git for cloning the repository
2. Clone Repository

   Clone the Vemetric repository:

   git clone https://github.com/vemetric/vemetric.git
   cd vemetric
   

Docker Compose Deployment

1. Start Infrastructure Services

Vemetric uses Docker Compose to run PostgreSQL, Redis, and ClickHouse:

docker-compose up -d

This will start:

PostgreSQL

Port: 5433

Database: vemetric

Redis

Port: 6379

With persistence enabled

ClickHouse

HTTP: 8123

Native: 9000

PostgreSQL runs on port 5433 (not the default 5432) to avoid conflicts with existing installations.

2. Configure Environment Variables

Copy the example environment file and configure it:

cp .env.example .env

Edit .env with your configuration. See Configuration for detailed environment variable documentation.

Minimum required changes:

.env

# Generate a secure random string for these values
EMAIL_TOKEN_SECRET=your-secret-key-here
BETTER_AUTH_SECRET=your-auth-secret-here

# Update to your domain
BETTER_AUTH_URL=https://your-domain.com

Always generate strong, unique secrets for production deployments. Never use the example values in production.

3. Install Dependencies

Install all workspace dependencies:

bun install

This installs dependencies for all apps and packages in the monorepo.

4. Run Database Migrations

1. Generate Prisma Client

   Generate the Prisma client for PostgreSQL:

   cd packages/database
   bun run db:generate
   cd ../..
   
2. Run PostgreSQL Migrations

   Apply all PostgreSQL schema migrations:

   cd packages/database
   bun run db:deploy
   cd ../..
   
3. Run ClickHouse Migrations

   Apply all ClickHouse table migrations:

   cd packages/clickhouse
   bun run migrate-local
   cd ../..
   

5. Start All Services

Start all Vemetric services in development mode:

bun dev

This starts:

• App (Web UI + API): http://localhost:4000
• Hub (Event Ingestion): http://localhost:4004
• Worker (Background Jobs): Running in background
• BullBoard (Queue UI): http://localhost:4100

The bun dev command uses Turborepo to run all services except health-check. Services will auto-reload on code changes.

6. Access the Application

Open your browser and navigate to:

http://localhost:4000

Create your first user account and start tracking analytics!

Production Deployment

Building for Production

1. Build All Services

   bun run build
   

   This builds all apps and packages, excluding the dev-proxy.

2. Build Docker Images

   Build production Docker images for each service:

   # Build App image
   docker build -f apps/app/Dockerfile -t vemetric-app:latest .
   
   # Build Hub image
   docker build -f apps/hub/Dockerfile -t vemetric-hub:latest .
   
   # Build Worker image
   docker build -f apps/worker/Dockerfile -t vemetric-worker:latest .
   
   # Build BullBoard image (optional)
   docker build -f apps/bullboard/Dockerfile -t vemetric-bullboard:latest .
   
3. Run Production Services

   Start the built images with your production configuration:

   docker run -d \
     --name vemetric-app \
     --env-file .env \
     -p 4000:4000 \
     vemetric-app:latest
   
   docker run -d \
     --name vemetric-hub \
     --env-file .env \
     -p 4004:4004 \
     vemetric-hub:latest
   
   docker run -d \
     --name vemetric-worker \
     --env-file .env \
     vemetric-worker:latest
   

Exposed Ports

Service	Port	Protocol	Purpose
App	4000	HTTP	Web UI and API
Hub	4004	HTTP	Event ingestion
BullBoard	4100	HTTP	Queue monitoring UI
PostgreSQL	5433	TCP	Database connections
Redis	6379	TCP	Cache and queues
ClickHouse HTTP	8123	HTTP	ClickHouse HTTP API
ClickHouse Native	9000	TCP	ClickHouse native protocol
ClickHouse Metrics	9363	HTTP	Prometheus metrics

Reverse Proxy Configuration

For production deployments, use a reverse proxy like Nginx or Caddy:

Nginx

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

    location / {
        proxy_pass http://localhost:4000;
        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;
    }
}

# Hub endpoint for event ingestion
server {
    listen 80;
    server_name hub.yourdomain.com;

    location / {
        proxy_pass http://localhost:4004;
        proxy_http_version 1.1;
        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;
    }
}

Always use HTTPS in production. Configure SSL certificates using Let’s Encrypt or your preferred certificate provider.

Health Checks

Vemetric includes health check endpoints for monitoring:

# Check App health
curl http://localhost:4000/api/health

# Check Hub health
curl http://localhost:4004/health

You can use these endpoints with Docker health checks, Kubernetes probes, or monitoring tools.

Verification

Verify your deployment:

1. Check Database Connections

   Ensure PostgreSQL and ClickHouse are accessible:

   # Test PostgreSQL
   docker exec vemetric-postgres psql -U postgres -d vemetric -c "SELECT 1;"
   
   # Test ClickHouse
   curl http://localhost:8123/ping
   
2. Check Redis

   Verify Redis is running:

   docker exec vemetric-redis redis-cli ping
   
3. Monitor Queue Jobs

   Access BullBoard to monitor background jobs:

   http://localhost:4100
   

   Default credentials (change in .env):

   • Username: bullboard
   • Password: password

Troubleshooting

Services won't start

Check Docker logs:

docker-compose logs -f

Ensure all required ports are available and not in use by other services.

Database connection errors

Verify environment variables in .env match your Docker Compose configuration:

• PostgreSQL port: 5433
• ClickHouse port: 8123
• Redis port: 6379

Migration failures

Ensure databases are running before running migrations:

docker-compose ps

If services are unhealthy, restart them:

docker-compose restart

Next Steps

Configuration

Configure environment variables for your deployment

Monitoring

Set up monitoring and observability