Environment Configuration (.env)

Last modified: 3/26/2026

Environment Configuration (.env)

ngdpbase uses a two-file configuration model: a bootstrap .env in the project root that tells the server where data lives, and a full instance config (app-custom-config.json) inside the data directory that controls how the platform behaves.

The Bootstrap .env File

Location: project root (.env) — gitignored, never committed
Purpose: tells server.sh and PM2 where to find data before the app starts
Template: .env.example in the project root

Minimum Required Content

FAST_STORAGE=/path/to/fast/data
SLOW_STORAGE=/path/to/slow/data

Without this file server.sh falls back to ./data for both paths and shows the install page.

All Supported Variables

VariableDefaultDescription
FAST_STORAGE./dataOperational data directory — sessions, logs, users, search index, config. Use fast storage (SSD).
SLOW_STORAGE./dataBulk content directory — pages, attachments, backups. Can be a NAS or large drive.
NODE_ENVdevelopmentRuntime environment: development, production, test, staging
PORT3000HTTP port the server listens on
PM2_MAX_MEMORY4GMaximum memory before PM2 restarts the process. Large instances (14K+ pages) spike to ~3 GB during search index rebuilds — keep at 4G or higher.
HEADLESS_INSTALL*(unset)*Set to true for Docker/Kubernetes automated deployment — skips the setup wizard entirely
INSTANCE_DATA_FOLDER*(deprecated)*Legacy alias for FAST_STORAGE — use FAST_STORAGE instead
INSTANCE_CONFIG_FILEapp-custom-config.jsonName of the config file to load from ${FAST_STORAGE}/config/

Two-Tier Storage

ngdpbase splits data across two storage locations to allow operational data (frequent small reads/writes) to live on fast storage while bulk content lives on cheaper or larger storage.

TierVariableWhat lives here
**Fast**FAST_STORAGESessions, logs, users, search index, config, .install-complete, page-index.json
**Slow**SLOW_STORAGEPages (content), attachments, backups

For single-drive setups, set both to the same path — or leave the defaults (./data).

Example: Single Drive

FAST_STORAGE=./data
SLOW_STORAGE=./data

Example: Two Local Drives

FAST_STORAGE=/mnt/ssd/ngdpbase/data
SLOW_STORAGE=/mnt/hdd/ngdpbase/data

Example: SSD + NAS

FAST_STORAGE=/mnt/ssd/ngdpbase/data
SLOW_STORAGE=/mnt/nas/ngdpbase

The Instance Config File

The full per-instance configuration lives at ${FAST_STORAGE}/config/app-custom-config.json.

During headless installation, this file is seeded from config/app-custom-config.example.

How server.sh Uses .env

server.sh sources .env before starting PM2, making FAST_STORAGE, SLOW_STORAGE, and other variables available to the Node.js process as environment variables. Configuration values in JSON config files can reference these as ${FAST_STORAGE} and ${SLOW_STORAGE}.

# server.sh sources .env, then starts PM2
./server.sh start      # production
./server.sh start dev  # development
./server.sh status     # shows resolved env paths
./server.sh env        # shows all environment and config values

See Server Management for full server.sh usage.

Headless / Docker Deployment

Set HEADLESS_INSTALL=true in .env (or as a container environment variable) to skip the setup wizard entirely. The server will:

  1. Copy config/*.example files to ${FAST_STORAGE}/config/ (if not already present)
  2. Copy required-pages/ to the pages directory (if empty)
  3. Create the .install-complete marker
  4. Start normally with the default admin credentials (admin / admin123)

The admin password should be changed immediately after first login.