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

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.

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.

• Created automatically during the Installation Wizard on first run
• Overrides any key from config/app-default-config.json
• Gitignored — specific to this deployment
• Loaded last in the configuration chain (see Configuration Properties Reference for the full loading order)

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.