🚀 Getting Started
Welcome to the FirstBreath development team! This guide will help you set up the entire stack on your local machine in minutes.
Prerequisites
Before starting, ensure you have the following installed:
- Docker & Docker Compose: For container orchestration.
- Node.js (v20+) & Yarn: For frontend/backend tooling.
- Git: For version control.
- (Optional) NVIDIA Drivers: If you plan to run the Vision system with GPU acceleration locally.
1. Clone the Ecosystem using the Platform Repo
We use a Monorepo Wrapper strategy. You don't need to clone each repository individually.
# Clone the main platform wrapper
git clone git@github.com:FirstBreath/FirstBreath-Platform.git
cd FirstBreath-Platform
# Initialize all submodules (Backend, Vision, Frontend)
git submodule update --init --recursive
Always pull the latest changes from submodules using:
git submodule foreach git pull origin main
2. Environment Configuration
The platform comes with a global .env.example file. Copy it to create your local config.
cp .env.example .env
Typically, the default values work out-of-the-box for local development.
3. Run the Stack
We have a unified docker-compose.yml at the root of the Platform repository that orchestrates all sub-services.
# Start everything (Database, Backend, Vision, Frontend)
docker compose up -d
🐢 Standard Mode vs 🐇 GPU Mode
By default, the stack runs in CPU Compatibility Mode.
If you have an NVIDIA GPU configured with nvidia-container-toolkit, you can enable GPU acceleration by uncommenting the deploy: resources: reservations: devices section in docker-compose.yml.
4. Access the Services
Once up, the services are available at:
| Service | URL | Description |
|---|---|---|
| Documentation | http://localhost:3000 | This documentation site |
| Control Hub API | http://localhost:3333 | Backend API & Swagger |
| Showcase App | http://localhost:3001 | Frontend Dashboard |
| Grafana | http://localhost:4000 | Monitoring Dashboards |
| Prometheus | http://localhost:9090 | Metrics Collection |
Troubleshooting
Submodules are empty?
If apps/backend or apps/vision folders are empty, you forgot the submodule init step:
git submodule update --init --recursive
Database Connection Error?
The backend might try to start before MySQL is ready. Docker Compose handles retries, but if it persists, restart the backend:
docker compose restart backend