Skip to content

SETUP.md

Latest commit

 

History

History
643 lines (456 loc) · 11.4 KB

SETUP.md

File metadata and controls

643 lines (456 loc) · 11.4 KB
Raw

Complete Setup Guide - Paintjob

A step-by-step guide to get the Paintjob application running on your machine.

📋 Table of Contents

  1. Prerequisites
  2. Initial Setup
  3. Backend Setup
  4. Frontend Setup
  5. Running the Application
  6. Verification
  7. Troubleshooting
  8. Next Steps

Prerequisites

Required Software

Install these before proceeding:

1. Python 3.11 or higher

# Check if installed
python3 --version

# If not installed:
# Windows: Download from https://www.python.org/downloads/
# macOS: brew install python@3.11
# Linux: sudo apt install python3.11

2. PostgreSQL 14 or higher

# Check if installed
psql --version

# If not installed:
# Windows: Download from https://www.postgresql.org/download/windows/
# macOS: brew install postgresql@14
# Linux: sudo apt install postgresql-14

3. Node.js 18+ and pnpm

# Check Node.js version
node --version

# If not installed:
# Download from https://nodejs.org/ (LTS version)

# Install pnpm globally
npm install -g pnpm

# Verify pnpm
pnpm --version

4. Git

# Check if installed
git --version

# If not installed:
# Download from https://git-scm.com/downloads

Initial Setup

1. Clone the Repository

# Clone the repository
git clone https://github.com/YOUR_USERNAME/paintjob.git

# Navigate to project directory
cd paintjob

2. Check Project Structure

Verify you have both directories:

# You should see:
# - paintjob/        (Backend)
# - paintjob-fe/     (Frontend)
# - README.md
# - CLA.md
# - CONTRIBUTING.md

ls -la

Backend Setup

Step 1: Navigate to Backend Directory

cd paintjob

Step 2: Create Virtual Environment

Why? Virtual environments isolate Python dependencies per project.

# Create virtual environment named 'venv'
python3 -m venv venv

Step 3: Activate Virtual Environment

Windows (PowerShell):

.\venv\Scripts\Activate.ps1

# If you get an execution policy error, run:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
# Then try activating again

Windows (Command Prompt):

.\venv\Scripts\activate.bat

macOS / Linux:

source venv/bin/activate

Verification: Your prompt should now show (venv) at the beginning.

Step 4: Install Poetry

Poetry is a modern Python dependency manager.

# Install poetry
pip install poetry

# Verify installation
poetry --version

Step 5: Install Dependencies with Poetry

# Install all project dependencies
poetry install

# This will install:
# - FastAPI
# - SQLAlchemy
# - PostgreSQL drivers
# - Pytest and testing tools
# - All other backend dependencies

Note: This may take a few minutes on first install.

Step 6: Configure Database

Create PostgreSQL Database

# Start PostgreSQL (if not already running)
# macOS: brew services start postgresql@14
# Linux: sudo systemctl start postgresql
# Windows: PostgreSQL should auto-start

# Connect to PostgreSQL
psql -U postgres

# In PostgreSQL shell, create database:
CREATE DATABASE paintjob;

# Create user (optional, if not using postgres user):
CREATE USER paintjob_user WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE paintjob TO paintjob_user;

# Exit PostgreSQL shell
\q

Step 7: Configure Environment Variables

The .env file should already exist in paintjob/ directory.

Verify it exists:

ls -la .env

If it doesn't exist, create it:

# Create .env file
touch .env

# Or on Windows:
echo. > .env

Edit .env file with your database credentials:

# Database connection string
DATABASE_URL=postgresql+asyncpg://postgres:your_password@localhost:5432/paintjob

# JWT Secret Key (generate a secure random key)
SECRET_KEY=your-super-secret-key-here-change-this-in-production

# JWT Algorithm
ALGORITHM=HS256

# Token expiration (in minutes)
ACCESS_TOKEN_EXPIRE_MINUTES=720

# CORS origins (for frontend)
CORS_ORIGINS=http://localhost:3000

Generate a secure SECRET_KEY:

# Python method
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

# Or use any random string generator

Step 8: Run Database Migrations

Alembic manages database schema migrations.

# Apply all migrations to create tables
alembic upgrade head

# You should see output like:
# INFO  [alembic.runtime.migration] Running upgrade -> e7dabe5987e3, initial
# INFO  [alembic.runtime.migration] Running upgrade e7dabe5987e3 -> ..., ...

Verify tables were created:

psql -U postgres -d paintjob -c "\dt"

# You should see tables:
# - users
# - projects
# - rooms
# - walls

Step 9: Start Backend Server

# Run the FastAPI application
python3 main.py

# You should see:
# INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
# INFO:     Started reloader process
# INFO:     Started server process
# INFO:     Waiting for application startup.
# INFO:     Application startup complete.

Keep this terminal open - the backend is now running.

Step 10: Verify Backend

Open a new terminal and test the API:

# Test health endpoint
curl http://localhost:8000/

# Or open in browser:
# http://localhost:8000/docs (Swagger UI)
# http://localhost:8000/redoc (ReDoc UI)

Frontend Setup

Open a NEW terminal (keep backend running in the first one).

Step 1: Navigate to Frontend Directory

cd paintjob-fe

Step 2: Install Dependencies with pnpm

# Install all dependencies
pnpm install

# This will install:
# - Next.js 15
# - React
# - TypeScript
# - Konva (canvas library)
# - Zustand (state management)
# - shadcn/ui components
# - Tailwind CSS
# - All other frontend dependencies

Note: This may take a few minutes on first install.

Step 3: Configure Environment Variables

The .env.local file should already exist in paintjob-fe/ directory.

Verify it exists:

ls -la .env.local

If it doesn't exist, create it:

# Create .env.local file
touch .env.local

# Or on Windows:
echo. > .env.local

Edit .env.local file:

# Backend API URL
NEXT_PUBLIC_API_URL=http://localhost:8000/api

# Optional: Environment
NEXT_PUBLIC_ENV=development

Step 4: Start Frontend Development Server

# Run Next.js development server
pnpm dev

# You should see:
# ▲ Next.js 15.0.0
# - Local:        http://localhost:3000
# - Ready in X.X seconds

Keep this terminal open - the frontend is now running.

Step 5: Verify Frontend

Open your browser to:

http://localhost:3000

You should see the Paintjob home page.

Running the Application

Summary of Commands

Terminal 1 - Backend:

cd paintjob
source venv/bin/activate  # or .\venv\Scripts\Activate.ps1 on Windows
python3 main.py

Terminal 2 - Frontend:

cd paintjob-fe
pnpm dev

Access Points

Verification

1. Test User Registration

Open http://localhost:3000 and:

  1. Click "Sign Up" or register link
  2. Create a new account
  3. Login with credentials
  4. Verify you're logged in

2. Test Editor

  1. Click "Open Editor"
  2. Create a new project
  3. Add rooms
  4. Add walls
  5. Place windows
  6. Verify all interactions work

3. Test API Directly

# Create a user
curl -X POST http://localhost:8000/api/users/ \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123","full_name":"Test User"}'

# Login
curl -X POST http://localhost:8000/api/users/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123"}'

# Copy the access_token from response and use in next requests

Troubleshooting

Backend Issues

"Database connection failed"

# Check PostgreSQL is running
psql -U postgres -c "SELECT 1;"

# Check DATABASE_URL in .env
cat paintjob/.env | grep DATABASE_URL

# Verify database exists
psql -U postgres -c "SELECT datname FROM pg_database WHERE datname='paintjob';"

"Module not found" errors

# Ensure virtual environment is activated
# You should see (venv) in prompt

# Reinstall dependencies
poetry install

"Port 8000 already in use"

# Find process using port 8000
# Windows:
netstat -ano | findstr :8000

# macOS/Linux:
lsof -ti:8000

# Kill the process
# Windows:
taskkill /PID <PID> /F

# macOS/Linux:
kill -9 <PID>

Frontend Issues

"Port 3000 already in use"

# Run on different port
pnpm dev -- -p 3001

# Or kill process on port 3000
# Windows:
netstat -ano | findstr :3000
taskkill /PID <PID> /F

# macOS/Linux:
lsof -ti:3000 | xargs kill -9

"pnpm not found"

# Install pnpm globally
npm install -g pnpm

# Verify
pnpm --version

"Module not found" errors

# Clear cache and reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install

# Or on Windows:
rmdir /s /q node_modules
del pnpm-lock.yaml
pnpm install

API connection errors in browser

# Check NEXT_PUBLIC_API_URL in .env.local
cat paintjob-fe/.env.local

# Should be: http://localhost:8000/api

# Restart frontend after changing .env.local

General Issues

Python version issues

# Check Python version
python3 --version

# If too old, update Python
# Then recreate virtual environment:
cd paintjob
rm -rf venv
python3 -m venv venv
source venv/bin/activate
poetry install

Permission denied errors

# Windows PowerShell execution policy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# macOS/Linux file permissions
chmod +x <file>

Next Steps

Learn the Codebase

  1. Read API_DOCUMENTATION.md
  2. Read Frontend README
  3. Explore the project structure
  4. Try the example API calls in the docs

Run Tests

# Backend tests
cd paintjob
pytest -v

# See TESTING_GUIDE.md for details

Make Changes

  1. Read CONTRIBUTING.md first
  2. Read and accept CLA.md
  3. Create a feature branch
  4. Make your changes
  5. Test thoroughly
  6. Submit a pull request

Deploy (Future)

Documentation for production deployment coming soon.

Quick Reference

Backend Commands

cd paintjob
source venv/bin/activate
python3 main.py                    # Run server
pytest                             # Run tests
alembic upgrade head               # Run migrations
alembic revision --autogenerate    # Create migration

Frontend Commands

cd paintjob-fe
pnpm dev                           # Run dev server
pnpm build                         # Build for production
pnpm start                         # Run production build
pnpm lint                          # Lint code

Support

If you encounter issues:

  1. Check this guide first
  2. Review the troubleshooting section
  3. Check README.md
  4. Search existing Issues
  5. Open a new issue with detailed information

Setup Complete! 🎉

You're now ready to start using and developing Paintjob!

Last Updated: October 5, 2025