Environment Setup

This guide covers everything needed to run GTM Clarity locally or deploy it to production, including prerequisites, environment configuration, and development commands.

Prerequisites

Dependency	Version	Purpose
Node.js	18+	Runtime
npm	9+	Package manager
PostgreSQL	15+ (or Neon serverless)	Primary database
Temporal Server	1.15+	Workflow orchestration

Optional

Dependency	Purpose
Docker	Running Temporal and PostgreSQL locally
Neon CLI	Managing Neon serverless PostgreSQL

Environment Variables

Create a .env file in the project root. Use .env.example as a template:

Authentication (Clerk)

Variable	Required	Description
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY	Yes	Clerk publishable key (starts with pk_test_ or pk_live_)
CLERK_SECRET_KEY	Yes	Clerk secret key (starts with sk_test_ or sk_live_)
NEXT_PUBLIC_CLERK_SIGN_IN_URL	Yes	Sign-in page path (default: /sign-in)
NEXT_PUBLIC_CLERK_SIGN_UP_URL	Yes	Sign-up page path (default: /sign-up)
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL	Yes	Redirect after sign-in (default: /)
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL	Yes	Redirect after sign-up (default: /)

Database (Neon PostgreSQL)

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection string (Neon pooled endpoint with ?sslmode=require)

Salesforce OAuth

Variable	Required	Description
SALESFORCE_CLIENT_ID	If using Salesforce	Connected App client ID (from Setup > App Manager)
SALESFORCE_CLIENT_SECRET	If using Salesforce	Connected App client secret
SALESFORCE_CALLBACK_URL	If using Salesforce	OAuth callback URL (default: http://localhost:3000/api/connectors/salesforce/callback)

Connector Security

Variable	Required	Description
CONNECTOR_ENCRYPTION_KEY	Yes	32-byte hex string for AES-256-GCM token encryption

Generate the encryption key:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Security

Never commit .env files to source control. The .gitignore file is pre-configured to exclude them. If you suspect a key has been compromised, rotate it immediately and re-authenticate all connectors.

Database Setup

Option 1: Neon Serverless (Recommended)

1. Create an account at neon.tech
2. Create a new project and database named scoring
3. Copy the pooled connection string to DATABASE_URL
4. Run migrations:

npm run drizzle migrate

Option 2: Local PostgreSQL

1. Install PostgreSQL 15+
2. Create a database:

createdb scoring

3. Set DATABASE_URL=postgresql://localhost:5432/scoring in .env
4. Run migrations:

npm run drizzle migrate

Drizzle ORM Commands

Command	Description
npm run drizzle migrate	Run pending migrations
npm run drizzle studio	Open interactive DB browser at https://local.drizzle.studio

Clerk Setup

1. Create an account at clerk.com
2. Create a new application
3. Enable Organizations in the Clerk dashboard (required for multi-tenancy)
4. Copy the publishable key and secret key to .env
5. Configure the redirect URLs to match your deployment

info

Clerk Organizations are the backbone of GTM Clarity's multi-tenant model. Make sure to enable the Organizations feature before first use.

Temporal Server

Option 1: Docker (Recommended for Local Dev)

docker run -d \
  --name temporal \
  -p 7233:7233 \
  -p 8233:8233 \
  temporalio/auto-setup:latest

This starts the Temporal server on port 7233 and the Web UI on port 8233.

Option 2: Temporal Cloud (Production)

For production deployments, use Temporal Cloud:

1. Create a Temporal Cloud namespace
2. Configure mTLS certificates
3. Set the connection details in your environment

Starting the Worker

The Temporal worker runs as a separate process:

npx tsx src/connectors/temporal/worker.ts

tip

In production, run the Temporal worker on dedicated instances separate from the web server. Use process managers like PM2 or container orchestration for automatic restarts.

Local Development

Install Dependencies

npm install

Run Development Server

npm run dev

The application starts at http://localhost:3000.

Run Tests

# Unit tests (Vitest)
npm test

# Watch mode
npm test -- --watch

# Specific test file
npm test -- tests/scoring/fit-engine.test.ts

# E2E tests (Playwright)
npm run test:e2e

Code Quality

# Lint
npm run lint

# Type check
npm run type-check

# Production build
npm run build

Production Build

npm run build
npm start

Production Checklist

Item	Details
Set all env variables	All Required variables from the table above
Run database migrations	npm run drizzle migrate
Start Temporal worker	Separate process on connector-sync task queue
Configure Temporal cron	Schedule scheduledSyncWorkflow per tenant
Verify Clerk organizations	Enable Organizations feature
Generate encryption key	Use crypto random bytes, store securely
Set up monitoring	Temporal Web UI, application logs, error tracking

Tech Stack Reference

Layer	Technology	Version
Frontend	Next.js (App Router)	16.1.6
UI Framework	React	19.2.3
Styling	Tailwind CSS	4
Charts	Recharts	3.7
API	tRPC	11.10
Auth	Clerk	6.39
Database	PostgreSQL (Neon)	15+
ORM	Drizzle ORM	0.45.1
Workflows	Temporal.io	1.15
CRM SDK	JSForce	3.10
Validation	Zod	4.3
Testing	Vitest	4.0
E2E Testing	Playwright	1.58

Related Pages

• Architecture -- System architecture overview
• Tenant Setup -- Configuring the first tenant
• Connector Management -- Setting up data sources