docs: How to run BAIO with Docker (step-by-step guide) #178

Overview

This issue documents the exact steps to run the full BAIO stack (backend API + frontend) using Docker Compose. Use this as a reference until the README Docker section is expanded.

Prerequisites

Before you begin, make sure the following are installed and running:

Important: Docker Desktop must be open and running before you execute any docker commands. Look for the whale icon in your menu bar (macOS) or system tray (Windows) — it should say "Docker Desktop is running."

Step-by-Step Instructions

1. Clone the repository

git clone https://github.com/oss-slu/baio.git
cd baio

2. Create your .env file

BAIO needs a Google Gemini API key for the AI assistant feature.

1. Go to https://makersuite.google.com/app/apikey and create a free API key
2. In the baio/ root folder, create a file named .env:

echo "GOOGLE_API_KEY=your_actual_key_here" > .env

Replace your_actual_key_here with the key you copied. The .env file must be in the root baio/ folder (same level as docker-compose.yml).

3. Build and start the containers

docker compose up --build

The first run downloads base images and installs all dependencies — this can take 5–15 minutes depending on your internet speed. Subsequent runs are much faster.

4. Confirm the services are up

Wait until you see output like:

baio-api       | INFO:     Uvicorn running on http://0.0.0.0:8080
baio-frontend  | ...

Then open your browser:

5. Stop the app

Press Ctrl + C in the terminal, then run:

docker compose down

Optional: Run in the background

To start the stack detached (no terminal output):

docker compose up -d --build

To check container status:

docker compose ps

To view logs:

docker compose logs -f

To stop:

docker compose down

Common Issues & Fixes

Docker Desktop is not running

Symptom: Cannot connect to the Docker daemon error
Fix: Open Docker Desktop and wait for it to fully start before running any commands.

Port 8080 or 4173 already in use

Symptom: Bind for 0.0.0.0:8080 failed: port is already allocated
Fix (macOS):

lsof -i :8080
kill -9 <PID>

Fix (Windows Git Bash):

netstat -ano | grep 8080
taskkill /PID <PID> /F

Build fails with dependency errors

Fix: Clear Docker cache and rebuild from scratch:

docker system prune -a
docker compose up --build

Frontend shows "Cannot connect to API"

Symptom: The frontend loads but classification fails
Fix: Check that the baio-api container is healthy:

docker compose ps

If it shows unhealthy, check its logs:

docker compose logs api

.env file not found / Gemini chat not working

Fix: Make sure the .env file exists in the root baio/ folder (not inside backend/ or frontend/):

ls -la .env

Notes

• The backend healthcheck runs every 30 seconds at http://localhost:8080/health. The frontend container will not start until the API passes its healthcheck.
• Data is persisted in Docker volumes (runs_data, weights_data) so it survives container restarts. To wipe all data: docker compose down -v