usda-vision/README.md

USDA Vision

A unified monorepo combining the camera API service and the web dashboard for USDA vision experiments.

Project Structure

• camera-management-api/ - Python API service for camera management (USDA-Vision-Cameras)
• management-dashboard-web-app/ - React web dashboard for experiment management (pecan_experiments)
• supabase/ - Database configuration, migrations, and seed data (shared infrastructure)

Quick Start

Production Mode (Docker Compose)

Recommended: Use the docker-compose.sh wrapper script which automatically detects your host IP and sets all environment variables:

./docker-compose.sh up --build -d

The wrapper script automatically:

• Detects your host machine's IP address
• Sets all required environment variables (VITE_*, HOST_SITE_URL, etc.)
• Generates/updates the .env file
• Runs docker-compose with your arguments

Alternative: If you prefer to use docker compose directly, the .env file will be auto-generated on first run, or you can set environment variables manually.

For more details, see Docker Compose Environment Setup.

• Web: http://localhost:5173
• API: http://localhost:8000
• MQTT broker: localhost:1883

To stop: docker compose down

Development Mode (Recommended for Development)

For development with live logging, debugging, and hot reloading:

1. Copy env template and set values (for web/Supabase):

cp .env.example .env
# set VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY in .env

2. Start the development environment:

./dev-start.sh

This will:

• Start containers with debug logging enabled
• Enable hot reloading for both API and web services
• Show all logs in real-time
• Keep containers running for debugging

Development URLs:

• Web: http://localhost:8080 (with hot reloading)
• API: http://localhost:8000 (with debug logging)

Development Commands:

• ./dev-start.sh - Start development environment
• ./dev-stop.sh - Stop development environment
• ./dev-logs.sh - View logs (use -f to follow, -t N for last N lines)
• ./dev-logs.sh -f api - Follow API logs only
• ./dev-logs.sh -f web - Follow web logs only
• ./dev-shell.sh - Open shell in API container
• ./dev-shell.sh web - Open shell in web container

Debug Features:

• API runs with --debug --verbose flags for maximum logging
• Web runs with Vite dev server for hot reloading
• All containers have stdin_open: true and tty: true for debugging
• Environment variables set for development mode

Services

API Service (Port 8000)

• Camera management endpoints
• Video recording controls
• File management

Web Dashboard (Port 5173)

• User authentication via Supabase
• Experiment definition and management
• Camera control interface
• Video playback and analysis

MQTT Broker (Port 1883)

• Local Mosquitto broker for development and integration testing

Git Subtree Workflow

This repo vendors two upstream projects using git subtree, preserving their histories under camera-management-api/ and management-dashboard-web-app/.

Configured remotes:

• cameras → https://github.com/salirezav/USDA-Vision-Cameras.git (branch: master)
• web-origin → https://github.com/salirezav/pecan_experiments.git (branch: master)

Pull latest upstream changes into subtrees:

# API (USDA-Vision-Cameras)
git subtree pull --prefix=camera-management-api cameras master

# Web (pecan_experiments)
git subtree pull --prefix=management-dashboard-web-app web-origin master

Push your changes back upstream (optional):

# API (push changes made under camera-management-api/ back to USDA-Vision-Cameras)
git subtree push --prefix=camera-management-api cameras master

# Web (push changes made under management-dashboard-web-app/ back to pecan_experiments)
git subtree push --prefix=management-dashboard-web-app web-origin master

Notes:

• Subtrees keep a single working copy with full history; no submodule init/update required.
• If you prefer a lighter top-level history, you can use --squash when adding/pulling, but pushing back becomes trickier.

Development Tips

• API

  • Code lives under camera-management-api/. The compose service runs the full system via python main.py --config config.compose.json.
  • Camera SDK access from inside Docker on Windows may be limited; for hardware work you might run the API directly on the host.
  • Configuration: camera-management-api/config.json (see camera-management-api/docs for details).
  • Storage (recordings) is mapped to camera-management-api/storage/ and ignored by git.

• Web

  • Code lives under management-dashboard-web-app/ with a Vite dev server on port 5173.
  • Environment: set VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY in .env (not committed).
  • Common scripts: npm run dev, npm run build (executed inside the container by compose).

Troubleshooting

• Port already in use: change the mapped ports in docker-compose.yml or stop the conflicting process.
• File watching issues on Docker Desktop: CHOKIDAR_USEPOLLING=true is already set for the web container.
• API not starting: check container logs and verify Python deps (compose installs from requirements.txt or pyproject.toml).