8e7b5b054f
- Introduced `dev-start.sh`, `dev-stop.sh`, `dev-logs.sh`, and `dev-shell.sh` for managing the development environment. - Added `docker-compose.dev.yml` to define services for API and web applications with appropriate configurations. - Updated `README.md` to include instructions for development mode and commands for managing the environment.
146 lines
4.6 KiB
Markdown
146 lines
4.6 KiB
Markdown
# 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)
|
|
|
|
## Quick Start
|
|
|
|
### Production Mode (Docker Compose)
|
|
|
|
1) Copy env template and set values (for web/Supabase):
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# set VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY in .env
|
|
```
|
|
|
|
2) Start the stack:
|
|
|
|
```bash
|
|
docker compose up --build
|
|
```
|
|
|
|
- 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):
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# set VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY in .env
|
|
```
|
|
|
|
2) Start the development environment:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
# 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):
|
|
|
|
```bash
|
|
# 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`).
|