Environment Documentation

This documentation explains Environment: Located at .env.example

Overview

This document provides a comprehensive guide to configuring the Compelete NestJS Boilerplate using environment variables. The project uses a .env file to store all configuration settings including database connections, authentication, AWS services, and other application settings.

All environment variables are validated using the AppEnvDto class to ensure required variables are present and properly formatted before the application starts.

Related Documents

• Configuration Documentation - For understanding how environment variables map to configurations
• Installation Documentation - For initial setup and environment file creation
• Database Documentation - For database connection details
• Authentication Documentation - For JWT and OAuth configuration

Table of Contents

• Overview
• Related Documents
• Environment Validation
• Example Configuration
• Environment Variables
  • Application Settings
  • Home/Organization Settings
  • HTTP Server Settings
  • Logging Settings
  • Middleware Settings
  • URL Versioning Settings
  • Database Settings
  • Authentication Settings
  • Social Authentication Settings
  • Two-Factor Authentication Settings
  • AWS Settings
  • Redis Settings
  • Debug Settings

Environment Validation

Environment variables are validated using the AppEnvDto class with class-validator decorators. This validation occurs in src/main.ts during application bootstrap:

 
// Validate environment variables
const classEnv = plainToInstance(AppEnvDto, process.env);
const errors = await validate(classEnv);
if (errors.length > 0) {
    const messageService = app.get(MessageService);
    const errorsMessage = messageService.setValidationMessage(errors);
    
    logger.error(
        `Env Variable Invalid: ${JSON.stringify(errorsMessage)}`,
        'NestApplication'
    );
    
    throw new Error('Env Variable Invalid', {
        cause: errorsMessage,
    });
}

The AppEnvDto class is located at src/app/dtos/app.env.dto.ts. If validation fails, the application will not start and will display detailed error messages showing which environment variables are missing or invalid.

Example Configuration

Below is an example .env file based on the current .env.example:

# Application Settings
APP_NAME=ACKNestJs
APP_ENV=local
APP_LANGUAGE=en
APP_TIMEZONE=Asia/Jakarta
 
# Home/Organization
HOME_URL=https://example.id
HOME_NAME=ACKNestJs
 
# HTTP Server
HTTP_HOST=localhost
HTTP_PORT=3000
 
# Logging
LOGGER_ENABLE=true
LOGGER_LEVEL=debug
LOGGER_INTO_FILE=true
LOGGER_PRETTIER=true
LOGGER_AUTO=false
 
# Middleware
MIDDLEWARE_CORS_ORIGIN=*
 
# URL Versioning
URL_VERSIONING_ENABLE=true
URL_VERSION=1
 
# Database
DATABASE_URL=mongodb://localhost:27017/ACKNestJs?retryWrites=true&w=majority&replicaSet=rs0
DATABASE_DEBUG=true
 
# JWT Authentication
AUTH_JWT_ISSUER=https://example.id
AUTH_JWT_AUDIENCE=ACKNestJs
 
# Access Token Configuration
AUTH_JWT_ACCESS_TOKEN_JWKS_URI=http://localhost:3011/.well-known/access-jwks.json
AUTH_JWT_ACCESS_TOKEN_KID=ack-access-2024-001
AUTH_JWT_ACCESS_TOKEN_PRIVATE_KEY=qwerty1234567890
AUTH_JWT_ACCESS_TOKEN_PUBLIC_KEY=qwerty1234567890
AUTH_JWT_ACCESS_TOKEN_EXPIRED=1h
 
# Refresh Token Configuration
AUTH_JWT_REFRESH_TOKEN_JWKS_URI=http://localhost:3011/.well-known/refresh-jwks.json
AUTH_JWT_REFRESH_TOKEN_KID=ack-refresh-2024-001
AUTH_JWT_REFRESH_TOKEN_PRIVATE_KEY=qwerty1234567890
AUTH_JWT_REFRESH_TOKEN_PUBLIC_KEY=qwerty1234567890
AUTH_JWT_REFRESH_TOKEN_EXPIRED=30d
 
# Social Authentication (Optional)
AUTH_SOCIAL_GOOGLE_CLIENT_ID=
AUTH_SOCIAL_GOOGLE_CLIENT_SECRET=
AUTH_SOCIAL_APPLE_CLIENT_ID=
AUTH_SOCIAL_APPLE_SIGN_IN_CLIENT_ID=
 
# AWS Configuration (Optional)
AWS_S3_CREDENTIAL_KEY=
AWS_S3_CREDENTIAL_SECRET=
AWS_S3_REGION=ap-southeast-3
AWS_S3_PUBLIC_BUCKET=
AWS_S3_PUBLIC_CDN=
AWS_S3_PRIVATE_BUCKET=
AWS_S3_PRIVATE_CDN=
AWS_SES_CREDENTIAL_KEY=
AWS_SES_CREDENTIAL_SECRET=
AWS_SES_REGION=ap-southeast-3
 
# Redis
CACHE_REDIS_URL=redis://localhost:6379/0
QUEUE_REDIS_URL=redis://localhost:6379/1
 
# Two-Factor Authentication
AUTH_TWO_FACTOR_ISSUER=COMPLETE
AUTH_TWO_FACTOR_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef
 
# Debug (Optional)
SENTRY_DSN=

Environment Variables

All environment variables are validated using the AppEnvDto class to ensure required variables are present and properly formatted. Below is a detailed explanation of each variable:

Application Settings

APP_NAME (required)
The name of your application. Used throughout the system for identification.

APP_NAME=CompleteNestJsBoilerplate

APP_ENV (required)
The environment the application is running in. Possible values: development, staging, production, local

APP_ENV=local

APP_LANGUAGE (required)
Default language for the application. Supported: en, id

APP_LANGUAGE=en

APP_TIMEZONE (required)
Default timezone for date operations. Example: Asia/Jakarta, UTC

APP_TIMEZONE=Europe/Paris

Home/Organization Settings

HOME_NAME (required)
Display name for your organization/home page.

HOME_NAME=CompleteNestJsBoilerplate

HOME_URL (required)
URL for your home/landing page.

HOME_URL=https://example.id

HTTP Server Settings

HTTP_HOST (required)
Host/IP address for the HTTP server.

HTTP_HOST=localhost

HTTP_PORT (required)
Port number for the HTTP server.

HTTP_PORT=3000

Logging Settings

LOGGER_ENABLE (required)
Enable or disable application logging.

LOGGER_ENABLE=true

LOGGER_LEVEL (required)
Logging level using Pino logger. Options: silent, trace, debug, info, warn, error, fatal

LOGGER_LEVEL=debug

LOGGER_INTO_FILE (required)
Whether to write logs to files.

LOGGER_INTO_FILE=true

LOGGER_PRETTIER (required)
Whether to format logs in a prettier, readable way.

LOGGER_PRETTIER=true

LOGGER_AUTO (required)
Enable automatic logging features.

LOGGER_AUTO=false

Middleware Settings

MIDDLEWARE_CORS_ORIGIN (required)
Comma-separated list of allowed CORS origins. Supports subdomain wildcards but not port wildcards.

Examples:

# Allow all origins (development only)
MIDDLEWARE_CORS_ORIGIN=*
 
# Specific origins
MIDDLEWARE_CORS_ORIGIN=example.com,app.example.com
 
# Subdomain wildcard (supported)
MIDDLEWARE_CORS_ORIGIN=*.example.com,api.myapp.com
 
# Multiple domains with subdomains
MIDDLEWARE_CORS_ORIGIN=*.example.com,*.myapp.com,localhost:3000

Note: While subdomain wildcards (*.example.com) are supported, port wildcards (example.com:*) are not supported. Specify exact ports when needed.

URL Versioning Settings

URL_VERSIONING_ENABLE (required)
Enable URL versioning for your API (e.g., /api/v1/users).

URL_VERSIONING_ENABLE=true

URL_VERSION (required)
Default API version number.

URL_VERSION=1

Database Settings

DATABASE_URL (required)
MongoDB connection string. Must include replica set for transactions.

# Local MongoDB with replica set
DATABASE_URL=mongodb://localhost:27017/CompleteNestJsBoilerplate?retryWrites=true&w=majority&replicaSet=rs0
 
# MongoDB Atlas example
# DATABASE_URL=mongodb+srv://username:password@cluster.mongodb.net/CompleteNestJsBoilerplate

DATABASE_DEBUG (required)
Enable database debug mode to log all queries.

DATABASE_DEBUG=true

Authentication Settings

AUTH_JWT_ISSUER (required)
JWT issuer claim value (usually your domain).

AUTH_JWT_ISSUER=https://example.id

AUTH_JWT_AUDIENCE (required)
JWT audience claim value (usually your application name).

AUTH_JWT_AUDIENCE=ACKNestJs

Access Token Settings

AUTH_JWT_ACCESS_TOKEN_JWKS_URI (required)
Public URI where access token JWKS is hosted.

AUTH_JWT_ACCESS_TOKEN_JWKS_URI=http://localhost:3011/.well-known/access-jwks.json

AUTH_JWT_ACCESS_TOKEN_KID (required)
Key ID for access token. Generated automatically by pnpm generate:keys.

AUTH_JWT_ACCESS_TOKEN_KID=complete-access-2024-001

AUTH_JWT_ACCESS_TOKEN_PRIVATE_KEY (required)
Private key content for signing access tokens.

AUTH_JWT_ACCESS_TOKEN_PRIVATE_KEY=qwerty1234567890

AUTH_JWT_ACCESS_TOKEN_PUBLIC_KEY (required)
Public key content for verifying access tokens.

AUTH_JWT_ACCESS_TOKEN_PUBLIC_KEY=qwerty1234567890

AUTH_JWT_ACCESS_TOKEN_EXPIRED (required)
Access token expiration time. Format: 1h, 30m, 2d

AUTH_JWT_ACCESS_TOKEN_EXPIRED=1h

Refresh Token Settings

AUTH_JWT_REFRESH_TOKEN_JWKS_URI (required)
Public URI where refresh token JWKS is hosted.

AUTH_JWT_REFRESH_TOKEN_JWKS_URI=http://localhost:3011/.well-known/refresh-jwks.json

AUTH_JWT_REFRESH_TOKEN_KID (required)
Key ID for refresh token. Generated automatically by pnpm generate:keys.

AUTH_JWT_REFRESH_TOKEN_KID=compelete-refresh-2024-001

AUTH_JWT_REFRESH_TOKEN_PRIVATE_KEY (required)
Private key content for signing refresh tokens.

AUTH_JWT_REFRESH_TOKEN_PRIVATE_KEY=qwerty1234567890

AUTH_JWT_REFRESH_TOKEN_PUBLIC_KEY (required)
Public key content for verifying refresh tokens.

AUTH_JWT_REFRESH_TOKEN_PUBLIC_KEY=qwerty1234567890

AUTH_JWT_REFRESH_TOKEN_EXPIRED (required)
Refresh token expiration time. Format: 7d, 30d, 90d

AUTH_JWT_REFRESH_TOKEN_EXPIRED=30d

Social Authentication Settings

Note: All social authentication settings are optional. Leave empty if not using social login.

AUTH_SOCIAL_GOOGLE_CLIENT_ID (optional)
Google OAuth client ID.

AUTH_SOCIAL_GOOGLE_CLIENT_ID=

AUTH_SOCIAL_GOOGLE_CLIENT_SECRET (optional)
Google OAuth client secret.

AUTH_SOCIAL_GOOGLE_CLIENT_SECRET=

AUTH_SOCIAL_APPLE_CLIENT_ID (optional)
Apple OAuth client ID.

AUTH_SOCIAL_APPLE_CLIENT_ID=

AUTH_SOCIAL_APPLE_SIGN_IN_CLIENT_ID (optional)
Apple Sign In client ID.

AUTH_SOCIAL_APPLE_SIGN_IN_CLIENT_ID=

Two-Factor Authentication Settings

AUTH_TWO_FACTOR_ISSUER (optional)
Issuer name displayed in authenticator apps.

AUTH_TWO_FACTOR_ISSUER=ACK

AUTH_TWO_FACTOR_ENCRYPTION_KEY (required for 2FA)
Secret used to derive an AES-256 key for encrypting TOTP secrets (recommended 32+ chars).

AUTH_TWO_FACTOR_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef

AWS Settings

Note: AWS settings are optional by default. However, if you want to test file uploads (S3) or email functionality (SES), these become required for those specific features to work.

S3 Configuration

AWS_S3_CREDENTIAL_KEY (optional/required for file uploads)
AWS access key for S3 bucket operations.

AWS_S3_CREDENTIAL_KEY=

AWS_S3_CREDENTIAL_SECRET (optional/required for file uploads)
AWS secret key for S3 bucket operations.

AWS_S3_CREDENTIAL_SECRET=

AWS_S3_REGION (optional/required for file uploads)
AWS region for S3 services.

AWS_S3_REGION=ap-southeast-3

AWS_S3_PUBLIC_BUCKET (optional/required for file uploads)
Name of the public S3 bucket for file storage.

AWS_S3_PUBLIC_BUCKET=

AWS_S3_PUBLIC_CDN (optional)
CloudFront CDN URL for public bucket.

AWS_S3_PUBLIC_CDN=

S3 Private Bucket (for private files)

AWS_S3_PRIVATE_BUCKET (optional/required for private file uploads)
Name of the private S3 bucket for secure file storage.

AWS_S3_PRIVATE_BUCKET=

AWS_S3_PRIVATE_CDN (optional)
CloudFront CDN URL for private bucket.

AWS_S3_PRIVATE_CDN=

SES (Email Service)

AWS_SES_CREDENTIAL_KEY (optional/required for email features)
AWS access key for SES email service.

AWS_SES_CREDENTIAL_KEY=

AWS_SES_CREDENTIAL_SECRET (optional/required for email features)
AWS secret key for SES email service.

AWS_SES_CREDENTIAL_SECRET=

AWS_SES_REGION (optional/required for email features)
AWS region for SES service.

AWS_SES_REGION=ap-southeast-3

Redis Settings

CACHE_REDIS_URL (required)
Redis URL for caching operations.

CACHE_REDIS_URL=redis://localhost:6379/0

QUEUE_REDIS_URL (required)
Redis URL for queue operations (background jobs).

QUEUE_REDIS_URL=redis://localhost:6379/1

Debug Settings

SENTRY_DSN (optional)
Sentry DSN for error tracking and monitoring.

SENTRY_DSN=