Getting Started

Getting Started

This guide walks you through setting up Bill Organizer locally for development or for self-hosting.

---

Prerequisites

Requirement	Minimum Version
PHP	8.3+
Composer	Latest
Node.js	18+
Yarn	Latest
Database	SQLite (default) or MySQL 8.0+
Docker	Optional (for Laravel Sail)

---

Local Development Setup

1. Clone and Install Dependencies

git clone https://github.com/4msar/bill-organizer.git
cd bill-organizer

# Backend dependencies
composer install

# Frontend dependencies
yarn install

2. Environment Configuration

cp .env.example .env
php artisan key:generate

Key environment variables to configure:

APP_NAME="Bill Organizer"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost

# Database (SQLite by default)
DB_CONNECTION=sqlite
DB_DATABASE=/absolute/path/to/database.sqlite

# Mail (log driver for local dev)
MAIL_MAILER=log
MAIL_FROM_ADDRESS="hello@example.com"

# Queue
QUEUE_CONNECTION=database

# API / Sanctum
SANCTUM_STATEFUL_DOMAINS=localhost,localhost:3000,127.0.0.1,127.0.0.1:8000
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8000
API_RATE_LIMIT=60

3. Database Setup

php artisan migrate
php artisan db:seed

4. Start the Development Server

Option A — Individual commands:

# Terminal 1: PHP dev server
php artisan serve

# Terminal 2: Vite frontend
yarn dev

Option B — Concurrent (recommended):

composer run dev

The application will be available at http://localhost:8000.

---

Docker Setup (Laravel Sail)

# Start all containers in detached mode
./vendor/bin/sail up -d

# Run migrations inside the container
./vendor/bin/sail artisan migrate

# Seed the database
./vendor/bin/sail artisan db:seed

Docker port defaults (configurable in .env):

APP_PORT=8500
VITE_PORT=8551
FORWARD_DB_PORT=8536

---

First Steps After Setup

1. Open http://localhost:8000 in your browser.
2. Register a new user account.
3. Create your first team (required before adding bills).
4. Add categories to organize your bills.
5. Create your first bill and set up recurrence if needed.

---

Running Tests

# Run all tests
php artisan test

# Run API tests only
php artisan test tests/Feature/Api

# Run with coverage
php artisan test --coverage

---

Useful Development Commands

# Real-time log tailing
php artisan pail

# Format PHP code
composer run lint

# Format TypeScript/Vue code
yarn lint
yarn format:check

# Clear all caches
php artisan optimize:clear

# Reset database
php artisan migrate:fresh --seed

# Restart queue workers
php artisan queue:restart

# Enable query logging in Tinker
DB::enableQueryLog();
dd(DB::getQueryLog());

---

Next Steps

• Architecture — Understand the system design
• Features — Explore all available features
• API Overview — Start building integrations
• API Setup — Configure and test the API