Environment Variables

GTM Feedback uses environment variables to configure database connections, authentication, AI services, and integrations.

Required Variables

These variables are required for the application to function.

Database

DATABASE_URL

string

required

PostgreSQL connection string for the application database.Format: postgresql://user:password@host:port/database?sslmode=requireProviders:

Neon (recommended for Vercel)
Supabase
Amazon RDS
Any PostgreSQL 14+ compatible database

Example:

DATABASE_URL="postgresql://user:[email protected]/neondb?sslmode=require"

Authentication

AUTH_GOOGLE_CLIENT_ID

string

required

Google OAuth 2.0 Client ID for user authentication.How to get:

Go to Google Cloud Console
Create or select a project
Enable Google+ API
Create OAuth 2.0 credentials
Add authorized redirect URI: https://your-app.vercel.app/api/auth/callback/google

Example:

AUTH_GOOGLE_CLIENT_ID="123456789-abc123def456.apps.googleusercontent.com"

AUTH_GOOGLE_SECRET

string

required

Google OAuth 2.0 Client Secret.How to get: Found in the same credentials page as the Client ID.Example:

AUTH_GOOGLE_SECRET="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45"

Keep this secret secure. Never commit it to version control.

AI / OpenAI

OPENAI_API_KEY

string

required

OpenAI API key for AI-powered features including embeddings and semantic search.How to get:

Create account at platform.openai.com
Navigate to API keys
Create new secret key

Example:

OPENAI_API_KEY="sk-proj-abc123def456ghi789jkl012mno345pqr678"

Used for:

Generating embeddings for semantic search
AI-powered feedback categorization
Slack bot AI assistant

Upstash KV (Redis)

KV_REST_API_URL

string

required

Upstash Redis REST API endpoint URL.How to get:

Create account at upstash.com
Create a new Redis database
Copy REST API URL from database details

Example:

KV_REST_API_URL="https://gusc1-decent-cat-12345.upstash.io"

KV_REST_API_TOKEN

string

required

Upstash Redis REST API authentication token.Example:

KV_REST_API_TOKEN="AaBbCc123456789XxYyZz"

KV_REST_API_READ_ONLY_TOKEN

string

required

Upstash Redis read-only token for secure read operations.Example:

KV_REST_API_READ_ONLY_TOKEN="AaBbCc987654321XxYyZz"

KV_URL

string

required

Upstash Redis connection URL (native protocol).Example:

KV_URL="redis://default:[email protected]:6379"

Optional Variables

These variables enable additional features but are not required for basic functionality.

Upstash Vector

UPSTASH_VECTOR_REST_URL

string

Upstash Vector database REST API URL for semantic search.How to get:

In Upstash dashboard, create a Vector database
Copy the REST URL

Example:

UPSTASH_VECTOR_REST_URL="https://vector-abc123.upstash.io"

If not set, semantic search features will be disabled.

UPSTASH_VECTOR_REST_TOKEN

string

Upstash Vector database authentication token.Example:

UPSTASH_VECTOR_REST_TOKEN="AbCdEf123456789XyZ"

Slack Integration (Web App)

SLACK_APP_VERIFICATION

string

Shared secret between web app and Slack app for request verification.How to generate:

openssl rand -base64 32

Example:

SLACK_APP_VERIFICATION="abc123def456ghi789jkl012mno345pqr678stu901vwx234=="

This must match the value set in your Slack app deployment.

SLACK_BOT_TOKEN

string

Slack Bot User OAuth Token for posting messages and interacting with Slack.How to get:

Go to api.slack.com/apps
Select your app → OAuth & Permissions
Copy the Bot User OAuth Token (starts with xoxb-)

Example:

SLACK_BOT_TOKEN="xoxb-123456789012-1234567890123-abcdefghijklmnopqrstuvwx"

SLACK_DIGEST_CHANNEL_ID

string

Slack channel ID where weekly feedback digests will be posted.How to get:

Open Slack in browser
Navigate to desired channel
Copy channel ID from URL (starts with C)

Example:

SLACK_DIGEST_CHANNEL_ID="C01234ABCDE"

SLACK_GTM_FEEDBACK_CHANNEL_ID

string

Slack channel ID for real-time feedback notifications.Example:

SLACK_GTM_FEEDBACK_CHANNEL_ID="C56789FGHIJ"

Slack Integration (Slack App)

SLACK_SIGNING_SECRET

string

Slack app signing secret for request verification.How to get:

Go to api.slack.com/apps
Select your app → Basic Information → App Credentials
Copy the Signing Secret

Example:

SLACK_SIGNING_SECRET="abc123def456ghi789jkl012mno345pq"

AI_GATEWAY_API_KEY

string

API key for AI Gateway (alternative to VERCEL_OIDC_TOKEN).Example:

AI_GATEWAY_API_KEY="your-gateway-api-key"

VERCEL_OIDC_TOKEN

string

Vercel OIDC token for secure AI service authentication.Note: This is automatically provided in Vercel deployments.

NGROK_AUTH_TOKEN

string

ngrok authentication token for local development tunneling.How to get:

Create account at ngrok.com
Copy auth token from dashboard

Example:

NGROK_AUTH_TOKEN="2abc123def456ghi789jkl012mno345_pqr678stu901vwx234yz"

Only needed for local Slack app development.

Cron Jobs

CRON_SECRET

string

Secret key for authenticating cron job requests.How to generate:

openssl rand -hex 32

Example:

CRON_SECRET="abc123def456ghi789jkl012mno345pqr678stu901vwx234yz"

Used for:

Weekly Slack digests
Scheduled data cleanup
Analytics aggregation

Other Configuration

EXTERNAL_API_VERIFICATION

string

Verification token for external API integrations.Example:

EXTERNAL_API_VERIFICATION="your-external-api-secret"

NEXT_PUBLIC_APP_URL

string

Public URL of your deployed application.Example:

NEXT_PUBLIC_APP_URL="https://feedback.yourcompany.com"

Default: Automatically set by Vercel

SYSTEM_USER_ID

string

UUID of the system user for automated actions.Default:

SYSTEM_USER_ID="00000000-0000-0000-0000-000000000001"

Only change this if you’re using a custom system user ID.

Configuration by Deployment Type

Web App (Minimal)
Web App (Full Features)
Slack App

Minimum required variables to run the web app:

# Database
DATABASE_URL="postgresql://..."

# Authentication
AUTH_GOOGLE_CLIENT_ID="..."
AUTH_GOOGLE_SECRET="..."

# AI
OPENAI_API_KEY="sk-..."

# Redis
KV_REST_API_URL="https://..."
KV_REST_API_TOKEN="..."
KV_REST_API_READ_ONLY_TOKEN="..."
KV_URL="redis://..."

All variables for complete functionality:

# Database
DATABASE_URL="postgresql://..."

# Authentication
AUTH_GOOGLE_CLIENT_ID="..."
AUTH_GOOGLE_SECRET="..."

# AI
OPENAI_API_KEY="sk-..."

# Redis
KV_REST_API_URL="https://..."
KV_REST_API_TOKEN="..."
KV_REST_API_READ_ONLY_TOKEN="..."
KV_URL="redis://..."

# Vector Search
UPSTASH_VECTOR_REST_URL="https://..."
UPSTASH_VECTOR_REST_TOKEN="..."

# Slack
SLACK_APP_VERIFICATION="..."
SLACK_BOT_TOKEN="xoxb-..."
SLACK_DIGEST_CHANNEL_ID="C..."
SLACK_GTM_FEEDBACK_CHANNEL_ID="C..."

# Cron
CRON_SECRET="..."

Required variables for Slack app:

# Slack Credentials
SLACK_SIGNING_SECRET="..."
SLACK_BOT_TOKEN="xoxb-..."
SLACK_APP_VERIFICATION="..."

# AI (optional but recommended)
AI_GATEWAY_API_KEY="..."
# OR
VERCEL_OIDC_TOKEN="..."

# Local Development Only
NGROK_AUTH_TOKEN="..."

Security Best Practices

Never commit environment variables to version control. Use .env.local for local development and Vercel’s environment variable settings for production.

Rotate secrets regularly

Rotate sensitive credentials (API keys, tokens, secrets) every 90 days or immediately if compromised.

Use different values per environment

Use separate credentials for development, staging, and production environments.

Restrict API key permissions

Configure API keys with minimum required permissions. For example, use read-only tokens where possible.

Monitor usage

Regularly check API usage dashboards for unexpected activity that might indicate compromised credentials.

Troubleshooting

Variables not updating after change

After changing environment variables in Vercel:

Trigger a new deployment (or wait for next git push)
Variables are only loaded at build time, not runtime
Check Vercel deployment logs to verify new values are set

Local .env not working

Ensure file is named exactly .env or .env.local
Restart your development server after changes
Verify file is in the correct directory (app root)
Check for typos in variable names

Database connection fails

Verify connection string format is correct
Check that ?sslmode=require is included for most providers
Ensure database allows connections from Vercel IPs
Test connection using a PostgreSQL client

Next Steps

Web App Deployment

Deploy the main feedback application

Slack App Deployment

Set up the Slack integration

Get Started

Core Concepts

Deployment

Features

Integrations

Development

Required Variables

Database

Authentication

AI / OpenAI

Upstash KV (Redis)

Optional Variables

Upstash Vector

Slack Integration (Web App)

Slack Integration (Slack App)

Cron Jobs

Other Configuration

Configuration by Deployment Type

Security Best Practices

Troubleshooting

Next Steps

Web App Deployment

Slack App Deployment

Build docs developers (and LLMs) love

Get Started

Core Concepts

Deployment

Features

Integrations

Development

​Required Variables

​Database

​Authentication

​AI / OpenAI

​Upstash KV (Redis)

​Optional Variables

​Upstash Vector

​Slack Integration (Web App)

​Slack Integration (Slack App)

​Cron Jobs

​Other Configuration

​Configuration by Deployment Type

​Security Best Practices

​Troubleshooting

​Next Steps

Web App Deployment

Slack App Deployment

Build docs developers (and LLMs) love

Required Variables

Database

Authentication

AI / OpenAI

Upstash KV (Redis)

Optional Variables

Upstash Vector

Slack Integration (Web App)

Slack Integration (Slack App)

Cron Jobs

Other Configuration

Configuration by Deployment Type

Security Best Practices

Troubleshooting

Next Steps