Environment variables

Reference for all environment variables required to run the SPS School Backend.

The SPS School Backend uses dotenv to load environment variables from a .env file in the project root. This page documents every variable the application reads, how to set secure values, and best practices for different environments.

How environment variables are loaded

At startup, server.js calls dotenv.config() before any other application code runs. This populates process.env with the values from your .env file. If a variable is missing, the relevant feature will fail at runtime — not at startup — so it is important to validate your configuration before deploying.

Variables defined in the shell environment take precedence over values in .env. This lets you override settings in CI/CD pipelines and container environments without modifying the file.

Required variables

body.PORT · number · required

The TCP port on which the Express HTTP server listens.

The server reads this value in server.js via app.listen(process.env.PORT, ...). If PORT is not set, process.env.PORT is undefined and Node.js will choose a random available port, which is rarely the intended behavior.

Example: PORT=5000

Common choices are 3000, 4000, 5000, or 8080 for local development. In hosted environments (Heroku, Railway, Render), the platform injects PORT automatically — do not hard-code it.

body.MONGODB_URI · string · required

The MongoDB connection string passed to Mongoose in config/db.js.

Mongoose uses this URI to establish and maintain the database connection. The URI encodes the host, port, authentication credentials, and target database name.

Local example:

MONGODB_URI=mongodb://localhost:27017/sps-school

MongoDB Atlas example:

MONGODB_URI=mongodb+srv://myuser:[e-mail]/sps-school?retryWrites=true&w=majority

Atlas connection strings contain your database username and password. Never commit a .env file containing a real MONGODB_URI to version control.

body.JWT_SECRET · string · required

The secret key used to sign and verify JSON Web Tokens in authController.js and authMiddleware.js.

When a user logs in, the server signs a JWT with this secret. On subsequent authenticated requests, the middleware verifies the token’s signature using the same secret. If the secret changes, all previously issued tokens become invalid and users must log in again.

Example:

JWT_SECRET=3f8a2c1d9e6b4a7f0c5d2e8b1a4f7c9d3e6b2a8f1c4d7e0b3a6f9c2d5e8b1a4

See generating a strong JWT secret below for instructions.

Use a different JWT_SECRET in every environment (development, staging, production). A secret that leaks from a development machine must not be able to forge tokens in production.

Generating a strong JWT secret

A JWT secret should be at least 32 bytes of cryptographically random data. Use one of the following methods to generate one:

openssl

openssl rand -hex 64

This outputs 64 hex characters (32 bytes of entropy). Copy the output directly into your .env file.

Node.js crypto

node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

Run this from your terminal (Node.js must be installed). The output is 128 hex characters (64 bytes of entropy).

Node.js REPL

// Open the Node.js REPL with: node
require('crypto').randomBytes(64).toString('base64')
// Copy the printed string into JWT_SECRET

Base64 encoding produces a slightly shorter string for the same entropy.

Prefer base64url or hex over dictionary words or passphrases. JWT secrets are never shown to users, so memorability is not a requirement — only entropy matters.

Complete .env template

Create a .env file in the project root with the following structure. Replace all placeholder values before starting the server.

.env

# -----------------------------------------------
# SPS School Backend — environment configuration
# -----------------------------------------------
# Do NOT commit this file to version control.
# Add .env to your .gitignore file.

# Server
PORT=5000

# Database
# Local MongoDB:
MONGODB_URI=mongodb://localhost:27017/sps-school
# MongoDB Atlas (uncomment and fill in your credentials):
# MONGODB_URI=mongodb+srv://<username>:<password>@cluster0.abcde.mongodb.net/sps-school?retryWrites=true&w=majority

# Authentication
# Generate with: openssl rand -hex 64
JWT_SECRET=replace-this-with-a-long-random-secret

Keeping .env out of version control

Committing a .env file with real credentials to a public or shared repository is a common source of credential leaks. Always add .env to .gitignore.

Ensure your .gitignore includes:

.gitignore

# Environment variables
.env
.env.local
.env.*.local

If you accidentally committed a .env file in the past, rotate every secret it contained (generate a new JWT_SECRET, rotate your MongoDB credentials) and remove it from the git history using git filter-repo or BFG Repo Cleaner.

Commit a .env.example file instead — a copy of the template with all values replaced by safe placeholders:

.env.example

PORT=5000
MONGODB_URI=mongodb://localhost:27017/sps-school
JWT_SECRET=replace-with-random-secret

This file is safe to commit and gives new developers a clear picture of required configuration without exposing real secrets.

Environment-specific configuration

Development

• Use a local MongoDB instance to keep development data isolated from staging and production.
• Any value works for JWT_SECRET locally, but use a randomly generated one so you catch token-related issues early.
• Set PORT to whatever is free on your machine (5000 is the default).

PORT=5000
MONGODB_URI=mongodb://localhost:27017/sps-school-dev
JWT_SECRET=dev-only-secret-do-not-reuse

Staging

• Use a separate MongoDB database or Atlas cluster from production.
• Generate a unique JWT_SECRET — do not share it with the production secret.
• If your staging environment is publicly accessible, treat its credentials with the same care as production.

PORT=5000
MONGODB_URI=mongodb+srv://staging-user:[e-mail]/sps-school-staging
JWT_SECRET=<randomly-generated-staging-secret>

Production

• Inject environment variables through your hosting platform’s secrets manager rather than a .env file on disk. Most platforms (Heroku, Railway, Render, AWS ECS, Kubernetes) support this natively.
• Enable MongoDB Atlas IP allowlisting and restrict access to your server’s IP range.
• Rotate JWT_SECRET periodically. Note that rotation invalidates all active sessions.
• Set PORT only if the platform does not inject it automatically.

Never store production secrets in a .env file inside a Docker image, a git repository, or a shared file system.

Variable summary

Variable	Required	Default	Description
PORT	Yes	—	HTTP server listen port
MONGODB_URI	Yes	—	MongoDB connection string
JWT_SECRET	Yes	—	Secret for signing JWTs