DEPLOY.md

# Deploying DocSentry to Streamlit Community Cloud

Free, public URL like `https://docsentry-yourname.streamlit.app`. Judges click a link, see your app. ~10 minutes total.

## What you need
- A free **GitHub** account (https://github.com)
- A free **Streamlit Community Cloud** account (https://share.streamlit.io)
- That's it — no credit card, no Docker, no AWS

## Files already prepared for deployment

| File | Purpose |
|---|---|
| `requirements.txt` | Python packages |
| `packages.txt` | System packages (Tesseract OCR) — apt-installed on the cloud VM |
| `.streamlit/config.toml` | Theme: blue corporate colors |
| `.gitignore` | Excludes `.venv/`, `data/` (use `sample_data/` instead), checkpoints |
| `sample_data/` | 26 curated demo files (~21 MB) — small enough for GitHub |
| `app.py` | Auto-detects sample_data on startup; judges can pick a sample without uploading |

## Step 1 — Create a GitHub repository (3 minutes)

1. Go to https://github.com/new
2. Repository name: `docsentry` (or whatever you want)
3. Set to **Public** (required for free Streamlit Cloud tier)
4. Do NOT initialize with README — we have our own
5. Click **Create repository**
6. Copy the URL shown — looks like `https://github.com/YourName/docsentry.git`

## Step 2 — Push the project to GitHub

Open PowerShell in your project folder:

```powershell
cd "C:\Users\HP\Desktop\Anomaly Based project"

# Install git for Windows if you don't have it: https://git-scm.com/download/win
git init
git add .
git commit -m "Initial commit: DocSentry document forensics demo"
git branch -M main
git remote add origin https://github.com/YourName/docsentry.git
git push -u origin main
```

If git asks for credentials: use your GitHub username + a **personal access token** (not your password). Make a token at https://github.com/settings/tokens — give it `repo` scope.

After this, refresh your GitHub page. You should see all the files: `app.py`, `forensics.py`, `audit_report.py`, `requirements.txt`, `packages.txt`, `sample_data/`, etc.

## Step 3 — Deploy on Streamlit Community Cloud (5 minutes)

1. Go to https://share.streamlit.io
2. Sign in with your GitHub account (one click — it's the same login)
3. Click **Create app** (top right)
4. Pick **Deploy from GitHub**
5. Fill in:
   - **Repository**: `YourName/docsentry`
   - **Branch**: `main`
   - **Main file path**: `app.py`
   - **App URL** (custom): `docsentry-yourname` (or whatever's free)
6. Click **Deploy**

Streamlit Cloud now:
1. Reads `packages.txt` → installs Tesseract OCR on the VM
2. Reads `requirements.txt` → pip-installs every dependency
3. Loads `app.py` → starts the Streamlit server

This takes 3-5 minutes the first time. Watch the build log on the right side of the screen.

When you see **"Your app is live"**, click **Open app** — that's your public URL.

## Step 4 — Test the live deployment

On the live URL:
1. **Tab 1**: pick a sample from the dropdown (e.g. `tampered/land_005_copy_move.png`) → should show **HIGH** band + heatmaps
2. **Tab 2**: upload two different files from `sample_data/originals/` → consistency check
3. **Tab 3**: change folder to `sample_data` → batch audit

If anything errors, check the logs via the **Manage app** menu on the live page.

## Step 5 — Share the link

You now have a public URL. Drop it in your pitch deck, on your GitHub README, on Devpost. Judges click → 30-second cold start → working demo, no install required.

## Updating the live app

Push to GitHub → Streamlit Cloud auto-deploys in ~1 minute. No redeploy button needed.

```powershell
git add .
git commit -m "Updated thresholds for higher precision"
git push
```

The live URL stays the same.

## Resource limits on the free tier

- **1 GB RAM** — enough for all forensic operations on documents up to ~2000x2000 pixels
- **CPU only** — no GPU. The Random Forest path runs fine; the CNN path (Section 7.6 in the notebook) won't fit here
- **App sleeps after ~7 days** of zero traffic — first visitor after that waits ~30 seconds for a cold start
- **Public access** — anyone with the URL can use it. Fine for hackathons. If you need it private, upgrade to Streamlit Teams ($25/mo) or self-host

## Common issues

**"ModuleNotFoundError: forensics"**
Make sure `forensics.py` and `audit_report.py` are at the **repo root** (not in a subfolder). Streamlit Cloud runs `app.py` from the repo root and Python only finds modules in the same folder.

**"tesseract: not found" on the live app**
The `packages.txt` file might not have been committed. Run `git status` and `git add packages.txt`, then `git push`. Verify on GitHub that `packages.txt` exists in the root.

**Sample data dropdown is empty on live app**
The `.gitignore` excludes `data/` but not `sample_data/`. Check on GitHub that the `sample_data/` folder is visible. If it's missing, you might have a leftover `data/` exclusion. Remove `sample_data/` from `.gitignore` if so.

**Build times out**
Free tier build limit is ~15 minutes. If you exceed, trim `requirements.txt` (e.g. remove `seaborn`, `imagehash`, `exifread` if unused). They're nice-to-have but not core.

**`models/forgery_rf.joblib` missing**
Train it locally first (run Section 7.5 in the notebook) then commit + push. The app gracefully falls back to rule-based-only scoring if the model is missing.

**Memory error on large uploads**
Free tier has 1 GB RAM. Tell judges to use PNG/JPG under 5 MB or downscale large scans first. Or upgrade to Teams ($25/mo, 8 GB RAM) for the hackathon.

## Alternative: Hugging Face Spaces (also free)

If Streamlit Cloud is slow on your day of demo, the same code deploys to Hugging Face Spaces with no changes:

1. Create a Space at https://huggingface.co/new-space
2. Pick **Streamlit** as the SDK
3. Push to its git repo using your HF write token
4. Done. Public URL like `huggingface.co/spaces/yourname/docsentry`

HF Spaces gives you 16 GB RAM free vs Streamlit's 1 GB, but the URL is uglier. Use whichever wins on the day.