Skip to main content

​
Overview

BillBuddy uses environment variables to configure the application’s runtime behavior. All environment variables should be defined in a .env file in the backend directory.
Never commit your .env file to version control. The .gitignore file is already configured to exclude it.

​
Creating the Environment File

Create a .env file in the backend directory of your BillBuddy installation: 
touch backend/.env

​
Required Variables

The following environment variables are required for BillBuddy to function properly:
​
PORT
number
default:"5000"
The port number on which the Express server will listen for incoming requests.
PORT=5000
​
MONGODB_URI
string
required
MongoDB connection string for database connectivity. Supports both local and cloud MongoDB instances.Local MongoDB:
MONGODB_URI=mongodb://localhost:27017/billbuddy
MongoDB Atlas:
MONGODB_URI=mongodb+srv://username:[email protected]/billbuddy?retryWrites=true&w=majority
​
JWT_SECRET
string
required
Secret key used for signing and verifying JSON Web Tokens (JWT) for user authentication.
Use a strong, randomly generated string. Never use a predictable value in production.
JWT_SECRET=your_secure_random_jwt_secret_key_here
Generating a secure secret:
node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
​
WEB3FORMS_ACCESS_KEY
string
required
Access key for Web3Forms email service used to send settlement summaries to users.
WEB3FORMS_ACCESS_KEY=your_web3forms_access_key
Get your access key from Web3Forms

​
Complete Example

Here’s a complete example .env file with all required variables: 
# Server Configuration
PORT=5000

# Database
MONGDB_URI=mongodb://localhost:27017/billbuddy

# Authentication
JWT_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

# Email Service
WEB3FORMS_ACCESS_KEY=your_web3forms_access_key_here

​
Environment-Specific Configuration

​
Development

For local development, use the following configuration: 
PORT=5000
MONGDB_URI=mongodb://localhost:27017/billbuddy-dev
JWT_SECRET=dev_secret_key_change_in_production
WEB3FORMS_ACCESS_KEY=your_access_key

​
Production

In production, ensure all secrets are strong and never exposed in logs or error messages.
For production deployment, use: 
PORT=5000
MONGDB_URI=mongodb+srv://user:[email protected]/billbuddy
JWT_SECRET=<strong-random-generated-secret>
WEB3FORMS_ACCESS_KEY=<production-access-key>

​
Loading Environment Variables

BillBuddy uses the dotenv package to load environment variables. The configuration is automatically loaded in server.js:
backend/server.js
const dotenv = require('dotenv');

// Load environment variables
dotenv.config();

​
Accessing Variables in Code

Environment variables are accessed throughout the application using process.env: 
const PORT = process.env.PORT || 5000;
const mongoUri = process.env.MONGODB_URI;
const jwtSecret = process.env.JWT_SECRET;

​
Validation

To verify your environment variables are loaded correctly, start the server and check the console output: 
npm run dev
You should see: 
Connected to MongoDB
Server running on port 5000
If you see connection errors, verify that your MONGODB_URI is correct and that MongoDB is running.

​
Troubleshooting

​
Variables Not Loading

If environment variables aren’t loading:
  1. Ensure the .env file is in the backend directory
  2. Check that variable names match exactly (case-sensitive)
  3. Restart the server after making changes
  4. Verify no trailing spaces in variable values

​
MongoDB Connection Issues

If MongoDB connection fails:
  1. Verify MongoDB is running locally: mongod --version
  2. Check the connection string format
  3. For Atlas, ensure IP whitelist includes your address
  4. Verify credentials are correct

​
JWT Errors

If authentication fails:
  1. Ensure JWT_SECRET is set and not empty
  2. Use the same secret across all server instances
  3. Check token expiration (default: 30 days)

Build docs developers (and LLMs) love

Get started for freeTalk to us