How-To Guide

Environment Variables

Configure your installation behavior through environment variables in .env files.

Overview

Environment variables control installation behavior without code changes. Different environments (.env, .env.production) enable environment-specific configuration.

File precedence (highest to lowest):

1. .env.production (production only)
2. .env.development (development only)
3. .env (all environments)

Security: Never commit .env.production or files containing secrets to version control.

Core variables

Required variables for basic operation:

Variable	Type	Default	Description
`ATELIER_MODE`	dev \| prod	dev	Deployment mode (affects features, logging)
`NODE_ENV`	development \| production	development	Node.js environment (controls optimizations)
`PUBLIC_DOMAIN`	string	localhost	Domain name for the installation
`COMPOSE_PROJECT_NAME`	string	(directory name)	Docker Compose project identifier

Example core configuration:

 .env 
 # .env - Development
ATELIER_MODE=dev
NODE_ENV=development
PUBLIC_DOMAIN=localhost
COMPOSE_PROJECT_NAME=my-installation-dev 

 .env.production 
 # .env.production - Production
ATELIER_MODE=prod
NODE_ENV=production
PUBLIC_DOMAIN=my-installation.com
COMPOSE_PROJECT_NAME=my-installation-prod 

Development variables

Variables that affect development workflows:

Variable	Type	Default	Description
`ENABLE_HMR`	boolean	true (dev)	Hot module reload for development
`DEBUG`	boolean	true (dev)	Show detailed error messages
`LOG_LEVEL`	debug \| info \| warn \| error	info	Minimum log level to display
`WATCH_POLL`	boolean	false	Use polling for file watching (Docker)

 .env 
 # Development-specific settings
ENABLE_HMR=true
DEBUG=true
LOG_LEVEL=debug
WATCH_POLL=true  # If HMR not working in Docker 

Feature flags

Optional features controlled via environment:

Variable	Type	Default	Description
`AMBIENT_EFFECTS_ENABLED`	boolean	false	Enable ambient visual effects
`AMBIENT_INTENSITY`	low \| medium \| high \| maximum	medium	Intensity of ambient effects
`ENABLE_ANALYTICS`	boolean	false	Enable analytics tracking
`ANALYTICS_ID`	string	-	Analytics provider tracking ID
`ENABLE_STEWARD`	boolean	true	Enable Steward chat interface

 .env 
 # Feature configuration
AMBIENT_EFFECTS_ENABLED=true
AMBIENT_INTENSITY=medium

ENABLE_ANALYTICS=true
ANALYTICS_ID=G-XXXXXXXXXX

ENABLE_STEWARD=true 

Performance variables

Variables affecting performance and resource usage:

Variable	Type	Default	Description
`NODE_OPTIONS`	string	-	Node.js CLI options
`BUILD_CONCURRENCY`	number	4	Parallel build workers
`VITE_BUILD_CHUNK_SIZE`	number (KB)	500	Chunk size warning limit

 .env.production 
 # Performance tuning
NODE_OPTIONS="--max-old-space-size=2048"
BUILD_CONCURRENCY=8
VITE_BUILD_CHUNK_SIZE=750 

Note: --max-old-space-size sets Node.js heap limit (MB). Increase if builds fail with out-of-memory errors.

Secret management

Variables containing sensitive data:

Security best practices:

Never commit .env.production to version control
Add .env*.local to .gitignore
Use different secrets per environment
Set file permissions: chmod 600 .env.production
Rotate secrets regularly (quarterly minimum)

 .env.production 
 # Example secret variables (production only)
API_KEY=your-api-key-here
DATABASE_URL=postgresql://user:password@host:5432/db
SESSION_SECRET=random-32-character-string
SENTRY_DSN=https://key@sentry.io/project 

Validating configuration

Check environment variables are set correctly:

 terminal 
 # View all environment variables
docker compose config

# Check specific variable
docker compose config | grep PUBLIC_DOMAIN

# Validate .env file syntax
cat .env | grep -v '^#' | grep -v '^$' | grep '='

# Test production configuration
docker compose -f docker-compose.yml -f docker-compose.prod.yml config 

Common validation errors:

Missing required variable

Error: PUBLIC_DOMAIN is not set

Solution: Add PUBLIC_DOMAIN=your-domain.com to .env

Invalid boolean value

Error: ENABLE_HMR must be true or false

Solution: Use lowercase true or false, not True or 1

Syntax error in .env file

Error: unexpected character

Solution: Check for spaces around =, quotes around values with spaces, missing line breaks

Complete examples

Full configuration examples for different environments:

Development environment

 .env 
 # .env - Development configuration
# Core settings
ATELIER_MODE=dev
NODE_ENV=development
PUBLIC_DOMAIN=localhost
COMPOSE_PROJECT_NAME=my-installation-dev

# Development features
ENABLE_HMR=true
DEBUG=true
LOG_LEVEL=debug
WATCH_POLL=false

# Features
AMBIENT_EFFECTS_ENABLED=true
AMBIENT_INTENSITY=medium
ENABLE_STEWARD=true

# Analytics (disabled in dev)
ENABLE_ANALYTICS=false

# Performance (relaxed in dev)
NODE_OPTIONS="--max-old-space-size=1024"
BUILD_CONCURRENCY=4 

Production environment

 .env.production 
 # .env.production - Production configuration
# Core settings
ATELIER_MODE=prod
NODE_ENV=production
PUBLIC_DOMAIN=my-installation.com
COMPOSE_PROJECT_NAME=my-installation-prod

# Development features (disabled)
ENABLE_HMR=false
DEBUG=false
LOG_LEVEL=warn

# Features
AMBIENT_EFFECTS_ENABLED=true
AMBIENT_INTENSITY=medium
ENABLE_STEWARD=true

# Analytics
ENABLE_ANALYTICS=true
ANALYTICS_ID=G-XXXXXXXXXX

# Performance (optimized for production)
NODE_OPTIONS="--max-old-space-size=2048"
BUILD_CONCURRENCY=8
VITE_BUILD_CHUNK_SIZE=750

# Secrets (not committed to git)
# API_KEY=your-api-key-here
# SESSION_SECRET=32-character-random-string 

Next steps

Environment configured. Related guides:

Deploy Locally

Use these variables in local development

Deploy to Production

Production-specific configuration

Caddy Configuration

Reverse proxy and HTTPS setup

Configuration Reference

Complete technical documentation