Installation Guide

This guide covers all installation methods for Budgetron, from Docker deployments to manual setup. Choose the method that best fits your infrastructure and requirements.

Prerequisites

System Requirements

For Docker Installation

Docker 20.10 or later
Docker Compose (optional)
2GB RAM minimum
5GB disk space

For Manual Installation

Node.js 18+ (Alpine compatible)
pnpm 10.30.3 or later
2GB RAM minimum
10GB disk space

Required Services

Budgetron requires a PostgreSQL database. Ensure you have access to a PostgreSQL instance before proceeding.

PostgreSQL 14+ with CREATE TABLE permissions
Network access to the database from your Budgetron instance

Optional Services

These services enable additional features:

Ollama or OpenAI-compatible API - For AI transaction categorization
Email service (e.g., Resend) - For password resets and notifications
Vercel Blob or S3-compatible storage - For profile picture uploads

Installation Methods

Docker (Recommended)
Manual Setup

Docker Installation

Docker provides the simplest and most reliable way to deploy Budgetron.

Step 1: Clone the Repository

git clone https://github.com/raghavan-dev/budgetron.git
cd budgetron

Step 2: Configure Environment

Create your environment configuration:

cp .env.example .env

Edit .env with your settings:

.env

# Authentication (Required)
AUTH_SECRET="your-secret-key-here"  # Generate: openssl rand -base64 32
AUTH_URL="https://budgetron.yourdomain.com"

# Database (Required)
DB_URL="postgresql://budgetron:password@postgres:5432/budgetron"

# Cron Jobs (Required)
CRON_SECRET_SLUG="sync-currency-rates"
CRON_SECRET_TOKEN="your-secure-cron-token"

# Google OAuth (Optional)
GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""

# Custom OAuth (Optional)
OAUTH_CLIENT_ID=""
OAUTH_CLIENT_SECRET=""
OAUTH_PROVIDER_NAME=""
OPENID_CONFIGURATION_URL=""

# AI Provider (Optional)
OPENAI_COMPATIBLE_PROVIDER="ollama"
OPENAI_COMPATIBLE_BASE_URL="http://ollama:11434/v1"
OPENAI_COMPATIBLE_API_KEY="ollama"
OPENAI_COMPATIBLE_MODEL="llama3"

# Email (Optional)
EMAIL_PROVIDER_API_KEY=""
EMAIL_PROVIDER_FROM_EMAIL="[email protected]"

# Blob Storage (Optional)
BLOB_READ_WRITE_TOKEN=""

For production deployments, use a secrets management solution instead of plain text .env files.

Step 3: Build the Image

Build the Budgetron Docker image:

docker build -t budgetron .

The Dockerfile uses a multi-stage build process:

Base stage: Sets up Node Alpine with PostgreSQL client
Dependencies stage: Installs all dependencies with pnpm
Builder stage: Compiles Next.js and migration tooling
Runner stage: Creates minimal production image

The build process includes gcompat for Alpine compatibility and postgresql-client for database health checks.

Step 4: Run the Container

Start Budgetron with your environment configuration:

docker run -d \
  --name budgetron \
  --env-file .env \
  -p 3000:3000 \
  --restart unless-stopped \
  budgetron

Advanced Docker Options

Custom Port:

docker run -d \
  --name budgetron \
  --env-file .env \
  -p 8080:3000 \
  budgetron

Custom Database Wait Timeout:

docker run -d \
  --name budgetron \
  --env-file .env \
  -e MAX_WAIT=60 \
  -p 3000:3000 \
  budgetron

Mount Logs Volume:

docker run -d \
  --name budgetron \
  --env-file .env \
  -v budgetron-logs:/app/.next/logs \
  -p 3000:3000 \
  budgetron

Step 5: Verify Deployment

Check container health:

docker logs -f budgetron

Expected output:

⏳ Waiting for database using DB_URL...
📦 Running DB migration...
✅ DB migration completed.
🚀 Starting server...

Test the application:

curl http://localhost:3000

If you see HTML content, Budgetron is running successfully!

Manual Installation

For development or custom deployments without Docker.

Step 1: Install Dependencies

Ensure you have the required tools:

# Check Node.js version (requires 18+)
node --version

# Install pnpm if not already installed
npm install -g [email protected]

Step 2: Clone and Install

# Clone repository
git clone https://github.com/raghavan-dev/budgetron.git
cd budgetron

# Install dependencies
pnpm install

The installation uses pnpm workspaces and includes both the main app and migration tooling.

Step 3: Configure Environment

cp .env.example .env

Edit .env with your configuration (same as Docker setup above).

Step 4: Set Up Database

Run database migrations:

pnpm run db:migrate

This applies all Drizzle ORM migrations to your PostgreSQL database.

For development with a separate database:

pnpm run db:migrate:dev

Step 5: Build for Production

# Build Next.js application
pnpm run build

The build process:

Compiles TypeScript
Generates optimized Next.js bundles
Creates standalone server output

Step 6: Start the Server

# Production mode
pnpm start

Or for development:

# Development mode with hot reload
pnpm dev

Access Budgetron at http://localhost:3000

Database Setup

Creating the Database

Connect to your PostgreSQL server and create the database:

CREATE DATABASE budgetron;
CREATE USER budgetron WITH PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE budgetron TO budgetron;

Connection String Format

The DB_URL environment variable should follow this format:

postgresql://[user]:[password]@[host]:[port]/[database]

DB_URL="postgresql://budgetron:password@localhost:5432/budgetron"

Always use SSL connections (?sslmode=require) for hosted databases in production.

Migration Management

Budgetron uses Drizzle ORM for database migrations:

# Generate new migration
pnpm run db:generate

# Apply migrations
pnpm run db:migrate

# Open Drizzle Studio (database GUI)
pnpm run db:studio

In Docker deployments, migrations run automatically on container startup via the entrypoint.sh script.

Post-Installation Configuration

Setting Up AI Categorization

For local AI processing with Ollama:

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull LLaMA 3 model
ollama pull llama3

# Configure Budgetron
OPENAI_COMPATIBLE_PROVIDER="ollama"
OPENAI_COMPATIBLE_BASE_URL="http://localhost:11434/v1"
OPENAI_COMPATIBLE_API_KEY="ollama"
OPENAI_COMPATIBLE_MODEL="llama3"

Other supported models include mixtral, mistral, and any OpenAI-compatible API.

Configuring Google OAuth

Go to Google Cloud Console
Create a new project or select existing
Enable Google+ API
Create OAuth 2.0 credentials
Add authorized redirect URI: {AUTH_URL}/api/auth/callback/google
Copy Client ID and Secret to .env

Setting Up Email Notifications

Budgetron supports any email provider compatible with the Resend SDK:

EMAIL_PROVIDER_API_KEY="re_..."
EMAIL_PROVIDER_FROM_EMAIL="[email protected]"

Required for:

Password reset emails
Account deletion confirmations
Budget alerts (upcoming feature)

Configuring Cron Jobs

Budgetron uses cron jobs for background tasks like currency rate synchronization:

CRON_SECRET_SLUG="sync-currency-rates"
CRON_SECRET_TOKEN="your-secure-token"

Set up your cron scheduler to call:

POST {AUTH_URL}/api/cron/{CRON_SECRET_SLUG}
Authorization: Bearer {CRON_SECRET_TOKEN}

Use services like cron-job.org or your server’s crontab for scheduling.

Troubleshooting

Common Issues

Database connection refused

Symptoms: Container exits with ❌ DB unavailable after 30sSolutions:

Verify PostgreSQL is running: pg_isready -h host -p 5432
Check firewall rules allow connections
Ensure DB_URL format is correct
For Docker: Use container name instead of localhost if using Docker networks
Increase wait timeout: -e MAX_WAIT=60

Migration errors

Symptoms: Error: relation "users" already existsSolutions:

Check if database was previously initialized
Verify database user has CREATE TABLE permissions
Review migration state: SELECT * FROM __drizzle_migrations;
For fresh start: Drop and recreate the database (data loss!)

Authentication not working

Symptoms: Login fails or session expires immediatelySolutions:

Verify AUTH_SECRET is set and at least 32 characters
Ensure AUTH_URL matches the URL you’re accessing
Check browser cookies are enabled
For HTTPS: Ensure secure cookie settings are correct

AI categorization not working

Symptoms: Transactions not categorized automaticallySolutions:

Verify all AI environment variables are set
Check Ollama is running: curl http://localhost:11434
Test API endpoint: curl http://localhost:11434/v1/models
Review application logs for API errors

Port conflicts

Symptoms: Error: Address already in useSolutions:

Change Docker port mapping: -p 8080:3000
Find conflicting process: lsof -i :3000
Stop conflicting service or use different port

Build failures

Symptoms: Docker build or pnpm build failsSolutions:

Ensure sufficient disk space (10GB+)
Clear Docker cache: docker builder prune
For manual build: Delete node_modules and reinstall
Check Node.js version: node --version (requires 18+)

Getting Help

GitHub Issues

Report bugs or request features

Documentation

Browse the full documentation

Next Steps

Now that Budgetron is installed:

Create Your First Account

Navigate to your Budgetron URL and sign up

Configure Your Budget

Set up budget categories and spending limits

Import Transactions

Import existing transactions from CSV or OFX files

Enable AI Categorization

Let AI automatically categorize your transactions

For production deployments, see our Production Best Practices guide.

Get Started

Core Features

Configuration

Deployment

Development

​Installation Guide

​Prerequisites

​System Requirements

For Docker Installation

For Manual Installation

​Required Services

​Optional Services

​Installation Methods

​Docker Installation

​Step 1: Clone the Repository

​Step 2: Configure Environment

​Step 3: Build the Image

​Step 4: Run the Container

​Step 5: Verify Deployment

​Manual Installation

​Step 1: Install Dependencies

​Step 2: Clone and Install

​Step 3: Configure Environment

​Step 4: Set Up Database

​Step 5: Build for Production

​Step 6: Start the Server

​Database Setup

​Creating the Database

​Connection String Format

​Migration Management

​Post-Installation Configuration

​Setting Up AI Categorization

​Configuring Google OAuth

​Setting Up Email Notifications

​Configuring Cron Jobs

​Troubleshooting

​Common Issues

​Getting Help

GitHub Issues

Documentation

​Next Steps

Build docs developers (and LLMs) love

Installation Guide

Prerequisites

System Requirements

Required Services

Optional Services

Installation Methods

Docker Installation

Step 1: Clone the Repository

Step 2: Configure Environment

Step 3: Build the Image

Step 4: Run the Container

Step 5: Verify Deployment

Manual Installation

Step 1: Install Dependencies

Step 2: Clone and Install

Step 3: Configure Environment

Step 4: Set Up Database

Step 5: Build for Production

Step 6: Start the Server

Database Setup

Creating the Database

Connection String Format

Migration Management

Post-Installation Configuration

Setting Up AI Categorization

Configuring Google OAuth

Setting Up Email Notifications

Configuring Cron Jobs

Troubleshooting

Common Issues

Getting Help

Next Steps