Deployment

Introduction & motivation

Artificial intelligence tools are far more woven into daily life today than they were a decade ago. That shift comes down to advancements in the field, and to software and hardware being built with the user placed at the centre of it all. As more solutions reach the market, the goal stays consistent: take a cumbersome task and make it bearable.

The pattern repeats across every example: powerful algorithms only matter once they reach the end user with keen, strategic execution. Get that right and the ripple effects follow — high adoption and engagement, organic growth in the user base, minimised training requirements, long-term loyalty, and sensitive data that stays protected along the way.

The build: people counting with YOLO

Today's project: a simple web application that uses a camera and YOLOv11n to count people through an entrance point in real time.

How the pieces fit together

Before touching any prompts, it's worth seeing the full picture: what runs where, and how the pieces talk to each other once everything is deployed.

Local webcam vs. a webcam once it's deployed

The local-dev prompt below asks for a backend that opens the webcam itself (cv2.VideoCapture). That's correct for testing on your own laptop — but once the backend moves to a Hugging Face Space, it's running on a remote server with no physical webcam attached. cv2.VideoCapture(0) in the cloud has no camera to open.

Finding the right camera index

The frontend spec asks for a dropdown to pick a camera index (0, 1, 2). To find out which index corresponds to which physical camera on your machine, run a short script rather than guessing:

import cv2

for i in range(5):
    cap = cv2.VideoCapture(i)
    if cap.isOpened():
        print(f"Camera index {i} is available")
        cap.release()
    else:
        print(f"Camera index {i} is not available")

Run it with python find_camera.py. Built-in laptop webcams are usually index 0; a plugged-in USB webcam often shows up at 1 or higher — but this varies by OS and by what else is plugged in, so testing beats assuming.

Setting up your tools

Before writing a single prompt, get your local machine ready: Cursor, Python, Node.js/npm, and Git.

Installing Cursor

Cursor is a fork of VS Code with AI features built in, and it runs on Windows, macOS, and Linux.

chmod +x cursor-*.AppImage
./cursor-*.AppImage

Installing Python

The backend (FastAPI + YOLO) runs on Python. Version 3.10 or newer is recommended for compatibility with recent Ultralytics releases.

sudo apt install python3 python3-pip python3-venv

Verify: python --version (or python3 --version on macOS/Linux) and pip --version should both print a version number.

Installing Node.js and npm

npm ships bundled with Node.js, so installing Node gives you both. Always choose the LTS (Long-Term Support) version unless you have a specific reason not to — it's what most libraries are tested against.

winget install OpenJS.NodeJS.LTS --source winget

brew install node

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.5/install.sh | bash

nvm install --lts
nvm use --lts

Verify: node -v and npm -v should both print a version number. If either says "not recognized," close and reopen your terminal first — most installers need a fresh shell to pick up the updated PATH.

Installing Git

You'll need Git to push code to your Hugging Face Space and to a GitHub repository for Vercel.

sudo apt install git

Verify: git --version. First-time setup also needs your identity for commits:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Running the project locally

Once your AI assistant (Cursor) has generated the codebase from the local development prompt below, you'll typically end up with a backend folder (Python/FastAPI) and a frontend folder (React/TypeScript). Adjust folder and file names to match whatever Cursor actually generates, but the shape of it looks like this:

cd backend
python -m venv venv

# Activate the virtual environment:
#   macOS/Linux:
source venv/bin/activate
#   Windows (PowerShell):
venv\Scripts\Activate.ps1

pip install -r requirements.txt
uvicorn main:app --reload --port 8000

cd frontend
npm install
npm run dev

Open the URL your terminal prints (typically http://localhost:5173 for a Vite + React frontend) in your browser. The frontend should now be talking to your backend at http://localhost:8000. If the browser can't reach your webcam, check that no other application (Zoom, Teams, another browser tab) is already holding the camera.

Accounts & deployment

The plan: the backend (the YOLO model + FastAPI server) runs in a Docker container on Hugging Face Spaces; the frontend (the React dashboard) runs on Vercel.

Creating a GitHub account

1. Go to github.com/signup ↗.
2. Enter an email, create a password, and choose a username — this username becomes part of your repository URLs, so pick something you're fine having public.
3. Verify your email address when prompted.
4. Create a new repository for your frontend code from the + → New repository button once logged in.

Creating a Hugging Face account

1. Go to huggingface.co/join ↗.
2. Sign up with an email address (or continue with an existing account), and verify your email — some features are gated behind a verified address.
3. Generate an access token for git operations: go to Settings → Access Tokens, click New token, and give it at least write access if you'll be pushing code to a Space via git. Copy and store it somewhere safe — you won't be able to see it again.

Deploying the backend on Hugging Face Spaces

1. Go to huggingface.co/spaces ↗ and click Create new Space.
2. Give it a name, choose the owner (your account or an organization), and pick a visibility (Public or Private).
3. Under Space SDK, select Docker — this tells Hugging Face to build and run whatever Dockerfile it finds in the repo, rather than a pre-set framework like Gradio or Streamlit.
4. Pick hardware — the free CPU basic tier is enough to start with.
5. Click Create Space. Hugging Face creates a Git repository for it.
6. Add your files — either:
   • Git: clone the Space's repo locally (git clone https://huggingface.co/spaces/<your-username>/<space-name>), copy in your Dockerfile, requirements.txt, and backend code, then git add . && git commit -m "Initial deploy" && git push. When prompted for a password, use the access token you generated above.
   • Web UI: use the Space's Files tab to upload files directly, if you'd rather not use git.
7. Hugging Face automatically rebuilds the container on every push. The first build can take several minutes, especially if your requirements.txt includes large packages like PyTorch or Ultralytics.
8. By default, Spaces expects your app to listen on port 7860 — make sure your Dockerfile's CMD starts uvicorn on that port (e.g. CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]).
9. Add any secrets (API keys, config values) under Settings → Variables and secrets on the Space, rather than hard-coding them — they'll be exposed to your container as environment variables.

Enabling CORS on the backend

Your frontend (on a vercel.app domain) and your backend (on a hf.space domain) are on different origins. By default, browsers block a webpage from calling an API on a different origin — this is CORS, and without configuring it, every request from your deployed frontend to your deployed backend will fail silently with a console error, even though the same call works fine on localhost.

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://your-frontend.vercel.app"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Replace https://your-frontend.vercel.app with your actual Vercel URL once you know it. You can ask your AI assistant to add this for you — just tell it your frontend's deployed URL.

Deploying the frontend on Vercel

1. Push your frontend code to a GitHub repository (create one if you haven't already).
2. Sign up or log in at vercel.com ↗ — signing in with your GitHub account makes the next step smoother.
3. From the Vercel dashboard, click Add New… → Project, then Import Git Repository.
4. Authorize Vercel to access your GitHub account (or organization), then select the frontend repository from the list.
5. Vercel auto-detects your framework (React, Vite, Next.js, etc.) and fills in sensible build settings — review them, but you usually won't need to change anything.
6. Add an environment variable pointing the frontend at your backend, e.g. VITE_API_URL (or whatever your code expects) set to your Hugging Face Space's URL — typically https://<your-username>-<space-name>.hf.space.
7. Click Deploy. Vercel installs dependencies, runs your build, and publishes it — usually within a couple of minutes.

Free-tier limits worth knowing

If a deployment fails

Definition of done

Before calling the deployment finished, confirm each of these:

• Locally, opening the dashboard shows live video with bounding boxes and updating counts.
• docker build completes without errors on your own machine before you push to Hugging Face.
• Your Hugging Face Space shows a Running status, not a build or runtime error.
• Visiting the Space's URL directly returns a response (e.g. the FastAPI docs page), confirming the backend is genuinely live.
• Your Vercel deployment shows Ready.
• Visiting the Vercel URL loads the dashboard with no CORS errors in the browser console.
• The deployed dashboard updates its counts from whatever video source you decided on in How the pieces fit together above.

Vibe coding: the prompts

Two prompts carry this build from a local prototype to a deployed web service. Copy either one into your coding assistant of choice and adapt as needed.

Local development phase

You are an expert full-stack engineer and computer vision developer. I want you to build a complete, production-ready web application for real-time people counting and tracking using a fixed webcam mounted in a standard room.

The core architecture must use YOLO (via the Ultralytics library) paired with the ByteTrack algorithm for persistent object tracking.

Please generate the complete codebase, configuration files, and architectural setup based on the following specifications:

1. System Architecture
- Backend: Python (FastAPI or Flask) to handle the video stream processing, YOLO initialization, and tracking logic.
- Frontend: A modern, clean, responsive dashboard in React and TypeScript.
- Communication: Use WebSockets or Server-Sent Events (SSE) to stream real-time analytics data and live processed video frames from the backend to the frontend UI without UI lag.

2. Backend Computer Vision Requirements
- Load the "yolo11n.pt" (or yolov8n.pt) model for optimized real-time CPU/GPU performance.
- Restrict object detection strictly to the "person" class (Class ID 0).
- Implement the tracking loop using model.track(source, persist=True, tracker="bytetrack.yaml").
- Implement robust exception handling for camera initialization. The code must gracefully attempt to fall back across camera indices (0, 1, 2) and try alternative video backends (like cv2.CAP_DSHOW on Windows) if the default camera stream fails to open.
- Maintain two distinct metrics in memory:
  1. Current Count: active unique tracking IDs present in the immediate frame.
  2. Cumulative Count: the total historical count of unique tracking IDs seen since the session started.

3. Frontend Dashboard UI Requirements
- Viewport: a main center stage displaying the live annotated video stream with YOLO bounding boxes and tracking IDs drawn on screen.
- Analytics cards: high-visibility, clean stat cards showing "Live Headcount" (current occupancy), "Total Unique Visitors" (cumulative traffic), and "System FPS / Status" (camera connection health).
- Control panel: interactive buttons to start/pause the live camera stream, reset the cumulative counter back to zero, and a dropdown to select the camera index (0, 1, 2).

Ensure all code includes inline documentation explaining how frames are grabbed, processed, tracked, and served to the client web browser. Ensure the webcam loop safely releases hardware resources when closed.

Deployment on the web

For this project to run well on a web browser instead of a local machine, what needs to be done?

I want a Dockerfile that I can have on Hugging Face, which I will use to run my backend. The frontend I will deploy on Vercel. This Dockerfile should tell Hugging Face how to build my environment, grant the correct user permissions, and pre-download the YOLO model weights.

Development concerns & best practices

As a machine learning practitioner, being informed is key. You have to be sensitive to how you collect data, process it, and use it to train your model — and you have to ensure the security of sensitive data throughout.

References

• Cursor — download & install ↗
• Python — official downloads ↗
• Node.js — official downloads ↗
• nvm — Node Version Manager (macOS/Linux) ↗
• nvm-windows ↗
• Git — official downloads ↗
• GitHub — create an account ↗
• Hugging Face — create an account ↗
• Hugging Face — Docker Spaces documentation ↗
• Vercel — deployments documentation ↗
• FastAPI — CORS (Cross-Origin Resource Sharing) ↗
• MDN — MediaDevices.getUserMedia() ↗
• Material Design 3 ↗
• Kenya Data Protection Act, 2019 ↗
• Ultralytics YOLO11 documentation ↗
• YOLOv11: an overview of the key architectural enhancements ↗