DEPLOYMENT.md

Deploying BREATHE — Completely Free

This guide deploys the app using:

Layer	Service	Cost
Frontend (React/Vite)	Vercel	Free forever
Backend (Flask API)	Render	Free tier
Database	Supabase	Free tier (500MB)

Note on ML models: PyTorch and the transformer models require ~1–2 GB RAM. Render's free tier provides only 512 MB. The app will run without the ML features on the free tier — assessments and auth still work. To enable ML inference for free, see Option B: Hugging Face Spaces below.

---

Prerequisites

• A GitHub account (push your project there first)
• Accounts on Vercel, Render, Supabase — all free to sign up

---

Step 1 — Push to GitHub

cd breathe-app
git init
git add .
git commit -m "Initial commit"
# Create a repo on github.com, then:
git remote add origin https://github.com/YOUR_USERNAME/breathe-app.git
git push -u origin main

Make sure .env is in .gitignore (never commit secrets).

---

Step 2 — Set up the Database on Supabase (free)

1. Go to supabase.com → New Project
2. Give it a name (e.g. breathe) and set a database password
3. Once created, go to Project Settings → Database
4. Copy the Connection string (URI) — it looks like:

   postgresql://postgres:[PASSWORD]@db.xxxx.supabase.co:5432/postgres
   

5. Save this — you'll need it in Steps 3 and 4.

---

Step 3 — Deploy the Backend on Render (free)

1. Go to render.com → New → Web Service

2. Connect your GitHub repo

3. Configure the service:

   Setting	Value
   Root Directory	breathe-app
   Runtime	Python 3
   Build Command	pip install -r requirements.txt
   Start Command	gunicorn app:app
   Instance Type	Free

4. Under Environment Variables, add:

   FLASK_APP=app.py
   FLASK_DEBUG=false
   SECRET_KEY=<run: python -c "import secrets; print(secrets.token_hex(32))">
   DATABASE_URL=<your Supabase connection string from Step 2>
   

5. Click Create Web Service — Render will build and deploy.

6. Your backend URL will be: https://your-service-name.onrender.com

⚠️ Free tier services spin down after 15 minutes of inactivity and take ~30s to wake up on the next request. This is normal.

---

Step 4 — Deploy the Frontend on Vercel (free)

1. Go to vercel.com → Add New Project

2. Import your GitHub repo

3. Configure the project:

   Setting	Value
   Root Directory	breathe-app/frontend
   Framework Preset	Vite
   Build Command	npm run build
   Output Directory	dist

4. Under Environment Variables, add:

   VITE_API_URL=https://your-service-name.onrender.com
   

5. Click Deploy — Vercel builds and publishes instantly.

6. Your app will be live at: https://your-project.vercel.app

---

Option C — Deploy on Hugging Face Spaces with Docker

This repository now includes a root-level Dockerfile so you can deploy the full app as one Docker Space.

1. Go to huggingface.co/spaces → Create new Space

2. Choose Docker as the SDK

3. Push or upload this repository to the Space

4. In Space settings, add environment variables:

   SECRET_KEY=<a strong random value>
   DATABASE_URL=<optional postgres connection string>
   PSYCHO_MODEL_DIR=models/psychometric
   ROBERTA_CKPT=models/text/roberta-model.pt
   

5. Build the Space. The app will start on port 7860 and serve both the React frontend and Flask API from the same domain.

Note: If model files are missing, the app falls back to demo mode for assessments.

---

Step 5 — Update the API Client

In frontend/src/api/client.js, make sure the base URL reads from the env variable:

const BASE_URL = import.meta.env.VITE_API_URL || ''

Redeploy the frontend after making this change.

---

Option B: ML on Hugging Face Spaces (free)

If you want the full ML-powered assessments for free:

1. Go to huggingface.co/spaces → Create new Space
2. Choose Docker as the SDK
3. Upload:
   • app.py, backend/, models/, requirements.txt
   • A Dockerfile (see below)
4. Add the same environment variables in the Space settings

Dockerfile for Hugging Face:

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 7860
CMD ["gunicorn", "--bind", "0.0.0.0:7860", "app:app"]

HF Spaces provides 2 CPU cores and 16 GB RAM on the free tier — enough for the ML models.

---

Summary

Step	Action	Time
1	Push code to GitHub	5 min
2	Create Supabase database, copy connection string	5 min
3	Deploy Flask backend on Render	10 min
4	Deploy React frontend on Vercel	5 min
5	Set VITE_API_URL and redeploy frontend	2 min

Total: ~30 minutes, $0.