Installation

System requirements

Before installing BillBuddy, ensure your system meets these requirements:

Node.js: v18.0.0 or higher (specified in backend/package.json:6-8)
MongoDB: v4.4 or higher
npm: v8 or higher (or yarn as an alternative)
Memory: Minimum 2GB RAM recommended
Disk Space: 500MB for dependencies and database

BillBuddy uses modern JavaScript features and requires Node.js v18+ as specified in the backend engine configuration.

Repository structure

BillBuddy follows a monorepo structure with separate backend and frontend directories:

billbuddy/
├── backend/          # Express.js backend
│   ├── models/       # Mongoose data models
│   ├── routes/       # API route handlers
│   ├── middleware/   # Authentication middleware
│   ├── utils/        # Email and utility functions
│   ├── server.js     # Express app entry point
│   └── package.json
└── frontend/         # React frontend
    ├── src/
    │   ├── pages/    # React page components
    │   ├── components/ # Reusable UI components
    │   ├── context/  # React context providers
    │   └── App.jsx   # Main app component
    └── package.json

Backend installation

Navigate to backend directory

cd backend

Install dependencies

Install all required npm packages:

npm install

This installs the following key dependencies:

{
  "express": "^4.18.2",
  "mongoose": "^7.5.0",
  "jsonwebtoken": "^9.0.2",
  "bcryptjs": "^2.4.3",
  "dotenv": "^16.3.1",
  "cors": "^2.8.5"
}

Configure environment variables

Create a .env file in the backend directory:

.env

# Server Configuration
PORT=5000

# Database Configuration
MONGODB_URI=mongodb://localhost:27017/billbuddy

# JWT Configuration
JWT_SECRET=your_secure_jwt_secret_key_minimum_32_characters

# Email Configuration (Optional)
WEB3FORMS_ACCESS_KEY=your_web3forms_access_key

Environment variable details

PORT

The port on which the Express server will run. Default is 5000.The server listens on this port as specified in server.js:62:

const PORT = process.env.PORT || 5000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

MONGODB_URI

MongoDB connection string. Can be:

Local: mongodb://localhost:27017/billbuddy
MongoDB Atlas: mongodb+srv://username:[email protected]/billbuddy

Used in server.js:40-42 for database connection:

mongoose.connect(process.env.MONGODB_URI)
  .then(() => console.log('Connected to MongoDB'))
  .catch((err) => console.error('MongoDB connection error:', err));

JWT_SECRET

Secret key for signing JWT tokens. Must be a strong, random string.Used in models/User.js:48-50 for token generation:

UserSchema.methods.getSignedJwtToken = function() {
  return jwt.sign({ id: this._id }, process.env.JWT_SECRET, {
    expiresIn: '30d'
  });
};

Use a secure random string (minimum 32 characters). Never commit this to version control. Tokens expire after 30 days.

WEB3FORMS_ACCESS_KEY

Access key for Web3Forms email service. Used for sending settlement summaries.Implemented in utils/email.js:31-39:

const response = await axios.post('https://api.web3forms.com/submit', {
  access_key: process.env.WEB3FORMS_ACCESS_KEY,
  subject,
  from_name: 'BillBuddy',
  to: members.join(','),
  body
});

Get a free key at web3forms.com. Optional for development but recommended for production.

Set up MongoDB

BillBuddy requires a running MongoDB instance. Choose one option:

Local MongoDB
MongoDB Atlas (Cloud)
Docker

macOS (Homebrew):

# Install MongoDB
brew tap mongodb/brew
brew install mongodb-community

# Start MongoDB service
brew services start mongodb-community

# Verify MongoDB is running
mongosh

Ubuntu/Debian:

# Install MongoDB
sudo apt-get install -y mongodb-org

# Start MongoDB service
sudo systemctl start mongod
sudo systemctl enable mongod

# Verify MongoDB is running
sudo systemctl status mongod

Windows: Download and install from mongodb.com/try/download/community

Create a free account at mongodb.com/cloud/atlas
Create a new cluster
Add a database user
Whitelist your IP address (or use 0.0.0.0/0 for development)
Get your connection string and update MONGODB_URI in .env:

MONGODB_URI=mongodb+srv://username:[email protected]/billbuddy?retryWrites=true&w=majority

Run MongoDB in a Docker container:

# Pull and run MongoDB image
docker run -d \
  --name billbuddy-mongodb \
  -p 27017:27017 \
  -v billbuddy-data:/data/db \
  mongo:7

# Verify container is running
docker ps

Use the default local connection string in your .env:

MONGODB_URI=mongodb://localhost:27017/billbuddy

Start the backend server

Development
Production

Run with nodemon for automatic reloading:

npm run dev

Output:

[nodemon] 3.0.1
[nodemon] watching path(s): *.*
[nodemon] watching extensions: js,mjs,json
Server running on port 5000
Connected to MongoDB

Run with Node.js directly:

npm start

For production deployments, consider using PM2:

npm install -g pm2
pm2 start server.js --name billbuddy-backend
pm2 save
pm2 startup

Frontend installation

Navigate to frontend directory

cd frontend

Install dependencies

Install all required npm packages:

npm install

This installs the following key dependencies:

{
  "react": "^18.2.0",
  "react-dom": "^18.2.0",
  "react-router-dom": "^6.22.1"
}

Configure API endpoint

The frontend is configured to communicate with the backend at http://localhost:5000.The CORS configuration in server.js:30-37 allows these origins:

app.use(cors({
  origin: ['http://localhost:5173', 'http://127.0.0.1:5173'],
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization', 'Accept'],
  credentials: true
}));

If you change the backend port or deploy to a different domain, update the CORS configuration in server.js to include your new origin.

Start the development server

Run the Vite development server:

npm run dev

Output:

VITE v5.1.0  ready in 500 ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
➜  press h + enter to show help

The frontend will be available at http://localhost:5173.

Build for production

To create an optimized production build:

npm run build

This creates a dist folder with optimized assets. Preview the production build:

npm run preview

Verify installation

Test backend API

Verify the backend is running by testing the health endpoint:

curl http://localhost:5000/api/auth/me

You should receive a 401 response (expected without authentication).

Test frontend

Open http://localhost:5173 in your browser. You should see the BillBuddy home page with:

Navigation bar with Login/Register buttons
Hero section with gradient background
Feature cards

Test user registration

Click “Sign Up” or navigate to http://localhost:5173/register
Fill in the registration form (name, email, password)
Submit the form
You should be redirected to the groups page with a valid JWT token

Test database connection

Verify data was saved to MongoDB:

mongosh
use billbuddy
db.users.find().pretty()

You should see your newly registered user.

Running both servers

For development convenience, you can run both servers simultaneously:

Option 1: Using concurrently (from backend directory)

cd backend
npm run dev:full

This script (defined in backend/package.json:13) uses concurrently to run both servers:

"dev:full": "concurrently \"npm run dev\" \"npm run client\""

Option 2: Separate terminals

Terminal 1 (Backend):

cd backend
npm run dev

Terminal 2 (Frontend):

cd frontend
npm run dev

Common issues

Module not found errors

If you encounter module not found errors:

Delete node_modules folders:

rm -rf backend/node_modules frontend/node_modules

Clear npm cache:
```
npm cache clean --force
```

Reinstall dependencies:

cd backend && npm install
cd ../frontend && npm install

MongoDB connection refused

If you see “ECONNREFUSED” or “MongoServerError”:

Verify MongoDB is running:

# macOS
brew services list | grep mongodb

# Linux
sudo systemctl status mongod

Check the MongoDB port (default 27017):
```
lsof -i :27017
```
Verify your MONGODB_URI in .env is correct

Check MongoDB logs for errors:

# macOS
tail -f /usr/local/var/log/mongodb/mongo.log

# Linux
sudo tail -f /var/log/mongodb/mongod.log

CORS policy errors

If you see CORS errors in the browser console:

Verify the backend is running on port 5000
Verify the frontend is running on port 5173
Check the CORS configuration in backend/server.js:30-37
Clear browser cache and hard reload (Cmd/Ctrl + Shift + R)

For custom ports, update the CORS origins:

app.use(cors({
  origin: ['http://localhost:YOUR_PORT'],
  // ...
}));

JWT authentication fails

If authentication tokens are not working:

Verify JWT_SECRET is set in your .env file
Check that the secret is at least 32 characters

Clear browser localStorage:

// In browser console
localStorage.clear();

Port already in use

If port 5000 or 5173 is already in use:Backend port conflict:

# Find process using port 5000
lsof -i :5000

# Kill the process
kill -9 <PID>

# Or change the port in .env
PORT=5001

Frontend port conflict: Vite will automatically try the next available port (5174, 5175, etc.)

Next steps

API reference

Explore all available API endpoints and request/response formats.

Authentication guide

Learn how to authenticate users and protect routes.

Core features

Understand the MongoDB schema for Users, Groups, Expenses, and Settlements.

Configuration

Configure environment variables and database settings.

Get Started

Core Features

Guides

Configuration

System requirements

Repository structure

Backend installation

Environment variable details

Frontend installation

Verify installation

Running both servers

Option 1: Using concurrently (from backend directory)

Option 2: Separate terminals

Common issues

Next steps

API reference

Authentication guide

Core features

Configuration

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

Configuration

​System requirements

​Repository structure

​Backend installation

​Environment variable details

​Frontend installation

​Verify installation

​Running both servers

​Option 1: Using concurrently (from backend directory)

​Option 2: Separate terminals

​Common issues

​Next steps

API reference

Authentication guide

Core features

Configuration

Build docs developers (and LLMs) love

System requirements

Repository structure

Backend installation

Environment variable details

Frontend installation

Verify installation

Running both servers

Option 1: Using concurrently (from backend directory)

Option 2: Separate terminals

Common issues

Next steps