Development Setup

This page describes how to set up a local development environment for contributing to Lineo-PM.

Prerequisites

• Docker v24+
• Docker Compose v2
• Git
• A code editor (VS Code recommended)

No other local dependencies are required — Python, Node.js, and PostgreSQL all run inside Docker containers.

1. Clone the Repository

git clone https://github.com/your-org/lineo-pm.git
cd lineo-pm

2. Start the Development Stack

docker compose -f docker-compose.dev.yml up -d --build

This builds and starts all services:

The Vite dev server supports hot module replacement (HMR) — frontend changes are reflected in the browser immediately without a container rebuild. Backend code changes require restarting the backend container.

3. Stopping the Stack

docker compose -f docker-compose.dev.yml down

For a full reset (including database data):

docker compose -f docker-compose.dev.yml down -v

Branch Strategy

Never commit directly to main. All development work goes through dev.

Development Workflow

1. Branch from dev:

   git checkout dev
   git pull origin dev
   git checkout -b feature/your-feature-name

2. Make changes — implement your feature or fix

3. Test locally — make sure the stack runs and the feature works end-to-end

4. Open a pull request against dev — not main

5. Keep PRs small and focused — one concern per pull request makes review faster and easier

Backend Development

Backend source code lives in backend/src/. The FastAPI application auto-reloads on code changes when running in development mode. If you add new dependencies, update backend/pyproject.toml and rebuild the container:

docker compose -f docker-compose.dev.yml build backend
docker compose -f docker-compose.dev.yml up -d backend

Database Migrations

When you change ORM models, generate a new Alembic migration:

docker compose -f docker-compose.dev.yml exec backend alembic revision --autogenerate -m "description"
docker compose -f docker-compose.dev.yml exec backend alembic upgrade head

Frontend Development

Frontend source code lives in frontend/src/. Changes are picked up automatically by the Vite HMR server inside the container — no rebuild needed.

If you add new npm dependencies, update frontend/package.json and rebuild the frontend container:

docker compose -f docker-compose.dev.yml build frontend
docker compose -f docker-compose.dev.yml up -d frontend