Installation Guide

Installation Guide: Getting MahaTraffic Running on Your Laptop

Set aside about 30 minutes. Most of that is waiting for pip and copying a big folder. Let's go step by step.

Prerequisites

• Python 3.10.11 from python.org. Not 2.7, and avoid 3.13 because some ML libraries lag behind. On Windows, tick "Add Python to PATH" during installation.
• pip, which comes with Python
• At least 3 GB of free disk space for the model artifacts and libraries
• A code editor like VS Code
• Docker Desktop only if you want the Docker route (optional)

Step-by-Step Setup

1. Place the ML artifacts. Download artifacts.zip, extract it, and put the artifacts folder inside mahatraffic/ml/. The final path must look like mahatraffic/ml/artifacts/models/. Double-check this. It's the number one reason the app fails.

2. Open a terminal in the project folder.

   cd mahatraffic

3. Create and activate a virtual environment.

   python -m venv venv
   
   # Windows
   venv\Scripts\activate
   
   # macOS / Linux
   source venv/bin/activate

   You should see (venv) at the start of your terminal line. If you don't, it isn't activated.

4. Install the dependencies.

   pip install -r requirements.txt
   pip install ultralytics

   The second one is for YOLOv8 vehicle detection. It's a big download, so give it a few minutes.

5. Set up the environment file.

   # Windows
   copy .env.example .env
   
   # macOS / Linux
   cp .env.example .env

   You can leave TOMTOM_API_KEY and ORS_API_KEY empty. The app runs in simulated mode without them. Add an ORS key later if you want the route planner working.

6. Prepare the database and data, in this exact order.

   python manage.py migrate
   python manage.py seed_from_artifacts
   python manage.py create_superuser_fixture
   python manage.py run_predictions
   python manage.py collectstatic --noinput

   The seed command loads 16 Pune intersections and 35 days of traffic history. The predictions command then fills in tomorrow's forecast for every junction.

7. Start the server.

   python manage.py runserver

   Open http://localhost:8000 in your browser and log in with admin / admin123.

Optional: Run with Docker

docker compose up --build

Then open http://localhost. Docker handles migrations, seeding and static files for you, but the artifacts folder still needs to be in place first.

Common Issues and Fixes

• Model registry error or missing BEST_classifier.pkl: your artifacts folder is in the wrong place, usually nested one level too deep like ml/artifacts/artifacts/models. Fix the path, then run python manage.py check_deploy to confirm.
• InsufficientHistoryError when running predictions: the model needs at least 21 days of history and the seed step didn't run. Run seed_from_artifacts again. It's safe to run twice.
• Vehicle detection hangs on the first upload: YOLOv8 is downloading yolov8n.pt (about 6 MB) in the background. Pre-download it with python -c "from ultralytics import YOLO; YOLO('yolov8n.pt')".
• PowerShell refuses to activate the venv: run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once, then activate again.
• Map markers stop updating or emergencies don't broadcast: you're probably running more than one worker process. Use a single server process only.

How to Verify It's Working

1. The dashboard at /dashboard/ shows summary cards, a volume trend chart and a congestion doughnut.
2. The map at /map/ shows 16 coloured markers across Pune. Click one and you'll see its prediction.
3. Upload any road photo on /vision/. You should get an annotated image with vehicle counts.
4. Open the app in two browser windows, report an emergency in one, and watch it appear in the other.
5. Run the tests: python -m pytest tests/ -v. All 8 should pass.

If all five check out, you're ready for your demo.