Skip to content

Developer Setup Guide

Jump to bottom
jairomelo edited this page Jan 11, 2026 · 3 revisions

This guide provides step-by-step instructions to set up the development environment for the Digitization Toolkit project. The purpose is to ensure consistency across development environments and streamline the onboarding process for new contributors.

Required Software:

Core tools needed, regardless of OS:

  • Git
    • Check if Git is installed by running git --version in your terminal.
    • If not installed, follow the instructions for your OS:
      • macOS: brew install git (or Xcode command line tools)
      • Windows: Download and install from the official Git website
      • Linux (Debian and Derivatives): sudo apt install git
  • Docker Desktop
    • macOS: Download from Docker's official site
    • Windows: Download from Docker's official site
    • Linux: Install Docker Engine (curl -fsSL https://get.docker.com | sh) and docker compose plugin.
    • After install: Run docker --version and docker compose version to verify installation.

Docker images contain all necessary dependencies (even Node and Python), so no additional installations are needed.

Cloning the Repository

When cloning the repository, ensure you include submodules:

git clone --recurse-submodules git@github.com:UCSB-AMPLab/digitization-toolkit-software.git
cd digitization-toolkit-software

Verify you have this structure:

.
├── backend # FastAPI backend
├── docker-compose.yml
├── docs
├── frontend # Svelte frontend
├── LICENSE
├── README.md
└── wiki

Start the Services

The toolkit uses a hybrid architecture:

  • Database + Frontend: Run in Docker containers
  • Backend: Run natively on Raspberry Pi (for camera access) or in Docker (for development)

Option 1: Development Mode (No Cameras)

From the root of the repository, run:

docker compose --profile with-backend up --build

This will:

  • Build the database service (PostgreSQL, port 5432)
  • Build the backend service (FastAPI + Uvicorn, port 8000)
  • Build the frontend service (SvelteKit + Vite, port 5173)
  • Mount your local code inside the containers for live reloading

Option 2: Raspberry Pi Mode (With Cameras)

Start the database and frontend:

docker compose up -d

In a separate terminal, start the native backend:

./scripts/run_backend_native.sh

The script will:

  • Activate the Python virtual environment
  • Verify database connectivity
  • Detect available cameras
  • Start the FastAPI backend with hot-reload

Why native? Camera access requires Raspberry Pi-specific system libraries (libcamera, picamera2, pykms) that are difficult to replicate in Docker.

Verify Backend

Open your browser and navigate to http://localhost:8000/health. You should see:

{"status": "ok"}

Verify Frontend

Open your browser and navigate to http://localhost:5173. You should expect to see:

Digitization Toolkit
API says: ok

Common Issues

  • Port already in use: If ports 5432, 8000, or 5173 are occupied, stop the conflicting services or change the ports in docker-compose.yml.
  • "API says: unavailable": The frontend briefly shows this during SSR before client-side hydration. This is normal. If it persists:
    • Check backend is running: curl http://localhost:8000/health
    • Verify DATABASE_HOST in .env matches your setup (localhost for native, db for Docker)
  • Camera not detected: Camera access requires the native backend on Raspberry Pi. Docker backend cannot access cameras.
  • Hot reloading not working: Restart the containers:
docker compose down && docker compose up --build

For native backend:

# Stop with Ctrl+C, then restart
./scripts/run_backend_native.sh

Shut Everything Down

When you're done coding, stop the containers with:

docker compose down

You can also use the GUI in Docker Desktop to stop/start containers.

Clone this wiki locally