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
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 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: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) |
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 |
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 |
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.