Environment Variables

Overview

Tambo360 requires several environment variables to configure the backend API, database connections, authentication, and email services. This guide provides a comprehensive reference for all configuration options.

Never commit .env files containing secrets to version control. Use .env.example as a template and add .env to .gitignore.

Environment File Structure

Create a .env file in your project root and backend directory:

# Project structure
tambo360/
├── .env                    # Root environment file (for Docker Compose)
├── apps/
│   ├── backend/
│   │   └── .env           # Backend environment variables
│   └── frontend/
│       └── .env           # Frontend environment variables

Backend Environment Variables

Required Variables

These variables must be set for the backend to function:

.env

# Server Configuration
NODE_ENV=development
PORT=3000

# Database
DATABASE_URL="postgresql://postgres:tambo360@localhost:5433/tambo?schema=public"

# Authentication
JWT_SECRET="your-secret-key-change-in-production-min-32-chars"

# Frontend URL (for CORS)
FRONTEND_URL="http://localhost:5173"

Optional Variables

These variables enable additional features:

.env

# Email Configuration (Gmail)
EMAIL_USER="[email protected]"
EMAIL_PASS="your-app-specific-password"

# CORS Configuration
CORS_ORIGIN="http://localhost:5173"

# Backend URL (for email links)
BACKEND_URL="http://localhost:3000"

# Tambo AI Service (if available)
TAMBO_AI_URL="http://ai-service:8000"

# Database Direct URL (for migrations)
DIRECT_URL="postgresql://postgres:tambo360@localhost:5433/tambo"

Frontend Environment Variables

Frontend variables use the VITE_ prefix:

apps/frontend/.env

# API Configuration
VITE_API_URL="http://localhost:3000/api"

# AI Service (optional)
VITE_API_IA_URL="http://localhost:8000"

Vite only exposes environment variables that start with VITE_ to the client-side code for security.

Variable Reference

NODE_ENV

string

required

Application environment mode.Values:

development - Development mode with debugging
production - Production mode with optimizations
test - Testing mode

Default: developmentExample:

NODE_ENV=production

PORT

number

required

Port number for the backend server.Default: 3000Example:

PORT=3000

Ensure this port is not already in use by another application.

DATABASE_URL

string

required

PostgreSQL connection string used by Prisma.Format:

postgresql://[user]:[password]@[host]:[port]/[database]?[parameters]

Parameters:

schema - Database schema (default: public)
connection_limit - Max connections (default: unlimited)
pool_timeout - Connection timeout in seconds
sslmode - SSL mode (require, prefer, disable)

Examples:

# Local development
DATABASE_URL="postgresql://postgres:tambo360@localhost:5433/tambo"

# Docker container
DATABASE_URL="postgresql://postgres:tambo360@db:5432/tambo"

# Production with SSL
DATABASE_URL="postgresql://user:[email protected]:5432/tambo?sslmode=require&connection_limit=10"

Use strong passwords for production databases. Never use default credentials.

DIRECT_URL

string

Direct database connection URL, bypassing connection poolers.Use case: Required when using PgBouncer or other connection poolers that don’t support certain Prisma features.Example:

DIRECT_URL="postgresql://postgres:tambo360@localhost:5433/tambo"

JWT_SECRET

string

required

Secret key for signing JWT authentication tokens.Requirements:

Minimum 32 characters
Use cryptographically secure random string
Different for each environment

Generate secure secret:

# Using openssl
openssl rand -base64 32

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

Example:

JWT_SECRET="8f7d6e5c4b3a29180f7e6d5c4b3a29180f7e6d5c4b3a2918"

Never use the default or example JWT_SECRET in production. This will compromise your application security.

FRONTEND_URL

string

required

URL where the frontend application is hosted.Use cases:

CORS configuration
Email verification links
Password reset links

Examples:

# Development
FRONTEND_URL="http://localhost:5173"

# Production
FRONTEND_URL="https://app.tambo360.com"

BACKEND_URL

string

URL where the backend API is accessible.Use cases:

Email verification links
Webhook callbacks

Examples:

# Development
BACKEND_URL="http://localhost:3000"

# Production
BACKEND_URL="https://api.tambo360.com"

CORS_ORIGIN

string

Allowed CORS origins for API requests.Values:

Single origin: "http://localhost:5173"
Multiple origins: "http://localhost:5173,https://app.tambo360.com"
All origins (dev only): "*"

Examples:

# Single origin
CORS_ORIGIN="http://localhost:5173"

# Multiple origins
CORS_ORIGIN="http://localhost:5173,https://staging.tambo360.com"

Never use "*" in production. Always specify exact origins.

EMAIL_USER

string

Email account username for sending emails.Supported providers:

Gmail
SendGrid (via SENDGRID_API_KEY)
Custom SMTP servers

Example:

EMAIL_USER="[email protected]"

For Gmail, you need to enable “Less secure app access” or use an App Password.

EMAIL_PASS

string

Email account password or app-specific password.Gmail App Password setup:

Enable 2-factor authentication
Go to Google Account > Security > App Passwords
Generate a new app password
Use the 16-character password

Example:

EMAIL_PASS="abcd efgh ijkl mnop"

Store email passwords securely. Consider using a dedicated email service for production.

SENDGRID_API_KEY

string

SendGrid API key for transactional emails.Setup:

Create a SendGrid account
Generate an API key with “Mail Send” permissions
Add to environment variables

Example:

SENDGRID_API_KEY="SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

EMAIL_FROM

string

Default “From” address for outgoing emails.Example:

EMAIL_FROM="Tambo360 <[email protected]>"

TAMBO_AI_URL

string

URL for the Tambo AI analytics service (if available).Example:

TAMBO_AI_URL="http://ai-service:8000"

VITE_API_URL

string

required

Backend API base URL for frontend requests.Examples:

# Development
VITE_API_URL="http://localhost:3000/api"

# Production
VITE_API_URL="https://api.tambo360.com/api"

This variable must be set at build time. Changing it requires rebuilding the frontend.

VITE_API_IA_URL

string

AI service URL for frontend analytics features.Example:

VITE_API_IA_URL="http://localhost:8000"

Environment-Specific Configurations

Development Environment

.env.development

NODE_ENV=development
PORT=3000
DATABASE_URL="postgresql://postgres:tambo360@localhost:5433/tambo"
JWT_SECRET="dev-secret-key-not-for-production"
FRONTEND_URL="http://localhost:5173"
CORS_ORIGIN="*"
EMAIL_USER=""
EMAIL_PASS=""

Production Environment

.env.production

NODE_ENV=production
PORT=3000
DATABASE_URL="postgresql://user:secure_password@db-host:5432/tambo?sslmode=require&connection_limit=10"
JWT_SECRET="production-secret-key-min-32-chars-random"
FRONTEND_URL="https://app.tambo360.com"
BACKEND_URL="https://api.tambo360.com"
CORS_ORIGIN="https://app.tambo360.com"
EMAIL_USER="[email protected]"
EMAIL_PASS="secure-email-password"
SENDGRID_API_KEY="SG.xxxxxxxxxxxxxx"
EMAIL_FROM="Tambo360 <[email protected]>"

Docker Environment

For Docker Compose, create a root .env file:

.env

NODE_ENV=development
PORT=3000
DATABASE_URL="postgresql://postgres:tambo360@db:5432/tambo"
JWT_SECRET="docker-dev-secret-key"
FRONTEND_URL="http://localhost:5173"
EMAIL_USER="[email protected]"
EMAIL_PASS="your-app-password"

When using Docker Compose, the database host is the service name (db) instead of localhost.

Loading Environment Variables

Backend (Node.js)

The backend uses dotenv to load environment variables:

import dotenv from 'dotenv';

// Load environment variables
dotenv.config();

// Access variables
const config = {
  port: process.env.PORT || 3000,
  databaseUrl: process.env.DATABASE_URL,
  jwtSecret: process.env.JWT_SECRET,
};

Frontend (Vite)

Vite automatically loads .env files:

// Access environment variables
const apiUrl = import.meta.env.VITE_API_URL;
const aiUrl = import.meta.env.VITE_API_IA_URL;

Security Best Practices

Use .env.example

Commit a template file without secrets:

.env.example

NODE_ENV=development
PORT=3000
DATABASE_URL=postgresql://user:password@host:5432/database
JWT_SECRET=your-secret-here

Add to .gitignore

Prevent committing secrets:

.gitignore

.env
.env.local
.env.*.local

Rotate Secrets

Regularly rotate:

JWT secrets
Database passwords
API keys
Email passwords

Use Secret Managers

For production, use:

AWS Secrets Manager
HashiCorp Vault
Azure Key Vault
Google Secret Manager

Validation

Validate required environment variables on startup:

const requiredEnvVars = [
  'NODE_ENV',
  'PORT',
  'DATABASE_URL',
  'JWT_SECRET',
  'FRONTEND_URL',
];

for (const envVar of requiredEnvVars) {
  if (!process.env[envVar]) {
    throw new Error(`Missing required environment variable: ${envVar}`);
  }
}

Troubleshooting

Environment variables not loading

Check that:

.env file is in the correct directory
File is named exactly .env (not .env.txt)
No spaces around = sign
Values with spaces are quoted

# Correct
JWT_SECRET="my secret key with spaces"

# Incorrect
JWT_SECRET = my secret key

Frontend variables undefined

Ensure variables:

Start with VITE_ prefix
Are set before running npm run build
Are accessed with import.meta.env.VITE_*

Rebuild frontend after changing variables:

npm run build

Database connection fails

Verify DATABASE_URL format:

# Check connection
psql "$DATABASE_URL"

# Test from backend
npm run dev

JWT authentication errors

Ensure JWT_SECRET:

Is at least 32 characters
Is the same across all backend instances
Hasn’t changed (would invalidate existing tokens)

Next Steps

Database Setup

Configure database with proper credentials

Docker Setup

Use environment variables with Docker

Deployment

Set up production environment variables

Get Started

Core Features

Guides

​Overview

​Environment File Structure

​Backend Environment Variables

​Required Variables

​Optional Variables

​Frontend Environment Variables

​Variable Reference

​NODE_ENV

​PORT

​DATABASE_URL

​DIRECT_URL

​JWT_SECRET

​FRONTEND_URL

​BACKEND_URL

​CORS_ORIGIN

​EMAIL_USER

​EMAIL_PASS

​SENDGRID_API_KEY

​EMAIL_FROM

​TAMBO_AI_URL

​VITE_API_URL

​VITE_API_IA_URL

​Environment-Specific Configurations

​Development Environment

​Production Environment

​Docker Environment

​Loading Environment Variables

​Backend (Node.js)

​Frontend (Vite)

​Security Best Practices

Use .env.example

Add to .gitignore

Rotate Secrets

Use Secret Managers

​Validation

​Troubleshooting

​Next Steps

Database Setup

Docker Setup

Deployment

Build docs developers (and LLMs) love

Overview

Environment File Structure

Backend Environment Variables

Required Variables

Optional Variables

Frontend Environment Variables

Variable Reference

NODE_ENV

PORT

DATABASE_URL

DIRECT_URL

JWT_SECRET

FRONTEND_URL

BACKEND_URL

CORS_ORIGIN

EMAIL_USER

EMAIL_PASS

SENDGRID_API_KEY

EMAIL_FROM

TAMBO_AI_URL

VITE_API_URL

VITE_API_IA_URL

Environment-Specific Configurations

Development Environment

Production Environment

Docker Environment

Loading Environment Variables

Backend (Node.js)

Frontend (Vite)

Security Best Practices

Validation

Troubleshooting

Next Steps