TroutTrout
Guide

Deploy with Docker

From zero to budgeting in about 10 minutes. This guide covers everything from cloning the repo to creating your first budget.

Prerequisites

  • Docker and Docker Compose -- any recent version. Install from docs.docker.com.
  • Git -- to clone the repository.
  • ~512 MB RAM -- PostgreSQL + API + Web app. Works on a $4/month VPS, a Raspberry Pi 4, or any modern server.

1. Clone the repository

git clone https://github.com/SSardorf/betterbudget.git
cd betterbudget

2. Configure environment

Copy the example env file and fill in the required values.

cp .env.example .env

Required settings

.env
# Generate a secret for authentication
BETTER_AUTH_SECRET=$(openssl rand -base64 32)

# Database credentials (change from defaults in production)
POSTGRES_USER=budget_user
POSTGRES_PASSWORD=your_secure_password_here
POSTGRES_DB=betterbudget

# Where the API is accessible (for auth callbacks)
BETTER_AUTH_URL=http://localhost:3001

# Where the web app reaches the API
NEXT_PUBLIC_API_URL=http://localhost:3001

# CORS origins (your web app URL)
ALLOWED_ORIGINS=http://localhost:3000

Optional settings

Bank sync: Get GoCardless credentials from bankaccountdata.gocardless.com and set GOCARDLESS_SECRET_ID and GOCARDLESS_SECRET_KEY.

AI assistant: Set OPENAI_API_KEY with your API key from OpenAI or another provider.

Investment sync: Generate an encryption key with openssl rand -base64 32 and set CREDENTIAL_ENCRYPTION_KEY.

3. Start everything

One command starts PostgreSQL, runs database migrations, the API, and the web app.

docker compose -f docker-compose.production.yml up -d

First run takes a few minutes to build images. After that, startup is fast. Check the logs to confirm everything is healthy:

docker compose -f docker-compose.production.yml logs -f

4. Open Trout

Open http://localhost:3000 in your browser. Create an account and start setting up your budget.

Create categories: Add your expense categories (Rent, Groceries, Transportation) organized into groups.

Add accounts: Create your checking, savings, and credit card accounts with opening balances.

Start budgeting: Assign your available money to categories. The Ready to Assign balance shows what is left.

Backups

Your financial data is in PostgreSQL. Back it up like any Postgres database.

Manual backup
docker exec betterbudget-postgres pg_dump -U budget_user betterbudget > backup.sql

Set up a cron job for daily backups. The Docker volumepostgres_datapersists data across container restarts, but a volume is not a backup.

Updating

Pull the latest code and rebuild. Migrations run automatically on startup.

git pull
docker compose -f docker-compose.production.yml up -d --build

Always back up your database before updating. Migration issues are rare but reversing them is easier with a backup.

Exposing to the internet

By default, Trout is only accessible on your local network. To access it from anywhere, you need a reverse proxy with HTTPS.

Option 1: Reverse proxy (Caddy, Nginx, Traefik) -- Point your domain at your server. Caddy handles HTTPS automatically. Update ALLOWED_ORIGINS, BETTER_AUTH_URL, and NEXT_PUBLIC_API_URL in your .env to use your domain.

Option 2: Tailscale / Cloudflare Tunnel -- Access your home server from anywhere without opening ports. Good for NAS or Raspberry Pi setups where you do not have a static IP.

Get started

Clone, configure, and deploy. Your budget is running in 10 minutes.

View on GitHubSee All Features