Configuration

Configure Vemetric SDKs and environment variables for optimal analytics tracking

This guide covers all configuration options for Vemetric SDKs and the self-hosted Vemetric platform.

SDK Configuration

JavaScript SDK

Configure the JavaScript SDK using the global vemetricConfig object:

<script>
  window.vemetricConfig = {
    host: 'https://hub.yourdomain.com',
    token: 'your-project-token',
    maskPaths: ['/admin/*', '/settings'],
    allowCookies: true
  };
</script>
<script src="https://hub.yourdomain.com/script.js" defer></script>

Configuration Options

host · string · required

The URL of your Vemetric hub instance.

Example: https://hub.yourdomain.com

For self-hosted instances, this should point to your hub subdomain or custom domain.

token · string · required

Your project token from the Vemetric dashboard.

You can find this in: Project Settings → API Keys → Project Token

maskPaths · string[]

Array of URL patterns to exclude from tracking. Supports wildcards (*).

Examples:

• /admin/* - Masks all admin pages
• /user/*/settings - Masks user settings pages
• /checkout/confirmation - Masks specific page

Masked pages are still tracked but their URLs are replaced with the pattern.

allowCookies · boolean · default: "true"

Whether to allow cookies for user tracking.

Set to false for cookieless tracking. Note that this may reduce accuracy for returning visitor identification.

React SDK

Configure the React SDK via the VemetricScript component props:

import { VemetricScript } from '@vemetric/react';

<VemetricScript
  host="https://hub.yourdomain.com"
  token="your-project-token"
  maskPaths={['/admin/*', '/settings']}
  allowCookies={true}
/>

The React SDK accepts the same configuration options as the JavaScript SDK.

Node.js SDK

Configure the Node.js SDK when creating the client instance:

import { Vemetric } from '@vemetric/node';

const vemetric = new Vemetric({
  host: 'https://hub.yourdomain.com',
  token: process.env.VEMETRIC_TOKEN
});

Configuration Options

host · string · required

The URL of your Vemetric hub instance.

token · string · required

Your project token.

Always use environment variables for tokens in production. Never hardcode credentials.

Environment Variables

For self-hosted Vemetric instances, configure these environment variables.

Core Configuration

VEMETRIC_TOKEN · string · required

Your project token for internal Vemetric tracking.

VEMETRIC_TOKEN=your-project-token

DOMAIN · string

Base domain for your Vemetric instance.

DOMAIN=vemetric.yourdomain.com

Defaults to vemetric.localhost:4050 for development.

VEMETRIC_DEV_PROXY_PORT · number

Port for the development proxy server.

VEMETRIC_DEV_PROXY_PORT=4050

Default: 4050

Database Configuration

DATABASE_URL · string · required

PostgreSQL connection string.

DATABASE_URL="postgresql://user:password@localhost:5432/vemetric?schema=public"

CLICKHOUSE_URL · string · required

ClickHouse server URL for analytics data.

CLICKHOUSE_URL=http://localhost:8123

CLICKHOUSE_USER · string · required

ClickHouse username.

CLICKHOUSE_USER=default

CLICKHOUSE_PASSWORD · string · required

ClickHouse password.

CLICKHOUSE_PASSWORD=your-password

CLICKHOUSE_DATABASE · string · required

ClickHouse database name.

CLICKHOUSE_DATABASE=vemetric

ClickHouse Migrations

CH_MIGRATIONS_HOST · string

ClickHouse host for running migrations.

CH_MIGRATIONS_HOST=http://localhost:8123

CH_MIGRATIONS_USER · string

ClickHouse user for migrations.

CH_MIGRATIONS_USER=default

CH_MIGRATIONS_PASSWORD · string

ClickHouse password for migrations.

CH_MIGRATIONS_PASSWORD=your-password

CH_MIGRATIONS_DB · string

ClickHouse database name for migrations.

CH_MIGRATIONS_DB=vemetric

Redis Configuration

REDIS_URL · string · required

Redis connection URL for caching and session management.

REDIS_URL=redis://localhost:6379

Authentication

BETTER_AUTH_SECRET · string · required

Secret key for Better Auth session encryption.

BETTER_AUTH_SECRET=your-secure-random-string

Use a strong, randomly generated secret in production.

BETTER_AUTH_URL · string · required

Public URL for Better Auth callbacks.

BETTER_AUTH_URL=https://app.vemetric.yourdomain.com

Email Configuration

EMAIL_TOKEN_SECRET · string · required

Secret for signing email verification and unsubscribe tokens.

EMAIL_TOKEN_SECRET=your-email-token-secret

POSTMARK_SERVER_API_TOKEN · string

Postmark API token for sending transactional emails.

POSTMARK_SERVER_API_TOKEN=your-postmark-token

POSTMARK_TRANSACTIONAL_MESSAGE_STREAM_ID · string

Postmark message stream ID.

POSTMARK_TRANSACTIONAL_MESSAGE_STREAM_ID=outbound

Default: outbound

Billing (Paddle)

PADDLE_API_KEY · string

Paddle API key for payment processing.

PADDLE_API_KEY=your-paddle-api-key

PADDLE_WEBHOOK_SECRET_KEY · string

Paddle webhook secret for verifying webhook signatures.

PADDLE_WEBHOOK_SECRET_KEY=your-webhook-secret

Queue Management

BULLBOARD_USERNAME · string

Username for accessing the BullBoard queue dashboard.

BULLBOARD_USERNAME=admin

Default: bullboard

BULLBOARD_PASSWORD · string

Password for accessing the BullBoard queue dashboard.

BULLBOARD_PASSWORD=your-secure-password

Default: password

Avatar Storage (Optional)

Configure S3-compatible storage for user avatar uploads.

AWS_ACCESS_KEY_ID · string

AWS access key ID (or equivalent for S3-compatible services).

AWS_ACCESS_KEY_ID=your-access-key

AWS_SECRET_ACCESS_KEY · string

AWS secret access key.

AWS_SECRET_ACCESS_KEY=your-secret-key

AWS_S3_ENDPOINT · string

S3-compatible endpoint URL.

Examples:

• Cloudflare R2: https://<account-id>.r2.cloudflarestorage.com
• MinIO: http://localhost:9000
• AWS S3: Leave empty to use default AWS endpoints

AWS_S3_ENDPOINT=https://abc123.r2.cloudflarestorage.com

AWS_S3_AVATARS_BUCKET · string

S3 bucket name for avatar storage.

AWS_S3_AVATARS_BUCKET=vemetric-avatars

AWS_S3_AVATARS_REGION · string

S3 bucket region.

AWS_S3_AVATARS_REGION=us-east-1

For Cloudflare R2, use auto.

AWS_S3_AVATARS_PUBLIC_URL · string

Public URL for accessing uploaded avatars.

AWS_S3_AVATARS_PUBLIC_URL=https://avatars.yourdomain.com

AWS_S3_AVATARS_KEY_PREFIX · string

Optional prefix for avatar object keys.

AWS_S3_AVATARS_KEY_PREFIX=avatars/

Leave empty if using a dedicated subdomain (e.g., avatars.example.com).

Project-Level Configuration

Configure project-specific settings in the Vemetric dashboard.

Excluded IPs

Exclude specific IP addresses from analytics:

1. Navigate to Project Settings → Privacy
2. Add IP addresses to exclude (one per line)
3. Save changes

Requests from excluded IPs are silently ignored and not tracked.

Excluded Countries

Exclude traffic from specific countries:

1. Navigate to Project Settings → Privacy
2. Select countries to exclude
3. Save changes

Uses ISO 3166-1 alpha-2 country codes (e.g., US, GB, DE).

API Keys

Manage API keys for programmatic access:

1. Navigate to Project Settings → API Keys
2. Create new API keys with specific permissions
3. Use keys in your backend applications

Configuration Files

Environment File

Create a .env file in your project root:

# .env

# Vemetric
VEMETRIC_TOKEN=your-project-token

# Database
DATABASE_URL="postgresql://postgres:password@localhost:5432/vemetric?schema=public"

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

# Redis
REDIS_URL=redis://localhost:6379

# Authentication
BETTER_AUTH_SECRET=your-secure-random-string
BETTER_AUTH_URL=https://app.vemetric.localhost:4050

# Email
EMAIL_TOKEN_SECRET=your-email-secret
POSTMARK_SERVER_API_TOKEN=your-postmark-token

# Billing
PADDLE_API_KEY=your-paddle-key
PADDLE_WEBHOOK_SECRET_KEY=your-webhook-secret

Never commit .env files to version control. Add .env to your .gitignore.

TypeScript Configuration

For TypeScript projects, add type definitions for environment variables:

// types/env.d.ts

declare global {
  namespace NodeJS {
    interface ProcessEnv {
      VEMETRIC_TOKEN: string;
      VEMETRIC_HOST: string;
      DATABASE_URL: string;
      CLICKHOUSE_URL: string;
      CLICKHOUSE_USER: string;
      CLICKHOUSE_PASSWORD: string;
      CLICKHOUSE_DATABASE: string;
      REDIS_URL: string;
      BETTER_AUTH_SECRET: string;
      BETTER_AUTH_URL: string;
    }
  }
}

export {};

Configuration Best Practices

Use environment variables for secrets

Always store sensitive configuration in environment variables:

// ✅ Good
const vemetric = new Vemetric({
  host: process.env.VEMETRIC_HOST!,
  token: process.env.VEMETRIC_TOKEN!
});

// ❌ Bad
const vemetric = new Vemetric({
  host: 'https://hub.example.com',
  token: 'hardcoded-token-123'
});

Separate development and production configs

Use different tokens and settings for each environment:

# .env.development
VEMETRIC_TOKEN=dev-token-123
VEMETRIC_HOST=http://localhost:4004

# .env.production
VEMETRIC_TOKEN=prod-token-456
VEMETRIC_HOST=https://hub.yourdomain.com

Validate required variables at startup

Check for required environment variables when your app starts:

if (!process.env.VEMETRIC_TOKEN) {
  throw new Error('VEMETRIC_TOKEN is required');
}

if (!process.env.VEMETRIC_HOST) {
  throw new Error('VEMETRIC_HOST is required');
}

Document your configuration

Create a .env.example file with all required variables:

# .env.example
VEMETRIC_TOKEN=your-token-here
VEMETRIC_HOST=https://hub.yourdomain.com
DATABASE_URL=postgresql://user:pass@localhost:5432/db

Commit this file to version control (without actual values).

Troubleshooting

Events Not Appearing

1. Verify token

   Ensure your project token is correct and matches your project in the dashboard.

2. Check host URL

   Verify the host URL is accessible and points to your Vemetric hub instance.

3. Review browser console

   Look for network errors or failed requests in the browser developer tools.

4. Check excluded IPs

   Ensure your IP address isn’t in the excluded IPs list.

CORS Errors

If you see CORS errors in the browser console:

1. Verify your hub instance is configured to allow requests from your domain
2. Check that the origin header is being sent correctly
3. Ensure your hub is accessible from the browser

Cookie Issues

If user tracking isn’t working across sessions:

1. Check that allowCookies is set to true
2. Verify cookies aren’t being blocked by browser settings
3. Ensure your site is served over HTTPS in production
4. Check that cookies are being set with the correct domain

Next Steps

JavaScript SDK

JavaScript SDK reference

React SDK

React SDK documentation

Node.js SDK

Server-side tracking guide

Tracking Events

Event tracking best practices