Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js v18 or higher
  • MongoDB v4.4 or higher (running locally or accessible remotely)
  • npm or yarn package manager
  • Git (for cloning the repository)
This quickstart guide will get you up and running with default settings. For production deployments or advanced configuration, see the installation guide.

​
Quick setup

1

Clone the repository

Clone the BillBuddy repository and navigate to the project directory:
git clone https://github.com/yourusername/billbuddy.git
cd billbuddy
2

Install backend dependencies

Install the required Node.js packages for the backend:
cd backend
npm install
This installs Express.js, MongoDB, JWT, and other backend dependencies.
3

Configure environment variables

Create a .env file in the backend directory with your configuration:
.env
PORT=5000
MONGODB_URI=mongodb://localhost:27017/billbuddy
JWT_SECRET=your_secure_jwt_secret_key_here
WEB3FORMS_ACCESS_KEY=your_web3forms_key_here
Replace your_secure_jwt_secret_key_here with a strong, random secret. This is used to sign authentication tokens and should be kept secure.
The WEB3FORMS_ACCESS_KEY is optional for development. Get a free key at web3forms.com to enable email settlement summaries.
4

Start MongoDB

Ensure MongoDB is running on your system. If you have MongoDB installed locally:
# macOS (using Homebrew)
brew services start mongodb-community

# Linux (using systemd)
sudo systemctl start mongod

# Or run MongoDB directly
mongod --dbpath /path/to/your/data/directory
You can also use MongoDB Atlas (cloud) by updating the MONGODB_URI in your .env file with your Atlas connection string.
5

Start the backend server

Launch the Express.js backend server:
npm run dev
You should see:
Server running on port 5000
Connected to MongoDB
The backend API is now running at http://localhost:5000.
6

Install frontend dependencies

Open a new terminal window and install the React frontend dependencies:
cd frontend
npm install
This installs React, Material-UI, Axios, and other frontend dependencies.
7

Start the frontend development server

Launch the Vite development server for the React frontend:
npm run dev
The frontend will be available at http://localhost:5173.
8

Access BillBuddy

Open your browser and navigate to http://localhost:5173. You should see the BillBuddy home page.
The frontend is configured to communicate with the backend at http://localhost:5000. If you change the backend port, update the API base URL in the frontend code.

​
Verify your installation

To confirm everything is working correctly:
  1. Test user registration: Click “Sign Up” and create a new account
  2. Create a group: Navigate to “Groups” and create your first expense group
  3. Add an expense: Add a test expense to your group
  4. Check balances: Verify that balances are calculated correctly

​
What’s next?

API reference

Explore all available API endpoints and learn how to integrate with BillBuddy.

Detailed installation

Learn about advanced configuration options and production setup.

Authentication

Understand how JWT authentication works in BillBuddy.

Configuration

Configure environment variables and settings for your deployment.

​
Troubleshooting

​
Port already in use

If port 5000 or 5173 is already in use, you can change the ports:
  • Backend: Update PORT in your .env file
  • Frontend: Vite will automatically try the next available port, or you can specify one in vite.config.js

​
MongoDB connection error

If you see “MongoDB connection error”:
  1. Verify MongoDB is running: mongosh (should connect successfully)
  2. Check your MONGODB_URI in the .env file
  3. Ensure the MongoDB port (default 27017) is not blocked

​
CORS errors

If you encounter CORS errors:
  1. Verify the backend is running on port 5000
  2. Check that the frontend is running on port 5173
  3. The backend CORS configuration in server.js:30-37 allows these origins by default
For production deployments, update the CORS configuration to include your production domain instead of localhost URLs.

​
Running both servers concurrently

For convenience during development, you can run both servers with a single command from the backend directory: 
npm run dev:full
This uses concurrently to run both the backend and frontend development servers simultaneously.

Build docs developers (and LLMs) love

Get started for freeTalk to us