Skip to main content

​
Overview

The E-commerce API requires several environment variables to function properly. This guide covers all required and optional configuration settings.

​
Required Environment Variables

​
Database Configuration

The API uses MySQL as its database. Configure the connection using the DATABASE_URL variable: 
DATABASE_URL="mysql://user:password@localhost:3306/ecommerce_db"
Format: mysql://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]
The DATABASE_URL is validated at startup. The application will throw an error if this variable is missing.

​
JWT Authentication

Configure JSON Web Token settings for user authentication: 
JWT_SECRET="your-super-secret-key-min-32-chars"
JWT_EXPIRY="1h"
JWT_SECRET (required)
  • Used to sign and verify JWT tokens
  • Should be a strong, random string (minimum 32 characters recommended)
  • Never commit this value to version control
JWT_EXPIRY (optional)
  • Token expiration time
  • Default: "1h" (1 hour)
  • Accepts values like: "15m", "1h", "7d"

​
Cloudinary Configuration

The API uses Cloudinary for image storage. All three variables are required: 
CLOUDINARY_CLOUD_NAME="your-cloud-name"
CLOUDINARY_API_KEY="your-api-key"
CLOUDINARY_API_SECRET="your-api-secret"
The application validates Cloudinary credentials at startup. Missing any of these variables will prevent the application from starting.
Get your credentials from the Cloudinary Dashboard:
1

Sign up for Cloudinary

Create a free account at cloudinary.com
2

Access your dashboard

Navigate to the dashboard to view your credentials
3

Copy credentials

Copy the Cloud Name, API Key, and API Secret to your .env file

​
Optional Environment Variables

​
Node Environment

NODE_ENV="development"
Values:
  • "development" (default): Enables detailed error messages
  • "production": Optimized for production with minimal error details

​
Frontend URL

FRONTEND_URL="http://localhost:3001"
Used for CORS configuration. Default: "http://localhost:3001"

​
Configuration File Structure

The configuration is loaded and validated in backend/src/config/index.ts:5-19: 
import dotenv from "dotenv";
dotenv.config();

function getRequiredEnv(key: string): string {
    const value = process.env[key];
    if (!value) {
        throw new Error(`Missing required environment variable: ${key}`);
    }
    return value;
}

export const config = {
    jwtSecret: getRequiredEnv("JWT_SECRET"),
    jwtExpiry: process.env.JWT_EXPIRY || "1h",
    dbUrl: getRequiredEnv("DATABASE_URL"),
    nodeEnv: process.env.NODE_ENV || "development",
    frontendUrl: process.env.FRONTEND_URL || "http://localhost:3001"
};

​
Complete .env Template

Create a .env file in the backend/ directory: 
# Database
DATABASE_URL="mysql://user:password@localhost:3306/ecommerce_db"

# JWT Authentication
JWT_SECRET="your-super-secret-key-min-32-chars"
JWT_EXPIRY="1h"

# Cloudinary Image Storage
CLOUDINARY_CLOUD_NAME="your-cloud-name"
CLOUDINARY_API_KEY="your-api-key"
CLOUDINARY_API_SECRET="your-api-secret"

# Application
NODE_ENV="development"
FRONTEND_URL="http://localhost:3001"

​
Docker Compose Variables

When using Docker Compose, additional MySQL variables are required in the root .env: 
# MySQL Container Configuration
MYSQL_ROOT_PASSWORD="rootpassword"
MYSQL_DATABASE="ecommerce_db"
MYSQL_USER="ecommerce_user"
MYSQL_PASSWORD="ecommerce_password"
These variables are only used by the docker-compose.yml file to configure the MySQL container. The backend uses DATABASE_URL from backend/.env.

​
Validation on Startup

The application performs validation when starting:
  1. Config validation (config/index.ts) - Checks JWT and database variables
  2. Cloudinary validation (config/cloudinary.ts:5-9) - Verifies all three Cloudinary credentials
const requiredVars = ["CLOUDINARY_CLOUD_NAME", "CLOUDINARY_API_KEY", "CLOUDINARY_API_SECRET"] as const;

for (const varName of requiredVars) {
  if (!process.env[varName]) {
    throw new Error(`Variable de entorno ${varName} no definida`);
  }
}
If any required variable is missing, the application will exit with a clear error message.

​
Next Steps

Docker Deployment

Deploy the application using Docker Compose

Database Migrations

Set up and manage database schema with Prisma

Build docs developers (and LLMs) love

Get started for freeTalk to us