Environment Variables Reference

Complete reference of all environment variables used by Ignis framework.

Overview

Ignis uses the APP_ENV_ prefix for all framework-specific environment variables. This prevents conflicts with system variables like PATH, HOME, etc.

bash

# ✅ Ignis variables
APP_ENV_POSTGRES_HOST=localhost

# ❌ Might conflict with system
POSTGRES_HOST=localhost

Accessing Environment Variables

typescript

// Direct access
const host = process.env.APP_ENV_POSTGRES_HOST;

// Using applicationEnvironment helper (recommended)
import { applicationEnvironment, EnvironmentKeys } from '@venizia/ignis';
const host = applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_POSTGRES_HOST);

Quick Start Template

Create a .env file in your project root:

bash

# .env

# =====================
# APPLICATION
# =====================
APP_ENV_APPLICATION_NAME=my-app
APP_ENV_APPLICATION_TIMEZONE=UTC

# =====================
# SERVER
# =====================
APP_ENV_SERVER_HOST=0.0.0.0
APP_ENV_SERVER_PORT=3000
APP_ENV_SERVER_BASE_PATH=/api

# =====================
# DATABASE (PostgreSQL)
# =====================
APP_ENV_POSTGRES_HOST=localhost
APP_ENV_POSTGRES_PORT=5432
APP_ENV_POSTGRES_USERNAME=postgres
APP_ENV_POSTGRES_PASSWORD=your_password_here
APP_ENV_POSTGRES_DATABASE=my_database

# =====================
# AUTHENTICATION
# =====================
APP_ENV_APPLICATION_SECRET=generate-a-strong-random-secret
APP_ENV_JWT_SECRET=generate-another-strong-random-secret
APP_ENV_JWT_EXPIRES_IN=86400

# =====================
# LOGGING
# =====================
APP_ENV_LOGGER_FOLDER_PATH=./logs

Important: Add .env to your .gitignore to prevent committing secrets.

Application Variables

Variable	Required	Default	Description
`APP_ENV_APPLICATION_NAME`	No	`APP`	Application name, used in logs and identification
`APP_ENV_APPLICATION_TIMEZONE`	No	`Asia/Ho_Chi_Minh`	Default timezone for date operations
`APP_ENV_APPLICATION_ROLES`	No	-	Comma-separated list of application roles

Example

bash

APP_ENV_APPLICATION_NAME=ignis-backend
APP_ENV_APPLICATION_TIMEZONE=UTC
APP_ENV_APPLICATION_ROLES=api,worker

Server Variables

Variable	Required	Default	Description
`APP_ENV_SERVER_HOST`	No	`localhost`	Server bind address
`APP_ENV_SERVER_PORT`	No	`3000`	Server port
`APP_ENV_SERVER_BASE_PATH`	No	`/`	Base path for all routes
`HOST`	No	-	Alternative to `APP_ENV_SERVER_HOST`
`PORT`	No	-	Alternative to `APP_ENV_SERVER_PORT`

Example

bash

# Development
APP_ENV_SERVER_HOST=localhost
APP_ENV_SERVER_PORT=3000
APP_ENV_SERVER_BASE_PATH=/api

# Production
APP_ENV_SERVER_HOST=0.0.0.0
APP_ENV_SERVER_PORT=8080
APP_ENV_SERVER_BASE_PATH=/v1/api

Priority Order

The server configuration uses this priority:

Explicit config in appConfigs
APP_ENV_SERVER_* variables
HOST/PORT variables (for cloud platforms)
Default values

Database Variables (PostgreSQL)

Variable	Required	Default	Description
`APP_ENV_POSTGRES_HOST`	Yes*	`localhost`	Database host
`APP_ENV_POSTGRES_PORT`	No	`5432`	Database port
`APP_ENV_POSTGRES_USERNAME`	Yes*	`postgres`	Database username
`APP_ENV_POSTGRES_PASSWORD`	Yes*	-	Database password
`APP_ENV_POSTGRES_DATABASE`	Yes*	-	Database name
`APP_ENV_DATASOURCE_NAME`	No	-	DataSource identifier

*Required when using PostgreSQL DataSource.

Example

bash

# Local development
APP_ENV_POSTGRES_HOST=localhost
APP_ENV_POSTGRES_PORT=5432
APP_ENV_POSTGRES_USERNAME=postgres
APP_ENV_POSTGRES_PASSWORD=password
APP_ENV_POSTGRES_DATABASE=my_app_dev

# Production
APP_ENV_POSTGRES_HOST=db.example.com
APP_ENV_POSTGRES_PORT=5432
APP_ENV_POSTGRES_USERNAME=app_user
APP_ENV_POSTGRES_PASSWORD=strong_password_here
APP_ENV_POSTGRES_DATABASE=my_app_prod

DataSource Configuration

typescript

@datasource({ driver: 'node-postgres' })
export class PostgresDataSource extends BaseDataSource {
  constructor() {
    super({
      name: PostgresDataSource.name,
      config: {
        host: process.env.APP_ENV_POSTGRES_HOST ?? 'localhost',
        port: +(process.env.APP_ENV_POSTGRES_PORT ?? 5432),
        database: process.env.APP_ENV_POSTGRES_DATABASE ?? 'mydb',
        user: process.env.APP_ENV_POSTGRES_USERNAME ?? 'postgres',
        password: process.env.APP_ENV_POSTGRES_PASSWORD ?? '',
      },
    });
  }
}

Authentication Variables

Variable	Required	Default	Description
`APP_ENV_APPLICATION_SECRET`	Yes	-	Secret for encrypting JWT payload
`APP_ENV_JWT_SECRET`	Yes	-	Secret for signing JWT tokens
`APP_ENV_JWT_EXPIRES_IN`	No	`86400`	Token expiration in seconds (24h default)

Security Requirements

Both APP_ENV_APPLICATION_SECRET and APP_ENV_JWT_SECRET are mandatory when using the authentication component. The application will fail to start if these are missing or empty.

Generate Strong Secrets

bash

# Generate random secrets
openssl rand -base64 32  # For APP_ENV_APPLICATION_SECRET
openssl rand -base64 32  # For APP_ENV_JWT_SECRET

Example

bash

APP_ENV_APPLICATION_SECRET=K8sX2mP9qR4tV7wZ1aD3fG6hJ9kL2nO5
APP_ENV_JWT_SECRET=M3nB6vC9xZ2aS5dF8gH1jK4lP7oI0uY
APP_ENV_JWT_EXPIRES_IN=86400

Common Expiration Values

Value	Duration
`3600`	1 hour
`86400`	24 hours (1 day)
`604800`	7 days
`2592000`	30 days

Logging Variables

Variable	Required	Default	Description
`APP_ENV_LOGGER_FOLDER_PATH`	No	`./`	Directory for log files
`APP_ENV_LOGGER_DGRAM_HOST`	No	-	UDP log transport host
`APP_ENV_LOGGER_DGRAM_PORT`	No	-	UDP log transport port
`APP_ENV_LOGGER_DGRAM_LABEL`	No	-	Label for UDP logs
`APP_ENV_LOGGER_DGRAM_LEVELS`	No	-	Comma-separated log levels for UDP
`APP_ENV_EXTRA_LOG_ENVS`	No	-	Extra env vars to include in logs

Example

bash

# File logging
APP_ENV_LOGGER_FOLDER_PATH=./app_data/logs

# UDP logging (for log aggregators)
APP_ENV_LOGGER_DGRAM_HOST=127.0.0.1
APP_ENV_LOGGER_DGRAM_PORT=5000
APP_ENV_LOGGER_DGRAM_LABEL=my-app
APP_ENV_LOGGER_DGRAM_LEVELS=error,warn,info

Storage Variables (MinIO/S3)

Variable	Required	Default	Description
`APP_ENV_MINIO_HOST`	Yes*	-	MinIO/S3 endpoint
`APP_ENV_MINIO_API_PORT`	No	`9000`	MinIO API port
`APP_ENV_MINIO_ACCESS_KEY`	Yes*	-	Access key
`APP_ENV_MINIO_SECRET_KEY`	Yes*	-	Secret key
`APP_ENV_MINIO_USE_SSL`	No	`false`	Enable SSL

*Required when using StaticAsset component.

Example

bash

# Local MinIO
APP_ENV_MINIO_HOST=localhost
APP_ENV_MINIO_API_PORT=9000
APP_ENV_MINIO_ACCESS_KEY=minioadmin
APP_ENV_MINIO_SECRET_KEY=minioadmin
APP_ENV_MINIO_USE_SSL=false

# AWS S3
APP_ENV_MINIO_HOST=s3.amazonaws.com
APP_ENV_MINIO_API_PORT=443
APP_ENV_MINIO_ACCESS_KEY=AKIAIOSFODNN7EXAMPLE
APP_ENV_MINIO_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
APP_ENV_MINIO_USE_SSL=true

Mail Variables

Variable	Required	Default	Description
`APP_ENV_MAIL_HOST`	Yes*	`smtp.gmail.com`	SMTP host
`APP_ENV_MAIL_PORT`	No	`465`	SMTP port
`APP_ENV_MAIL_SECURE`	No	`true`	Use TLS
`APP_ENV_MAIL_USER`	Yes*	-	SMTP username/email
`APP_ENV_MAIL_CLIENT_ID`	Yes*	-	OAuth2 client ID
`APP_ENV_MAIL_CLIENT_SECRET`	Yes*	-	OAuth2 client secret
`APP_ENV_MAIL_REFRESH_TOKEN`	Yes*	-	OAuth2 refresh token

*Required when using Mail component with OAuth2.

Example (Gmail with OAuth2)

bash

APP_ENV_MAIL_HOST=smtp.gmail.com
APP_ENV_MAIL_PORT=465
APP_ENV_MAIL_SECURE=true
APP_ENV_MAIL_USER=your-email@gmail.com
APP_ENV_MAIL_CLIENT_ID=your-oauth2-client-id
APP_ENV_MAIL_CLIENT_SECRET=your-oauth2-client-secret
APP_ENV_MAIL_REFRESH_TOKEN=your-oauth2-refresh-token

DataSource Variables

Variable	Required	Default	Description
`APP_ENV_APPLICATION_DS_MIGRATION`	No	-	DataSource name for migrations
`APP_ENV_APPLICATION_DS_AUTHORIZE`	No	-	DataSource name for auth
`APP_ENV_APPLICATION_DS_OAUTH2`	No	-	DataSource name for OAuth2

Debug Variables

Variable	Required	Default	Description
`DEBUG`	No	-	Enable debug mode
`NODE_ENV`	No	`development`	Environment mode
`ALLOW_EMPTY_ENV_VALUE`	No	`false`	Allow empty env values

Example

bash

# Development
NODE_ENV=development
DEBUG=true

# Production
NODE_ENV=production

Environment-Specific Files

Create environment-specific .env files:

project/
├── .env                 # Default (development)
├── .env.local           # Local overrides (gitignored)
├── .env.production      # Production values
├── .env.test            # Test environment
└── .env.example         # Template for team (committed)

Loading Priority

.env.local (highest priority, gitignored)
.env.{NODE_ENV} (e.g., .env.production)
.env (default)

Custom Environment Prefix

You can customize the prefix from APP_ENV_ to something else:

typescript

// Set custom prefix
process.env.APPLICATION_ENV_PREFIX = 'MY_APP';

// Now use MY_APP_ prefix
// MY_APP_POSTGRES_HOST=localhost

Validation

Ignis validates APP_ENV_* variables on startup. Missing required variables will cause the application to fail with a clear error message.

Disable Validation

bash

# Allow empty env values (not recommended for production)
ALLOW_EMPTY_ENV_VALUE=true

Security Best Practices

Never commit .env files - Add to .gitignore
Use strong secrets - Generate with openssl rand -base64 32
Rotate secrets regularly - Especially JWT_SECRET
Use different values per environment - Don't reuse dev secrets in production
Use secret managers in production - AWS Secrets Manager, HashiCorp Vault, etc.

Complete .env.example

bash

# ===========================================
# IGNIS ENVIRONMENT VARIABLES
# ===========================================
# Copy this file to .env and fill in values

# APPLICATION
APP_ENV_APPLICATION_NAME=my-app
APP_ENV_APPLICATION_TIMEZONE=UTC

# SERVER
APP_ENV_SERVER_HOST=0.0.0.0
APP_ENV_SERVER_PORT=3000
APP_ENV_SERVER_BASE_PATH=/api

# DATABASE
APP_ENV_POSTGRES_HOST=localhost
APP_ENV_POSTGRES_PORT=5432
APP_ENV_POSTGRES_USERNAME=postgres
APP_ENV_POSTGRES_PASSWORD=
APP_ENV_POSTGRES_DATABASE=

# AUTHENTICATION (Required for auth component)
APP_ENV_APPLICATION_SECRET=
APP_ENV_JWT_SECRET=
APP_ENV_JWT_EXPIRES_IN=86400

# LOGGING
APP_ENV_LOGGER_FOLDER_PATH=./logs

# STORAGE (Optional - MinIO/S3)
# APP_ENV_MINIO_HOST=localhost
# APP_ENV_MINIO_API_PORT=9000
# APP_ENV_MINIO_ACCESS_KEY=
# APP_ENV_MINIO_SECRET_KEY=
# APP_ENV_MINIO_USE_SSL=false

# MAIL (Optional)
# APP_ENV_MAIL_HOST=smtp.gmail.com
# APP_ENV_MAIL_PORT=465
# APP_ENV_MAIL_USER=
# APP_ENV_MAIL_CLIENT_ID=
# APP_ENV_MAIL_CLIENT_SECRET=
# APP_ENV_MAIL_REFRESH_TOKEN=

Environment Variables Reference ​

Overview ​

Accessing Environment Variables ​

Quick Start Template ​

Application Variables ​

Example ​

Server Variables ​

Example ​

Priority Order ​

Database Variables (PostgreSQL) ​

Example ​

DataSource Configuration ​

Authentication Variables ​

Security Requirements ​

Generate Strong Secrets ​

Example ​

Common Expiration Values ​

Logging Variables ​

Example ​

Storage Variables (MinIO/S3) ​

Example ​

Mail Variables ​

Example (Gmail with OAuth2) ​

DataSource Variables ​

Debug Variables ​

Example ​

Environment-Specific Files ​

Loading Priority ​

Custom Environment Prefix ​

Validation ​

Disable Validation ​

Security Best Practices ​

Complete .env.example ​

Environment Variables Reference

Overview

Accessing Environment Variables

Quick Start Template

Application Variables

Example

Server Variables

Example

Priority Order

Database Variables (PostgreSQL)

Example

DataSource Configuration

Authentication Variables

Security Requirements

Generate Strong Secrets

Example

Common Expiration Values

Logging Variables

Example

Storage Variables (MinIO/S3)

Example

Mail Variables

Example (Gmail with OAuth2)

DataSource Variables

Debug Variables

Example

Environment-Specific Files

Loading Priority

Custom Environment Prefix

Validation

Disable Validation

Security Best Practices

Complete .env.example