Environment Variables

MicroCBM requires specific environment variables to be configured before deployment. These variables control API connectivity, session management, and application behavior.

Required Variables

These environment variables must be set for the application to function correctly.

NEXT_PUBLIC_API_URL

string

required

The base URL of the backend REST API that MicroCBM connects to.

Example:

.env.local

NEXT_PUBLIC_API_URL=https://api.example.com

Variables prefixed with NEXT_PUBLIC_ are exposed to the browser. Do not store secrets in public environment variables.

Usage in Code: The API URL is used throughout the application to make HTTP requests:

import axios from "axios";

const api = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL,
  headers: {
    "Content-Type": "application/json",
  },
});

SESSION_SECRET

string

required

A secret key used for session management and JWT token validation. Must be a strong, random string.

Example:

.env.local

SESSION_SECRET=your-secure-random-string-here

Generate a secure random string using: openssl rand -base64 32

Security Requirements:

Minimum 32 characters
Include uppercase, lowercase, numbers, and symbols
Never commit to version control
Use different values for development and production

Environment File Setup

Create a .env.local file in the project root:

.env.local

# Backend API Configuration
NEXT_PUBLIC_API_URL=https://api.example.com

# Session Management
SESSION_SECRET=your-secure-random-string-here

The .env.local file is gitignored by default. Never commit environment files containing secrets to version control.

Environment Files

Next.js supports multiple environment files with different priorities:

File	Description	Priority
`.env`	Default values for all environments	Lowest
`.env.local`	Local overrides (gitignored)	High
`.env.development`	Development environment only	Medium
`.env.production`	Production environment only	Medium
`.env.development.local`	Local development overrides	Highest
`.env.production.local`	Local production overrides	Highest

Variables in .env.local override all other environment files except .env.*.local.

Platform-Specific Configuration

Vercel

Add environment variables in the Vercel dashboard:

Open Project Settings

Navigate to your project in the Vercel dashboard and click Settings.

Add Environment Variables

Go to Environment Variables and add each variable with its value.

Select Environments

Choose which environments (Production, Preview, Development) should use each variable.

Redeploy

Trigger a new deployment to apply the changes.

Using Vercel CLI:

vercel env add NEXT_PUBLIC_API_URL
vercel env add SESSION_SECRET

Netlify

Configure environment variables in Netlify:

Open Site Settings

Go to Site Settings > Environment Variables.

Add Variables

Click Add a variable and enter the key-value pairs.

Deploy Context

Select which deploy contexts (Production, Deploy Previews, Branch deploys) should use each variable.

Docker

Pass environment variables to Docker containers: Using .env file:

docker run --env-file .env.local -p 3000:3000 microcbm

Using -e flags:

docker run \
  -e NEXT_PUBLIC_API_URL=https://api.example.com \
  -e SESSION_SECRET=your-secret \
  -p 3000:3000 \
  microcbm

Using docker-compose:

docker-compose.yml

services:
  web:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL}
      - SESSION_SECRET=${SESSION_SECRET}

Development vs Production

Development Environment

.env.development.local

NEXT_PUBLIC_API_URL=http://localhost:8000
SESSION_SECRET=dev-secret-not-for-production

Production Environment

.env.production

NEXT_PUBLIC_API_URL=https://api.production.com
SESSION_SECRET=strong-production-secret-from-secrets-manager

Never use development secrets in production. Use a secrets management service like AWS Secrets Manager, HashiCorp Vault, or your platform’s built-in secrets management.

Validation

Verify your environment variables are loaded correctly:

// Run this in a server component or API route
console.log("API URL:", process.env.NEXT_PUBLIC_API_URL);
console.log("Session secret set:", !!process.env.SESSION_SECRET);

Never log the actual value of SESSION_SECRET in production.

Backend API Requirements

Without a running backend API at the URL specified in NEXT_PUBLIC_API_URL, authentication pages will render but data-dependent pages will show errors.

Expected API Behavior:

The backend must respond to requests at the configured URL
Free-tier hosting may have 30-60 second cold start times
The API should support JWT token authentication
CORS must be configured to allow requests from your frontend domain

Troubleshooting