Skip to main content

​
Prerequisites

Before starting, ensure you have:
  • Docker and Docker Compose installed on your machine
  • A Google Cloud project with Gmail API enabled (for Gmail integration)
  • An xAI API key (for transaction extraction)
  • A Supabase account (optional for production; local stack works out of the box)
No local installation of Bun or Supabase CLI is required. Everything runs inside Docker containers.

​
Installation

1

Clone the repository

git clone https://github.com/yourusername/money-tracker.git
cd money-tracker
2

Create environment files

Copy the example environment files:
cp packages/frontend/.env.example packages/frontend/.env
cp supabase/functions/.env.example supabase/functions/.env
3

Configure frontend environment

Edit packages/frontend/.env:
# Supabase Configuration
SUPABASE_URL=http://127.0.0.1:54321
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0

# Frontend server
PORT=3000

# Optional (used by E2E tests)
XAI_API_KEY=
The SUPABASE_ANON_KEY above is the default key for local Supabase. Don’t change it for local development.
4

Configure Edge Functions environment

Edit supabase/functions/.env with your actual credentials:
# Supabase Configuration
SUPABASE_URL=http://host.docker.internal:54321
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImV4cCI6MTk4MzgxMjk5Nn0.EGIM96RAZx35lJzdJsyH-qQwv8Hdp7fsn3W0YpN81IU
FRONTEND_URL=http://localhost:3000

# Google OAuth Configuration
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
OAUTH_REDIRECT_URI=http://localhost:3000/auth/callback
GOOGLE_PROJECT_ID=your_google_project_id
PUBSUB_TOPIC=gmail-notifications

# AI Configuration
XAI_API_KEY=your_xai_api_key_here

# Langfuse Configuration (optional for development)
LANGFUSE_SECRET_KEY=
LANGFUSE_PUBLIC_KEY=
LANGFUSE_BASE_URL=https://cloud.langfuse.com

# CORS Configuration
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
CORS_ALLOW_CREDENTIALS=false

# Internal functions secret
INTERNAL_FUNCTIONS_SECRET=local-dev-internal-secret

# Environment
ENVIRONMENT=development
You must replace GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_PROJECT_ID, and XAI_API_KEY with your actual credentials.
5

Start the application

Run the application using Docker Compose:
PROJECT_ROOT=$(pwd) docker compose up --build
This starts:
  • Frontend with hot reload at http://localhost:3000
  • Supabase local stack (PostgreSQL, Auth, Edge Functions, Studio)
The first startup may take a few minutes as Docker downloads images and builds containers.
6

Access the application

Once running, open your browser to:
The local database is automatically seeded with a test account:

​
Connecting Your Gmail Account

After logging in, connect your Gmail to start tracking real transactions:
1

Navigate to Settings

Click on the Settings icon in the sidebar or press Cmd/Ctrl + K and search for “Settings”.
2

Connect Gmail Account

Click the “Connect Gmail Account” button. This will redirect you to Google’s OAuth consent screen.
3

Authorize access

Grant Money Tracker read-only access to your Gmail. The app will never modify or delete your emails.
4

Wait for initial import

After authorization, Money Tracker automatically starts importing the last 3 months of emails. This process runs in the background and may take a few minutes depending on your email volume.You’ll see a progress indicator showing how many emails have been processed.
5

Check your transactions

Navigate to the Transactions page to see automatically extracted transactions from your emails.
The initial import processes 30 emails at a time with 10 concurrent AI extractions per batch. Processed emails are tracked in the database, so you can safely stop and resume the import.

​
Processing Your First Transaction

To test the AI extraction manually:
1

Upload a receipt

On the Transactions page, click the “Upload Document” button.
2

Select a file

Choose a receipt image (JPG, PNG) or PDF invoice from your computer.
3

Wait for AI extraction

The document is sent to xAI Grok for analysis. Within a few seconds, the transaction details are extracted and displayed.
4

Review and save

Check the extracted amount, merchant, category, and date. Edit if needed, then save the transaction.

​
Database Commands

​
Reset the database

Apply all migrations and reseed the database: 
PROJECT_ROOT=$(pwd) docker compose run --rm supabase-cli sh -lc "supabase start && supabase db reset --local"
Or use the npm script: 
bun run docker:db:reset

​
Apply pending migrations

PROJECT_ROOT=$(pwd) docker compose run --rm supabase-cli sh -lc "supabase start && supabase migration up --include-all --local"
Or: 
bun run docker:db:migration:up

​
Generate TypeScript types

Generate types from the database schema: 
PROJECT_ROOT=$(pwd) docker compose run --rm supabase-cli sh -lc "supabase start && supabase gen types typescript --local > packages/frontend/src/types/database.types.ts"
Or: 
bun run docker:db:types

​
Seed Data

The local database includes test data for development:
FileDescription
001_auth_test_user.sqlCreates test account [email protected] / password123
002_transactions_test_user.sqlInserts 132 demo transactions
005_internal_functions_secret_local.sqlSets up local Vault secret
Seeds run automatically when you reset the database.

​
Stopping the Application

To stop all services: 
PROJECT_ROOT=$(pwd) docker compose down
Or use the npm script: 
bun run docker:down

​
Troubleshooting

​
Frontend fails to load

  • Verify packages/frontend/.env exists and contains valid SUPABASE_URL and SUPABASE_ANON_KEY
  • Check frontend logs: docker compose logs -f frontend
  • Ensure Supabase is running: docker compose ps

​
Gmail OAuth fails

  • Verify your Google Cloud project has the Gmail API enabled
  • Check that GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and OAUTH_REDIRECT_URI match your Google Cloud Console settings
  • Ensure the redirect URI is added to the authorized redirect URIs in Google Cloud Console

​
AI extraction fails

  • Verify your XAI_API_KEY is valid and has credits
  • Check Edge Function logs: docker compose logs -f supabase-cli
  • Test the API key with a simple curl request to xAI

​
Docker issues on macOS/Linux

  • Always include PROJECT_ROOT=$(pwd) when running Docker Compose commands
  • This ensures host and container paths match for nested Docker mounts
  • Use service names (e.g., frontend, supabase-cli) with docker compose exec, not container names

​
Database connection errors

  • Ensure Supabase services are healthy: docker compose ps
  • Check if port 54321 is available: lsof -i :54321
  • Restart the Supabase stack: docker compose restart supabase-cli

​
Advanced Usage

​
Access Supabase CLI container

Enter the container for manual commands: 
PROJECT_ROOT=$(pwd) docker compose exec supabase-cli sh
Inside, you have full access to the Supabase CLI: 
supabase status
supabase db diff
supabase functions deploy

​
Stream logs

Watch real-time logs: 
# Frontend logs
docker compose logs -f frontend

# Supabase logs (Edge Functions)
docker compose logs -f supabase-cli

# All logs
docker compose logs -f

​
Next Steps

Architecture

Understand how Money Tracker works

Core Features

Explore all features of Money Tracker

Build docs developers (and LLMs) love

Get started for freeTalk to us