> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mayekun.com/llms.txt
> Use this file to discover all available pages before exploring further.

# NodeForgeCMS Environment Variables Configuration Guide

> Set up your NodeForgeCMS server environment: configure database credentials, JWT secrets, Redis connection, and email settings before deploying.

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:

```bash theme={null}
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:

```ini theme={null}
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:

```sql theme={null}
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.

```ini theme={null}
JWT_SECRET=your_long_random_secret
```

<Warning>
  **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:

  ```bash theme={null}
  openssl rand -hex 32
  ```

  Never commit this value to source control.
</Warning>

***

## Redis (7.x)

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

```ini theme={null}
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.

```ini theme={null}
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.

```ini theme={null}
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)                      |

<Note>
  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.
</Note>

### Supported Email Services

The `USER_EMAIL_SERVICE` variable is passed directly to [Nodemailer's well-known services](https://nodemailer.com/smtp/well-known/) list. Supported values include:

| Value        | Provider                                                                                        |
| ------------ | ----------------------------------------------------------------------------------------------- |
| `QQ`         | QQ Mail (default for China-hosted deployments)                                                  |
| `Gmail`      | Google Gmail (may require an [App Password](https://support.google.com/accounts/answer/185833)) |
| `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.