Skip to content

Local Development Setup

This guide walks you through setting up Colony for local development.

Prerequisites

  • Python 3.13+
  • Node.js 18+
  • Docker and Docker Compose
  • Git

Initial Setup

# Clone the repository
git clone https://github.com/jcarranz97/colony.git
cd colony

# Install pre-commit hooks
pip install pre-commit
pre-commit install

The easiest way to get started is using Docker Compose:

# Start all services
docker-compose up --build

# Or run in detached mode
docker-compose up -d --build

Services Available

  • Frontend: http://localhost:3000
  • Backend API: http://localhost:8000
  • API Documentation: http://localhost:8000/docs
  • ReDoc: http://localhost:8000/redoc

Option 2: Local Development

For development with hot reloading:

Backend Setup

cd backend

# Install dependencies using uv
uv sync

# Run development server
uv run fastapi dev

# For linting and formatting
uv run ruff check . --fix    # Lint and auto-fix issues
uv run ruff format .         # Format code

# Type checking
uv run pyright .

# Run tests
uv run pytest

Managing Dependencies

Adding Dependencies

We use uv for Python package management:

cd backend

# Add a production dependency
uv add fastapi

# Add a development dependency
uv add pytest --dev
uv add ruff --dev

# Add a dependency with version constraints
uv add "fastapi>=0.100.0"

# Add from a specific index or source
uv add requests --index-url https://pypi.org/simple/

Removing Dependencies

# Remove a dependency
uv remove package-name

# Remove a dev dependency
uv remove package-name --dev

Updating Dependencies

# Update all dependencies
uv sync --upgrade

# Update a specific package
uv add package-name --upgrade

# See outdated packages
uv tree --outdated

Installing Dependencies

# Install all dependencies (production + dev)
uv sync

# Install only production dependencies
uv sync --no-dev

# Install and update lock file
uv sync --upgrade

Frontend Setup

cd frontend

# Install dependencies
npm install

# Install development dependencies
npm install --save-dev prettier eslint

# Run development server
npm run dev

Documentation Setup

cd docs

# Install MkDocs Material
pip install mkdocs-material

# Serve documentation
mkdocs serve

Code Quality Setup

# Install pre-commit (if not already done)
pip install pre-commit

# Install git hooks
pre-commit install

# Run on all files (first time)
pre-commit run --all-files

Environment Variables

Create a .env file in the root directory:

# Database
DATABASE_URL=sqlite:///./colony.db

# Security
SECRET_KEY=your-secret-key-here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Development
DEBUG=true

Development Workflow

  1. Make changes to your code
  2. Add dependencies if needed using uv add
  3. Pre-commit hooks will automatically run on commit
  4. Test locally using Docker Compose or individual services
  5. Submit pull request when ready

Next Steps