Configuration

Complete environment variable reference for Vemetric

Configuration

Vemetric is configured through environment variables defined in a .env file. This page documents all available configuration options.

Core Configuration

Vemetric Token

VEMETRIC_TOKEN=PLACEHOLDER

VEMETRIC_TOKEN · string · required

Internal token used for authenticating Vemetric SDK requests. Generate a unique random string for production.

Database Configuration

PostgreSQL

Vemetric uses PostgreSQL as the primary database for user data, projects, organizations, and application state.

DATABASE_URL="postgresql://postgres:password@localhost:5433/vemetric?schema=public"

DATABASE_URL · string · required

PostgreSQL connection string in the format:

postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=SCHEMA

Default local setup:

• User: postgres
• Password: password
• Host: localhost
• Port: 5433
• Database: vemetric

The default Docker Compose setup uses port 5433 to avoid conflicts with existing PostgreSQL installations on port 5432.

ClickHouse

ClickHouse stores all analytics events, sessions, devices, and user data for high-performance querying.

# ClickHouse Migrations
CH_MIGRATIONS_HOST=http://localhost:8123
CH_MIGRATIONS_USER=default
CH_MIGRATIONS_PASSWORD=password
CH_MIGRATIONS_DB=vemetric

# ClickHouse Client
CLICKHOUSE_URL=http://localhost:8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=password
CLICKHOUSE_DATABASE=vemetric

CH_MIGRATIONS_HOST · string · required

ClickHouse HTTP endpoint for running migrations. Default: http://localhost:8123

CH_MIGRATIONS_USER · string · required

ClickHouse username for migrations. Default: default

CH_MIGRATIONS_PASSWORD · string · required

ClickHouse password for migrations. Default: password

CH_MIGRATIONS_DB · string · required

ClickHouse database name. Default: vemetric

CLICKHOUSE_URL · string · required

ClickHouse HTTP endpoint for application connections. Default: http://localhost:8123

CLICKHOUSE_USER · string · required

ClickHouse username for application connections. Default: default

CLICKHOUSE_PASSWORD · string · required

ClickHouse password for application connections. Default: password

CLICKHOUSE_DATABASE · string · required

ClickHouse database name. Default: vemetric

Redis Configuration

REDIS_URL=redis://localhost:6379

REDIS_URL · string · required

Redis connection URL. Used for caching, session storage, and BullMQ job queues.

Format: redis://[username:password@]host:port[/db]

Default: redis://localhost:6379

Redis is critical for job processing. Ensure Redis persistence is enabled in production to prevent job loss during restarts.

Authentication Configuration

Better Auth

Vemetric uses Better Auth for user authentication.

BETTER_AUTH_SECRET=123456789
BETTER_AUTH_URL=https://app.vemetric.localhost:4050

BETTER_AUTH_SECRET · string · required

Secret key for signing authentication tokens and sessions.

IMPORTANT: Generate a strong random string (at least 32 characters) for production:

openssl rand -base64 32

BETTER_AUTH_URL · string · required

The base URL where your Vemetric app is hosted. Used for OAuth callbacks and email links.

Examples:

• Development: http://localhost:4000
• Production: https://analytics.yourdomain.com

Email Token Secret

EMAIL_TOKEN_SECRET=its-a-secret

EMAIL_TOKEN_SECRET · string · required

Secret key for signing email unsubscribe tokens.

Generate a unique random string for production:

openssl rand -hex 32

Queue Monitoring (BullBoard)

BULLBOARD_USERNAME=bullboard
BULLBOARD_PASSWORD=password

BULLBOARD_USERNAME · string · required

Username for accessing the BullBoard queue monitoring UI at http://localhost:4100

BULLBOARD_PASSWORD · string · required

Password for BullBoard authentication. Change this in production!

BullBoard provides access to sensitive job data and queue controls. Use strong credentials and restrict access in production.

Optional Integrations

Email (Postmark)

Configure Postmark for transactional emails (user invitations, notifications, drip campaigns).

POSTMARK_SERVER_API_TOKEN=PLACEHOLDER
POSTMARK_TRANSACTIONAL_MESSAGE_STREAM_ID=outbound

POSTMARK_SERVER_API_TOKEN · string

Your Postmark server API token. Get this from your Postmark account.

If not configured, email functionality will be disabled.

POSTMARK_TRANSACTIONAL_MESSAGE_STREAM_ID · string

Postmark message stream ID for transactional emails. Default: outbound

Payments (Paddle)

Configure Paddle for billing and subscriptions (if offering Vemetric as a service).

PADDLE_API_KEY=
PADDLE_WEBHOOK_SECRET_KEY=

PADDLE_API_KEY · string

Paddle API key for managing subscriptions and payments.

PADDLE_WEBHOOK_SECRET_KEY · string

Paddle webhook secret for verifying webhook authenticity.

Paddle integration is optional and only needed if you plan to offer Vemetric as a paid service to customers.

Avatar Storage (S3-Compatible)

Enable user avatar uploads using any S3-compatible storage provider (AWS S3, Cloudflare R2, MinIO).

# Uncomment and configure to enable avatar uploads
# AWS_ACCESS_KEY_ID=
# AWS_SECRET_ACCESS_KEY=
# AWS_S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
# AWS_S3_AVATARS_BUCKET=vemetric-avatars
# AWS_S3_AVATARS_REGION=auto
# AWS_S3_AVATARS_PUBLIC_URL=https://avatars.vemetric.com
# AWS_S3_AVATARS_KEY_PREFIX=avatars/

AWS_ACCESS_KEY_ID · string

S3 access key ID for authentication.

AWS_SECRET_ACCESS_KEY · string

S3 secret access key for authentication.

AWS_S3_ENDPOINT · string

S3-compatible endpoint URL.

Examples:

• AWS S3: Leave empty or use regional endpoint
• Cloudflare R2: https://<account-id>.r2.cloudflarestorage.com
• MinIO: http://minio.yourdomain.com:9000

AWS_S3_AVATARS_BUCKET · string

S3 bucket name for storing avatar images.

AWS_S3_AVATARS_REGION · string

S3 bucket region.

• AWS S3: Use region like us-east-1
• Cloudflare R2: Use auto

AWS_S3_AVATARS_PUBLIC_URL · string

Public URL for accessing uploaded avatars.

Examples:

• https://avatars.yourdomain.com
• https://<bucket>.s3.amazonaws.com

AWS_S3_AVATARS_KEY_PREFIX · string

Optional prefix for avatar object keys.

• Use avatars/ to organize files in a subdirectory
• Leave empty for a dedicated subdomain (e.g., avatars.example.com)

For Cloudflare R2:

1. Create an R2 bucket
2. Get API credentials from the R2 dashboard
3. Configure a custom domain for public access
4. Set AWS_S3_AVATARS_REGION=auto

Environment-Specific Configuration

Development

For local development, use the default .env.example values:

cp .env.example .env
# Edit .env and set required secrets

Production

1. Generate Secure Secrets

   # Generate Better Auth secret
   openssl rand -base64 32
   
   # Generate Email token secret
   openssl rand -hex 32
   
2. Update Database URLs

   Point to your production databases:

   DATABASE_URL="postgresql://user:[e-mail]:5432/vemetric"
   CLICKHOUSE_URL=http://clickhouse.example.com:8123
   REDIS_URL=redis://redis.example.com:6379
   
3. Set Production URLs

   BETTER_AUTH_URL=https://analytics.yourdomain.com
   
4. Configure Integrations

   Set up optional services:

   • Postmark for emails
   • S3 for avatars
   • Paddle for billing (if needed)

Security Best Practices

Never commit .env files to version control!

The .env file is already in .gitignore, but always verify before pushing code.

Use Strong Secrets

Generate cryptographically secure random strings for all secret values. Never use example or default values in production.

Rotate Secrets

Periodically rotate authentication secrets and API keys. Update them in your deployment without downtime.

Restrict Database Access

Use firewall rules to limit database access to only your application servers.

Use Environment Variables

In containerized environments, pass secrets via environment variables or secret management systems (not .env files).

Validation

Verify your configuration:

# Test database connections
bun run apps/app/src/backend/index.ts

# Check for missing environment variables
grep -E "^[A-Z_]+=$" .env

Next Steps

Database Setup

Set up and migrate PostgreSQL and ClickHouse databases

Monitoring

Monitor your Vemetric deployment