NodeForgeCMS Environment Variables Configuration Guide

All runtime configuration for NodeForgeCMS lives in a single .env file inside the server/ directory. This file controls how the Node.js backend connects to MySQL and Redis, how it signs authentication tokens, what domain it serves assets from, and how it dispatches email. Getting these values right before your first deployment is essential — misconfigured variables are the most common source of startup failures.

Create the Environment File

The repository ships with a fully annotated example file. Start by copying it:

cp server/.env.example server/.env

Then open server/.env in your editor and fill in the values for your environment. The sections below explain every variable group.

Database (MySQL 8.x)

NodeForgeCMS requires MySQL 8.x. Configure the connection to match your MySQL instance:

DATABASE_USERNAME=root
DATABASE_PASSWORD=your_password
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306
DATABASE_DB=node_forge_cms

Variable	Description
`DATABASE_USERNAME`	MySQL user with full privileges on the CMS database
`DATABASE_PASSWORD`	Password for the MySQL user
`DATABASE_HOST`	Hostname or IP of the MySQL server (`127.0.0.1` for local)
`DATABASE_PORT`	MySQL port (default: `3306`)
`DATABASE_DB`	Name of the database to use (create it before first run)

Create the database if it doesn’t already exist:

CREATE DATABASE node_forge_cms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Authentication

NodeForgeCMS uses JSON Web Tokens (JWT) to authenticate admin sessions. The secret is used to sign and verify every token issued by the server.

JWT_SECRET=your_long_random_secret

Use a strong, randomly generated secret in production. A weak or guessable JWT_SECRET puts every admin session at risk. Generate a value with at least 32 random characters — for example, using OpenSSL:

openssl rand -hex 32

Never commit this value to source control.

Redis (7.x)

NodeForgeCMS uses Redis for session caching and queue management. Redis 7.x is required.

REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_USERNAME=
REDIS_PASSWORD=
REDIS_DB=5

Variable	Description
`REDIS_HOST`	Hostname or IP of the Redis server
`REDIS_PORT`	Redis port (default: `6379`)
`REDIS_USERNAME`	Redis ACL username — leave blank if not using ACLs
`REDIS_PASSWORD`	Redis password — leave blank if authentication is disabled
`REDIS_DB`	Logical database index (default: `5`, avoids conflicts with other apps)

If you’re running Redis locally without authentication, you can leave REDIS_USERNAME and REDIS_PASSWORD empty.

Server

These variables tell NodeForgeCMS what public-facing URL it is running on. They are used to generate absolute links, redirect URLs, and asset paths.

SERVER_HOST=https://yourdomain.com
IMG_HOST=https://yourdomain.com

Variable	Description
`SERVER_HOST`	The public base URL of your site, including scheme and domain (no trailing slash)
`IMG_HOST`	The base URL used to prefix uploaded image paths — usually the same as `SERVER_HOST`

Set these to your actual production domain before deploying. If you’re using separate subdomains, SERVER_HOST should point to your main domain and IMG_HOST to wherever /uploads is served from.

Email (Optional)

NodeForgeCMS can send outbound email for contact form submissions and notifications. Email configuration is optional but required if you want contact form functionality to work.

FORM_USER_EMAIL=noreply@yourdomain.com
FORM_USER_EMAIL_PASSWORD=your_email_password
USER_EMAIL_SERVICE=QQ

Variable	Description
`FORM_USER_EMAIL`	The “from” address used for all outbound emails
`FORM_USER_EMAIL_PASSWORD`	The password or app-specific password for the email account
`USER_EMAIL_SERVICE`	The email service provider (see below)

Email settings are optional. If you leave them blank, the CMS will start normally but contact form submissions will not be delivered. Configure these values if your site uses the built-in contact form.

Supported Email Services

The USER_EMAIL_SERVICE variable is passed directly to Nodemailer’s well-known services list. Supported values include:

Value	Provider
`QQ`	QQ Mail (default for China-hosted deployments)
`Gmail`	Google Gmail (may require an App Password)
`Outlook365`	Microsoft Outlook / Office 365
`Yahoo`	Yahoo Mail
`Hotmail`	Microsoft Hotmail

Set USER_EMAIL_SERVICE to the string that matches your provider. If your provider isn’t in the well-known list, you can configure a custom SMTP transport — refer to the Nodemailer documentation for advanced SMTP options.

Get Started

Core Concepts

Guides

Deployment

Help

NodeForgeCMS Environment Variables Configuration Guide

Create the Environment File

Database (MySQL 8.x)

Authentication

Redis (7.x)

Server

Email (Optional)

Supported Email Services

​Create the Environment File

​Database (MySQL 8.x)

​Authentication

​Redis (7.x)

​Server

​Email (Optional)

​Supported Email Services

Create the Environment File

Database (MySQL 8.x)

Authentication

Redis (7.x)

Server

Email (Optional)

Supported Email Services