Quick Start Guide

This guide gets you up and running with the Personal Finance Platform quickly.

Note

This is a quick reference. For detailed installation and configuration, see the respective sections.

Prerequisites

  • Python 3.10 – 3.13 with pip

  • PostgreSQL (optional; falls back to SQLite)

  • Redis (required for Celery, optional for simple local runs)

  • Docker + Docker Compose (optional, but recommended for parity)

Local Development Setup

  1. Clone and Environment Setup

    git clone https://github.com/MauGx3/personal-finance.git
cd personal-finance
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

  2. Install Dependencies

    python -m pip install --upgrade pip
pip install -r requirements.txt
pip install -r requirements-dev.txt

  3. Configure Environment

    cp .env.example .env
# Edit .env to set DATABASE_URL, REDIS_URL, DJANGO_SECRET_KEY, etc.

  4. Initialize Database

    python manage.py migrate
python manage.py collectstatic --noinput

  5. Start Development Server

    python manage.py runserver

Docker Compose Setup

For a complete development environment:

just up          # or: docker compose -f docker-compose.local.yml up -d
just logs django # view container logs
just down        # or: docker compose down

Essential Commands

# Django management
python manage.py check                    # Validate configuration
python manage.py shell                    # Interactive shell
python manage.py createsuperuser          # Create admin user

# Database operations
python manage.py makemigrations           # Create migrations
python manage.py migrate                  # Apply migrations
alembic upgrade head                      # Apply Alembic migrations

# Background services
celery -A config worker -l info           # Start Celery worker
python run_finance.py                     # Run ETL/backtesting

# Quality checks
pytest -q                                 # Run tests
ruff check .                              # Lint code
black .                                   # Format code

Next Steps

  • installation - Detailed installation instructions

  • configuration - Environment and configuration reference

  • development/setup - Complete development environment setup

  • deployment/docker - Production deployment with Docker