Skip to main content

​
Overview

The backend requires several environment variables for configuration. Copy .env.example to .env and configure the following variables. 
cp .env.example .env

​
Required Variables

All of these variables are required for the application to start. The server validates them on startup.

​
Server Configuration

​
PORT
number
default:"4000"
Port number where the server will listen for requests.
PORT=4000
​
NODE_ENV
string
default:"development"
Application environment. Affects error handling, logging, and CORS.Options: development, production, test
NODE_ENV=development
​
FRONTEND_URL
string
required
URL of your frontend application. Used for CORS configuration.
# Development
FRONTEND_URL=http://localhost:3000

# Production
FRONTEND_URL=https://your-frontend.vercel.app

​
Database Configuration

​
DATABASE_URL
string
required
PostgreSQL connection string. This is the primary database connection.Format: postgresql://[user]:[password]@[host]:[port]/[database]
# Local development
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/los_inmaduros

# Docker development
DATABASE_URL=postgresql://postgres:postgres@postgres:5432/los_inmaduros

# Production (example)
DATABASE_URL=postgresql://user:[email protected]:5432/los_inmaduros
Never commit your production database URL to version control. Use environment variables in your deployment platform.

​
Authentication (Clerk)

​
CLERK_SECRET_KEY
string
required
Secret key from your Clerk dashboard. Used for server-side authentication.Format: sk_test_... (test) or sk_live_... (production)
CLERK_SECRET_KEY=sk_test_your_secret_key_here
Get this from Clerk Dashboard → Your App → API Keys → Secret Keys
​
CLERK_PUBLISHABLE_KEY
string
required
Publishable key from your Clerk dashboard. Safe to expose in frontend code.Format: pk_test_... (test) or pk_live_... (production)
CLERK_PUBLISHABLE_KEY=pk_test_your_publishable_key_here

​
Storage (Supabase)

​
SUPABASE_URL
string
required
Your Supabase project URL. Used for file storage operations.Format: https://[project-id].supabase.co
SUPABASE_URL=https://your-project.supabase.co
Get this from Supabase Dashboard → Your Project → Settings → API
​
SUPABASE_ANON_KEY
string
required
Supabase anonymous/public API key. Used for authenticated storage access.
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
This is the anon (public) key, not the service_role key. The service role key should never be used in client-side code.

​
Docker-Specific Variables

These variables are only used in the Docker Compose setup for local development:
​
DB_USER
string
default:"postgres"
PostgreSQL username for Docker container.
DB_USER=postgres
​
DB_PASSWORD
string
default:"postgres"
PostgreSQL password for Docker container.
DB_PASSWORD=postgres
Change this to a strong password in production!
​
DB_NAME
string
default:"los_inmaduros"
PostgreSQL database name for Docker container.
DB_NAME=los_inmaduros

​
Environment Variable Validation

The application validates all required environment variables on startup using the validateEnv() function in src/config/env.config.ts: 
const requiredEnvVars = [
  "DATABASE_URL",
  "CLERK_SECRET_KEY",
  "CLERK_PUBLISHABLE_KEY",
  "SUPABASE_URL",
  "SUPABASE_ANON_KEY",
  "FRONTEND_URL",
];
If any required variable is missing, the application will throw an error: 
Error: Missing required environment variables: CLERK_SECRET_KEY, SUPABASE_URL

​
Example Configurations

​
Development (.env)

# Server
PORT=4000
NODE_ENV=development

# Frontend URL
FRONTEND_URL=http://localhost:3000

# Database (local)
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/los_inmaduros

# Supabase (test project)
SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Clerk (test environment)
CLERK_SECRET_KEY=sk_test_xxxxxxxxxxxx
CLERK_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxx

# Docker Database
DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=los_inmaduros

​
Production (.env)

# Server
PORT=4000
NODE_ENV=production

# Frontend URL
FRONTEND_URL=https://losinmaduros.vercel.app

# Database (managed PostgreSQL)
DATABASE_URL=postgresql://prod_user:[email protected]:5432/los_inmaduros_prod

# Supabase (production project)
SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Clerk (production environment)
CLERK_SECRET_KEY=sk_live_xxxxxxxxxxxx
CLERK_PUBLISHABLE_KEY=pk_live_xxxxxxxxxxxx

​
Platform-Specific Setup

​
Render

  1. Go to your service → Environment
  2. Add each environment variable as a key-value pair
  3. Render automatically provides DATABASE_URL if you attach a PostgreSQL database

​
Railway

  1. Go to your project → Variables
  2. Add each variable individually or use “Raw Editor” for bulk import
  3. Railway auto-generates DATABASE_URL when you add a PostgreSQL plugin

​
Vercel (for serverless functions)

  1. Go to your project → Settings → Environment Variables
  2. Add variables for each environment (Production, Preview, Development)
  3. Use Vercel Postgres integration for DATABASE_URL

​
Docker Compose

Docker Compose automatically reads from your .env file. You can also set variables directly in docker-compose.yml: 
services:
  backend:
    environment:
      NODE_ENV: production
      DATABASE_URL: ${DATABASE_URL}
      CLERK_SECRET_KEY: ${CLERK_SECRET_KEY}

​
Security Best Practices

Never commit .env files to version control!Make sure .env is in your .gitignore:
.env
.env.local
.env.*.local
Use Clerk’s test keys (sk_test_..., pk_test_...) for development and live keys (sk_live_..., pk_live_...) for production.
Change your database passwords and API keys periodically, especially if they may have been exposed.
Platforms like Render, Railway, and Vercel provide built-in secrets management. Use these instead of committing credentials.
Set FRONTEND_URL to your exact frontend URL, not a wildcard (*).

​
Troubleshooting

​
”Missing required environment variables”

Make sure all required variables are set in your .env file: 
# Check if .env exists
ls -la .env

# View .env contents (be careful in production!)
cat .env

​
“PORT must be a valid number”

Ensure PORT is a number without quotes: 
# Correct
PORT=4000

# Incorrect
PORT="4000"

​
Variables not being loaded

Make sure you’re using the correct .env file location: 
# Should be in the project root
/home/user/los-inmaduros-backend/.env
Restart your application after changing .env: 
# Development
npm run dev

# Docker
docker-compose restart backend

​
Next Steps

Docker Deployment

Set up Docker for local development

Production Deployment

Deploy to production platforms

Build docs developers (and LLMs) love

Get started for freeTalk to us