Skip to main content

​
Quickstart Guide

Get Budgetron running on your system in under 5 minutes using Docker. This guide will walk you through the fastest path to a working installation.
This quickstart uses Docker for the simplest setup. For other installation methods, see the Installation Guide.

​
Prerequisites

Before you begin, ensure you have:
  • Docker installed and running (Get Docker)
  • PostgreSQL database accessible (local or hosted)
  • 10 minutes of your time

​
Quick Setup

1

Clone the Repository

First, clone the Budgetron repository to your local machine:
git clone https://github.com/raghavan-dev/budgetron.git
cd budgetron
2

Set Up Environment Variables

Copy the example environment file and configure your settings:
cp .env.example .env
Open .env in your favorite editor and configure the required variables:
# Required: Authentication
AUTH_SECRET="your-secret-key-here"  # Generate with: openssl rand -base64 32
AUTH_URL="http://localhost:3000"

# Required: Database
DB_URL="postgresql://user:password@host:5432/budgetron"

# Required: Cron Jobs
CRON_SECRET_SLUG="your-cron-slug"
CRON_SECRET_TOKEN="your-cron-token"
Generate a secure AUTH_SECRET using: openssl rand -base64 32
For AI-powered transaction categorization, add these variables:
# Using Ollama locally
OPENAI_COMPATIBLE_PROVIDER="ollama"
OPENAI_COMPATIBLE_BASE_URL="http://localhost:11434/v1"
OPENAI_COMPATIBLE_API_KEY="ollama"  # Ollama doesn't need a real key
OPENAI_COMPATIBLE_MODEL="llama3"
Or use a hosted provider like OpenAI or Groq:
OPENAI_COMPATIBLE_PROVIDER="openai"
OPENAI_COMPATIBLE_BASE_URL="https://api.openai.com/v1"
OPENAI_COMPATIBLE_API_KEY="sk-..."
OPENAI_COMPATIBLE_MODEL="gpt-4"
To enable Google OAuth authentication:
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"
3

Build the Docker Image

Build the Budgetron Docker image:
docker build -t budgetron .
The build process includes dependency installation, Next.js compilation, and migration tooling setup. This may take 5-10 minutes on first build.
4

Run the Container

Start Budgetron with your environment variables:
docker run -d \
  --name budgetron \
  --env-file .env \
  -p 3000:3000 \
  budgetron
Or pass environment variables directly:
docker run -d \
  --name budgetron \
  -e DB_URL="postgresql://user:password@host:5432/budgetron" \
  -e AUTH_SECRET="your-secret-key" \
  -e AUTH_URL="http://localhost:3000" \
  -e CRON_SECRET_SLUG="your-slug" \
  -e CRON_SECRET_TOKEN="your-token" \
  -p 3000:3000 \
  budgetron
Want to run on a different port? Use -p 8080:3000 to expose on port 8080 instead.
5

Verify It's Running

Check the container logs to ensure everything started correctly:
docker logs -f budgetron
You should see:
⏳ Waiting for database using DB_URL...
📦 Running DB migration...
✅ DB migration completed.
🚀 Starting server...
The container automatically waits for the database to be ready, runs migrations, and starts the server.
6

Access Budgetron

Open your browser and navigate to:
http://localhost:3000
You should see the Budgetron login page. Create your first account and start budgeting!
Congratulations! You’ve successfully deployed Budgetron.

​
What Happens on Startup?

The Docker container runs through an automated startup sequence:
  1. Database Health Check - Waits up to 30 seconds for PostgreSQL to be ready
  2. Schema Migration - Automatically applies all pending Drizzle ORM migrations
  3. Server Start - Launches the Next.js production server
This ensures your database is always up-to-date with the latest schema changes.

​
Next Steps

Configure Authentication

Set up Google OAuth or custom OAuth providers

Enable AI Features

Configure AI-powered transaction categorization

Production Deployment

Deploy Budgetron to production with best practices

Development Guide

Set up your local development environment

​
Troubleshooting

Check the logs with docker logs budgetron. Common issues:
  • Missing environment variables: Ensure AUTH_SECRET, AUTH_URL, DB_URL, CRON_SECRET_SLUG, and CRON_SECRET_TOKEN are set
  • Database connection failed: Verify your DB_URL is correct and the database is accessible
If you see DB unavailable after 30s, your database might not be accessible:
  • Verify the PostgreSQL server is running
  • Check firewall rules allow connections
  • Ensure credentials in DB_URL are correct
  • If using Docker networking, use the container name instead of localhost
If port 3000 is already in use:
docker run -d \
  --name budgetron \
  --env-file .env \
  -p 8080:3000 \
  budgetron
Then access Budgetron at http://localhost:8080
If migrations fail:
  1. Ensure the database user has CREATE TABLE permissions
  2. Check if the database already has conflicting tables
  3. Review migration logs: docker logs budgetron | grep migration
For more detailed troubleshooting, see the Installation Guide or join our community discussions.

Build docs developers (and LLMs) love

Get started for freeTalk to us