README_DOCKER.md

🚗 Safe Driving Assistant — Docker Integration Guide

Welcome to the premium Docker integration guide for your Safe Driving Assistant. This guide provides step-by-step instructions on how to package, configure, build, and run the assistant inside a fully isolated, headless-capable Docker container.

The containerized environment includes all C/C++ libraries, graphics backends, sound drivers, and speech synthesizers, pre-configured with a virtual framebuffer (Xvfb) to prevent OpenCV graphical crashes.

---

🌟 Highlights of the Docker Configuration

• Zero-Dependency Setup: No need to install dlib, cmake, opencv, or pyaudio manually on your host machine.
• Virtual Framebuffer (Xvfb): Headless-safe. If no display is detected, it automatically spawns a virtual X11 server so that cv2.imshow calls do not crash.
• Dynamic Network Routing: Pre-configured to easily bridge to your local Ollama SLM instance.
• Unified Sound Backend: Installs PulseAudio, ALSA, and espeak dependencies required for speech synthesis and playback.
• Environment-Driven Configuration: Highly customizable via environment variables (FLASK_HOST, CAMERA_ID, OLLAMA_API_URL, etc.).

---

🛠️ Step 1: Build the Docker Image

Open your terminal in the project directory (Safe Driving Assistant) and run the following command to build your custom co-pilot image:

docker build -t safe-driving-assistant:latest .

This compilation will take several minutes during the first run because it builds dlib (facial recognition) and compiles native C extensions.

---

🚀 Step 2: Run the Docker Container

Depending on your host Operating System and hardware setup, select one of the premium run configurations below:

Option A: Standard Headless / Web-HUD Only (Recommended)

This runs the assistant, serves the live futuristic Web-HUD on port 5000, and bridges network queries to your host's local Ollama service.

docker run -d \
  --name driving_assistant \
  --add-host=host.docker.internal:host-gateway \
  -e OLLAMA_API_URL="http://host.docker.internal:11434/api/generate" \
  -p 5000:5000 \
  safe-driving-assistant:latest

• Web Dashboard: Once started, open your browser and navigate to http://localhost:5000 to view the live dashboard!
• How it works: The container runs headlessly. Face recognition and eye-aspect ratio tracking are active, and the live stream is pushed directly to the dashboard.

---

Option B: Linux Run with Full Hardware Passthrough (Camera & Audio)

If you are running native Linux and want the container to access your physical USB webcam and audio hardware directly, run:

docker run -it \
  --name driving_assistant \
  --device /dev/video0:/dev/video0 \
  --device /dev/snd:/dev/snd \
  --add-host=host.docker.internal:host-gateway \
  -e CAMERA_ID=0 \
  -e OLLAMA_API_URL="http://host.docker.internal:11434/api/generate" \
  -p 5000:5000 \
  safe-driving-assistant:latest

• --device /dev/video0: Mounts your primary webcam inside the container.
• --device /dev/snd: Exposes speaker and mic controls.

---

Option C: Windows Host (WSL2) with Web USB Webcam Passthrough

If you are using WSL2 on Windows and want to feed your physical webcam into the Docker container:

1. Bind your USB camera to WSL2 using usbipd-win:

   usbipd list
   usbipd bind --busid <BUSID>
   usbipd attach --wsl --busid <BUSID>
   

2. Start the container with device mapping:

   docker run -it \
     --name driving_assistant \
     --device /dev/video0:/dev/video0 \
     --add-host=host.docker.internal:host-gateway \
     -e CAMERA_ID=0 \
     -e OLLAMA_API_URL="http://host.docker.internal:11434/api/generate" \
     -p 5000:5000 \
     safe-driving-assistant:latest
   

---

⚙️ Environment Variables Customization

You can dynamically tune your assistant container at runtime by passing -e KEY=VALUE parameters to docker run:

Variable Name	Default Value	Description
FLASK_HOST	0.0.0.0	Binding IP address for Flask web dashboard.
FLASK_PORT	5000	Port on which the web HUD dashboard will be served.
CAMERA_ID	0	Camera index.
OLLAMA_API_URL	http://localhost:11434/api/generate	The API endpoint for the Ollama voice co-pilot. Use http://host.docker.internal:11434/api/generate for bridging to host.
OLLAMA_MODEL	drivesafe	Name of the custom SLM model configured inside Ollama.
FRAME_WIDTH	640	Video frame capture width.
FRAME_HEIGHT	480	Video frame capture height.

---

🧼 Housekeeping & Diagnostics

View Real-Time Logs

To see the system warnings, detected EAR, and conversational chatbot interactions:

docker logs -f driving_assistant

Stop & Remove Container

To stop and clean up the assistant container instance:

docker stop driving_assistant
docker rm driving_assistant

---

Safe Driving Assistant — Keep your eyes on the road, your hands on the wheel, and drive safely! 🚗💨