Configuration Reference

How IGNIS applications read configuration - the APP_ENV_ variable convention, the EnvironmentKeys constants, and where to look up every value.

Quick Reference

Category	Purpose	Key Variables
Application	App identity and timezone	`APP_ENV_APPLICATION_NAME`, `APP_ENV_APPLICATION_TIMEZONE`
Server	HTTP server settings	`APP_ENV_SERVER_HOST`, `APP_ENV_SERVER_PORT`
Database	PostgreSQL connection	`APP_ENV_POSTGRES_HOST`, `APP_ENV_POSTGRES_DATABASE`
Authentication	JWT tokens and secrets	`APP_ENV_JWT_SECRET`, `APP_ENV_APPLICATION_SECRET`
Logging	Log file paths and transports	`APP_ENV_LOGGER_FOLDER_PATH`
Storage	MinIO/S3 file storage (application-level convention)	`APP_ENV_MINIO_HOST`, `APP_ENV_MINIO_ACCESS_KEY`
Mail	SMTP email sending (application-level convention)	`APP_ENV_MAIL_HOST`, `APP_ENV_MAIL_USER`

Full list: Environment Variables Reference - every APP_ENV_* variable, its default, and whether it's required.

In one example

IGNIS uses the APP_ENV_ prefix to avoid conflicts with system variables. Create a .env file in your project root:

bash

# ✅ IGNIS variables
APP_ENV_POSTGRES_HOST=localhost

# ❌ Might conflict with system variables
POSTGRES_HOST=localhost

bash

# .env
APP_ENV_APPLICATION_NAME=my-app
APP_ENV_SERVER_HOST=0.0.0.0
APP_ENV_SERVER_PORT=3000
APP_ENV_POSTGRES_HOST=localhost
APP_ENV_POSTGRES_DATABASE=my_database

Read a value either directly or through the applicationEnvironment helper:

typescript

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

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

How it works

One prefix, layered files. Everything IGNIS reads is prefixed APP_ENV_ (configurable - see the Environment Variables Reference). Layer .env, .env.local, and .env.{NODE_ENV} the same way any dotenv-based tool does.
applicationEnvironment snapshots process.env once at import. It's built from whatever is in process.env when @venizia/ignis-helpers loads.
Late values need an explicit merge. A value set programmatically at runtime, after that snapshot, won't appear in .keys() unless merged in - secret hydration does this, see below.
Empty values are allowed by default. The emptiness check is skipped entirely unless you set ALLOW_EMPTY_ENV_VALUE to false or 0. The startup banner prints Empty values: ALLOWED (default).
Turn it on and it checks emptiness, not absence. With the check on, IGNIS iterates every APP_ENV_* key that IS set and throws if its value is empty. It never requires a variable to exist at all.
Per-component checks are separate. Component-level checks still cover values that must be present, for example the authentication component's jwtSecret check.
Secrets don't have to live in a file. IGNIS can hydrate APP_ENV_* keys from a vault at boot, before datasources are configured - see Secrets & Vault.

Common tasks

Access a variable in code

Prefer applicationEnvironment.get() over process.env directly - it stays in sync when secrets are hydrated from a vault.

typescript

import { applicationEnvironment } from '@venizia/ignis-helpers';
import { EnvironmentKeys } from '@venizia/ignis';

const dbHost = applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_POSTGRES_HOST);

Add a per-environment file

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

Reject empty values at startup

bash

ALLOW_EMPTY_ENV_VALUE=false

false and 0 turn the check ON. Leaving the variable unset, or setting it to true, keeps the default: empty values pass. See Validation.

Look up every variable's default and requirement

See the Environment Variables Reference for the full table, grouped by Application, Server, Database, Authentication, Logging, Storage, Mail, and Secrets & Vault.

Reference

EnvironmentKeys class

typescript

import { EnvironmentKeys } from '@venizia/ignis';

The column that matters is the last one: a constant marked no is a naming convention for your own code, and setting it changes nothing in IGNIS.

Constant	Description	Read by IGNIS
`APP_ENV_APPLICATION_NAME`	Application display name	yes - `AppConstants.APPLICATION_NAME`, startup banner
`APP_ENV_APPLICATION_TIMEZONE`	Application timezone (for example `'Asia/Ho_Chi_Minh'`)	yes - startup banner only; date work takes its zone from `TemporalHelper`
`APP_ENV_LOGGER_FOLDER_PATH`	Log file output directory	yes - enables rotating file logs
`APP_ENV_SERVER_HOST`	HTTP server host (e.g., `'0.0.0.0'`)	yes - fallback when `configs.host` is absent
`APP_ENV_SERVER_PORT`	HTTP server port (e.g., `3000`)	yes - fallback when `configs.port` is absent
`APP_ENV_APPLICATION_SECRET`	Application-wide secret key	no
`APP_ENV_APPLICATION_ROLES`	Application role definitions	no
`APP_ENV_JWT_SECRET`	JWT signing secret	no
`APP_ENV_JWT_EXPIRES_IN`	JWT token expiration	no
`APP_ENV_SERVER_BASE_PATH`	Base URL path prefix	no - `configs.path.base` is the real setting
`APP_ENV_POSTGRES_HOST`	PostgreSQL host	no
`APP_ENV_POSTGRES_PORT`	PostgreSQL port	no
`APP_ENV_POSTGRES_USERNAME`	PostgreSQL username	no
`APP_ENV_POSTGRES_PASSWORD`	PostgreSQL password	no
`APP_ENV_POSTGRES_DATABASE`	PostgreSQL database name	no

The logger reads a further set of APP_ENV_LOGGER_* names that EnvironmentKeys does not declare - see Environment variables.

APPLICATION_ENV_PREFIX and ALLOW_EMPTY_ENV_VALUE are deliberately absent from the class. Neither carries the APP_ENV prefix, so applicationEnvironment never holds them - both are bootstrap variables read straight off process.env.

Configuration Reference ​

Quick Reference ​

In one example ​

How it works ​

Common tasks ​

Access a variable in code ​

Add a per-environment file ​

Reject empty values at startup ​

Look up every variable's default and requirement ​

Reference ​

EnvironmentKeys class ​

See also ​

Configuration Reference

Quick Reference

In one example

How it works

Common tasks

Access a variable in code

Add a per-environment file

Reject empty values at startup

Look up every variable's default and requirement

Reference

EnvironmentKeys class

See also