Skip to main content

Development Commands

Reference guide for common development tasks and commands.

Running the Application​

Start API Server​

# Development mode with auto-reload
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Using helper script
bash scripts/run_dev.sh

# Production mode (no reload)
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000

Access Points:

Start Celery Worker​

# Standard worker
uv run celery -A app.celery_app worker --loglevel=info

# Using helper script
bash scripts/start_celery_worker.sh

# With debug logging
uv run celery -A app.celery_app worker --loglevel=debug

# With specific concurrency
uv run celery -A app.celery_app worker --concurrency=4

Start Both API and Worker​

# Terminal 1: API
bash scripts/run_dev.sh

# Terminal 2: Celery Worker
bash scripts/start_celery_worker.sh

Database Operations​

Migrations​

# Apply all pending migrations
uv run alembic upgrade head

# Create new migration
uv run alembic revision --autogenerate -m "Add user email index"

# Rollback last migration
uv run alembic downgrade -1

# Rollback to specific version
uv run alembic downgrade abc123

# View migration history
uv run alembic history

# View current version
uv run alembic current

# Show SQL for migration (don't execute)
uv run alembic upgrade head --sql

Code Quality​

Linting and Formatting​

# Format code (modify files)
uv run ruff format .

# Format specific file or directory
uv run ruff format app/models/

# Check formatting without modifying
uv run ruff format --check .

# Lint code (show issues)
uv run ruff check .

# Lint with auto-fix
uv run ruff check --fix .

# Lint specific file
uv run ruff check app/api/v1/uploads.py

Ruff Configuration​

Located in pyproject.toml:

[tool.ruff]
line-length = 100
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I"]  # pycodestyle, pyflakes, isort
ignore = ["E501"]  # Line too long

Dependency Management​

Installing Dependencies​

# Install all dependencies
uv sync

# Install with all optional groups
uv sync --all-groups

# Install without dev dependencies
uv sync --no-dev

# Force reinstall
uv sync --force

Adding Dependencies​

# Add package
uv add fastapi

# Add dev dependency
uv add --dev pytest

# Add with version constraint
uv add "sqlalchemy>=2.0,<3.0"

# Add from git
uv add git+https://github.com/user/repo.git

Updating Dependencies​

# Update all dependencies
uv lock --upgrade

# Update and install
uv lock --upgrade && uv sync

# Update specific package
uv add fastapi --upgrade

Remove Dependencies​

# Remove package
uv remove package-name

Documentation Site​

Development​

cd docs

# Install dependencies (first time)
npm install

# Start dev server with API docs generation
npm start

# Build for production
npm run build

# Serve production build
npm run serve

Maintenance​

# Clear cache
npm run clear

# Type check
npm run typecheck

# Clean and rebuild
npm run clear && npm run build

Docker Operations​

Service Management​

# Start all services
docker compose -f docker-compose.dev.yml up -d

# Start specific services
docker compose -f docker-compose.dev.yml up -d postgres redis

# Stop services (keep data)
docker compose -f docker-compose.dev.yml stop

# Stop and remove containers
docker compose -f docker-compose.dev.yml down

# Stop and remove volumes (DELETE DATA)
docker compose -f docker-compose.dev.yml down -v

# Restart services
docker compose -f docker-compose.dev.yml restart

# Restart specific service
docker compose -f docker-compose.dev.yml restart postgres

Service Logs​

# View all logs
docker compose -f docker-compose.dev.yml logs -f

# View specific service
docker compose -f docker-compose.dev.yml logs -f postgres

# Last 100 lines
docker compose -f docker-compose.dev.yml logs --tail=100 postgres

Service Status​

# Check running services
docker compose -f docker-compose.dev.yml ps

# Check service health
docker compose -f docker-compose.dev.yml exec postgres pg_isready
docker compose -f docker-compose.dev.yml exec redis redis-cli ping

Celery Operations​

Task Management​

# List registered tasks
uv run celery -A app.celery_app inspect registered

# View active tasks
uv run celery -A app.celery_app inspect active

# View scheduled tasks
uv run celery -A app.celery_app inspect scheduled

# Purge all tasks
uv run celery -A app.celery_app purge

Worker Control​

# Shutdown worker
uv run celery -A app.celery_app control shutdown

# Worker statistics
uv run celery -A app.celery_app inspect stats

# View worker pool settings
uv run celery -A app.celery_app inspect pool

Next Steps​