Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed on your system:
  • Node.js (v18 or higher)
  • pnpm (v10.25.0 or higher)
  • Docker and Docker Compose
  • Git
BudgetBee uses pnpm as its package manager. Make sure you have the correct version installed: [email protected]

​
Quick Setup

The fastest way to get started is using the Makefile:
1

Clone the repository

git clone https://github.com/sammaji/budgetbee
cd budgetbee
2

Run the setup command

make setup
This command will:
  • Install all dependencies with pnpm install
  • Create .env file and symlink it to all packages
  • Start PostgreSQL and PostgREST containers
  • Create database roles and run migrations
  • Fetch JWKS secret and update .env
3

Update environment variables

Open the .env file at the root and configure any missing variables:
# Database
POSTGRESQL_USER=your_db_user
POSTGRES_AUTH_ADMIN_USER=postgres_auth_admin_user
POSTGRES_SUBSCRIPTION_ADMIN_USER=postgres_subscription_admin_user

# Application URLs
NEXT_PUBLIC_SITE_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3001

# Optional: For testing with dummy data
DEV_ONLY_TEST_USER_ID=your_user_id
4

Start development servers

make dev
This starts all three applications:
  • docs - Documentation site at http://localhost:3002
  • site - Landing page at http://localhost:3000
  • web - Main application at http://localhost:3001

​
Manual Setup

If you prefer to set up manually or the automated scripts fail:
1

Install dependencies

pnpm install
2

Create environment file

chmod +x scripts/*
./scripts/post_install.sh
This creates a .env file at the root and symlinks it to all packages that need environment variables.
3

Start PostgreSQL

cd infra
docker compose up -d
Ensure all environment variables starting with POSTGRES_ are set before starting the containers.
4

Create database roles

Create three PostgreSQL users with appropriate permissions:
CREATE USER postgresql_user WITH PASSWORD 'password';
CREATE USER postgres_auth_admin_user WITH PASSWORD 'password';
CREATE USER postgres_subscription_admin_user WITH PASSWORD 'password';
Add these user names to your .env file.
5

Run migrations

Run each migration file in packages/core/migrations in order:
  1. better-auth-migrations.sql
  2. init.sql
  3. All other migration files sorted by date
Or use the automated script:
./scripts/create_roles.sh
./scripts/run_migrations.sh
6

Get JWKS secret

Start the development servers:
pnpm turbo dev
Visit http://localhost:3000/api/auth/jwks and copy the JWKS secret. Set PGRST_JWT_SECRET in your .env file to this value.
You only need to do this once during initial setup.

​
Available Make Commands

BudgetBee includes a Makefile with helpful commands: 
# Install dependencies
make install

# Create .env and symlinks
make setup-env

# Full setup (install + env + db + jwks)
make setup

​
Adding Dummy Data

For testing purposes, you can populate the database with dummy data: 
make dummy-data
Or manually: 
source .env
cd packages/core
pnpm tsx --env=.env ./scripts/initdb.ts
Make sure to set DEV_ONLY_TEST_USER_ID in your .env file to your user ID before running this command.

​
Troubleshooting

​
Scripts are failing

The automation scripts can be flaky. If they fail, follow the manual setup steps instead.

​
PostgreSQL connection issues

Ensure your Docker containers are running: 
cd infra
docker compose ps

​
Missing environment variables

Check that all required variables in .env are set, especially:
  • Database connection strings
  • PostgreSQL user credentials
  • Application URLs

​
Next Steps

Project Structure

Learn about the monorepo structure and organization

Code Guidelines

Review coding standards and best practices

​
Getting Help

If you get stuck:

Build docs developers (and LLMs) love

Get started for freeTalk to us