Skip to main content

​
Installation

Budget Bee can be accessed as a hosted web application or self-hosted on your own infrastructure.

​
Accessing Budget Bee

​
Hosted Version

The easiest way to use Budget Bee is through the hosted version:
  1. Visit the Budget Bee web application at the provided URL
  2. Create an account or sign in
  3. Start managing your finances immediately
The hosted version is maintained and updated automatically. No installation required.

​
System Requirements

​
Browser Compatibility

Budget Bee works best on modern web browsers:

Recommended Browsers

  • Chrome 90+
  • Firefox 88+
  • Safari 14+
  • Edge 90+

Mobile Support

  • iOS Safari 14+
  • Chrome Mobile 90+
  • Android Browser (latest)

​
Minimum Requirements

  • JavaScript: Must be enabled
  • Cookies: Must be enabled for authentication
  • Screen Resolution: 1024x768 or higher recommended
  • Internet Connection: Required for all features

​
Self-Hosting Budget Bee

For organizations that want to host Budget Bee on their own infrastructure:

​
Prerequisites

Before installing Budget Bee, ensure you have:
  • Node.js 22 or higher
  • pnpm 10.25.0 or higher (specified in package.json)
node --version  # Should be v22.x.x or higher
pnpm --version  # Should be 10.25.0 or higher
  • PostgreSQL 14 or higher
  • Ability to create databases and users
  • At least 1GB of storage space
See Database Setup for detailed instructions.
  • Resend API key (or another SMTP service)
  • For sending verification emails and notifications
Budget Bee uses Resend by default for transactional emails.
  • Redis (for caching and session management)
  • Cloudinary (for image uploads)
  • Polar (for subscription billing)

​
Installation Steps

1

Clone the Repository

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

Install Dependencies

pnpm install
This will install all dependencies for the monorepo including:
  • Web application (apps/web)
  • Core packages (packages/core)
  • UI components (packages/ui)
3

Configure Environment Variables

Copy the example environment file and configure it:
cp .env.example .env
Edit .env with your configuration. See Environment Variables for details.
Never commit your .env file to version control. It contains sensitive secrets.
4

Set Up the Database

Initialize the PostgreSQL database:
# Run the initialization script
pnpm --filter @budgetbee/core run initdb
This will:
  • Create required database roles
  • Run all migrations
  • Set up row-level security policies
See Database Setup for manual setup instructions.
5

Start Development Server

pnpm --filter @budgetbee/web dev
The application will be available at http://localhost:3000

​
Building for Production

To build Budget Bee for production deployment: 
# Build the web application
pnpm --filter @budgetbee/web build

# Start the production server
pnpm --filter @budgetbee/web start
Use a process manager like PM2 or systemd to keep the application running in production.

​
Docker Deployment

Budget Bee includes Docker configuration in the infra/ directory: 
# Build and start all services
docker-compose up -d
This will start:
  • Web application
  • PostgreSQL database
  • Redis (if configured)

​
Verifying Installation

After installation, verify everything is working:
1

Check Application Health

Visit http://localhost:3000 (or your configured URL)You should see the Budget Bee login page.
2

Test Authentication

Try creating a new account:
  • Sign up with email and password
  • Verify you receive the verification email
  • Complete email verification
3

Test Database Connection

After logging in, try creating a transaction.If successful, your database connection is working correctly.

​
Troubleshooting

Check your database configuration in .env:
  • Verify POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DATABASE
  • Ensure PostgreSQL is running
  • Check database user permissions
# Test PostgreSQL connection
psql -h localhost -U root -d budgetbee
Check your Resend configuration:
  • Verify RESEND_API_KEY is set
  • Ensure SMTP_SENDER_NAME and SMTP_MAIL are configured
  • Check Resend dashboard for delivery status
If port 3000 is in use, specify a different port:
pnpm --filter @budgetbee/web dev -- -p 3001
Clear the build cache and reinstall:
pnpm clean
rm -rf node_modules
pnpm install

​
Updating Budget Bee

To update your self-hosted installation: 
# Pull latest changes
git pull origin main

# Install new dependencies
pnpm install

# Run new migrations
pnpm --filter @budgetbee/core run migrate

# Rebuild the application
pnpm --filter @budgetbee/web build

# Restart the server
pnpm --filter @budgetbee/web start
Always backup your database before updating to a new version.

​
Next Steps

Configure Database

Set up PostgreSQL with proper roles and permissions.

Set Up Authentication

Configure Better Auth with OAuth providers.

Environment Variables

Complete reference for all configuration options.

Start Using Budget Bee

Create your first account and add transactions.

Build docs developers (and LLMs) love

Get started for freeTalk to us