Video2Guide / DEPLOY.md
Claude
Add DEPLOY.md: deploy workflow, deploy-hf script, troubleshooting
9760d47
|
Raw History Blame Contribute Delete
5.71 kB
# VideoGuideMaker / Video2Guide β€” Deploy Guide
## TL;DR
To ship code changes to https://huggingface.co/spaces/joemartis/Video2Guide:
```bash
~/bin/deploy-hf
```
That's the whole deploy. Wait ~1–3 minutes for HF to rebuild.
---
## Where everything lives
| Thing | Location |
|---|---|
| Local checkout | `/Users/jmartis/Documents/GitHub/VideoGuideMaker` |
| GitHub repo (source of truth) | https://github.com/JoeMartis/VideoGuideMaker |
| HF Space (live site) | https://huggingface.co/spaces/joemartis/Video2Guide |
| Deploy script | `/Users/jmartis/bin/deploy-hf` |
## Remotes inside the repo
```
github β†’ https://github.com/JoeMartis/VideoGuideMaker.git (source)
origin β†’ https://huggingface.co/spaces/joemartis/Video2Guide (live site)
```
(There's also a duplicate `space` remote pointing at HF; harmless, ignore it.)
---
## How code reaches production
```
You ask Claude β†’ Claude commits to claude/general-session-* branch on GitHub
↓
Auto-merge bot opens & merges PR into main on GitHub
↓
You run `deploy-hf`
↓
Script pulls main, strips video files from history, force-pushes to HF
↓
HF rebuilds Docker container (~1–3 min) β†’ live
```
You don't push to GitHub yourself. Claude handles all writes; the bot merges; `deploy-hf` reads.
---
## What `deploy-hf` does, step by step
```bash
#!/usr/bin/env bash
set -euo pipefail
cd /Users/jmartis/Documents/GitHub/VideoGuideMaker
# 1. Fetch the latest main from GitHub
git fetch github main
# 2. Throwaway working branch built fresh from GitHub each run
git checkout -B hf-deploy github/main
# 3. Strip every video file from the entire git history.
# HF rejects any file >10MB not in LFS; a few old commits
# include big .m4v / .mp4 sample inputs that have to be gone.
git filter-repo --invert-paths \
--path-glob '*.mp4' --path-glob '*.m4v' \
--path-glob '*.mov' --path-glob '*.mkv' --path-glob '*.webm' \
--force
# 4. filter-repo defensively drops `origin`; re-add (silent if it's there)
git remote add origin https://huggingface.co/spaces/joemartis/Video2Guide 2>/dev/null || true
# 5. Force-push to HF. Force is required because each filter-repo run
# produces a new SHA chain β€” content matches, history doesn't.
git push origin hf-deploy:main --force
```
You never need to touch your real local `main` β€” the script lives on a separate `hf-deploy` branch.
---
## Verifying a deploy worked
After running `deploy-hf`:
```bash
curl -s https://huggingface.co/api/spaces/joemartis/Video2Guide | \
python3 -c 'import json,sys; d=json.load(sys.stdin); print("sha:", d.get("sha"), "stage:", d.get("runtime",{}).get("stage"))'
```
- `stage: BUILDING` β†’ still building, wait
- `stage: RUNNING` β†’ live
- `sha: <hash>` β†’ the commit currently deployed (different from your local SHA because of the filter-repo rewrite β€” that's expected)
You can also watch the build live in the **Logs** tab on the Space page.
---
## Adding new code changes
You don't run git for code changes. Tell Claude what you want, e.g.:
- "Default the LLM toggles to off"
- "When I pick an alternate frame, update the OCR text"
- "Remove the TL;DR mode"
Claude will:
1. Make the edits
2. Run the test suite (for backend changes)
3. Commit on `claude/general-session-*` and push
4. The auto-merge bot opens a PR and merges it into `main`
Then **you** run `deploy-hf` to push it to HF.
---
## Troubleshooting
**`'github' does not appear to be a git repository`**
The script's `cd` is landing somewhere without your remotes set up. Either fix the `cd` line or run the script from inside the right folder.
**`error: unknown option 'force~'` (or any `~` typo)**
Open `~/bin/deploy-hf` in `nano`, look for stray `~` characters, remove them.
**HF push rejected with `files larger than 10 MiB`**
A new video file in history slipped past the glob list. Run the script's filter-repo step again with the offending extension added.
**HF push rejected with `non-fast-forward`**
You ran `git push origin main:main` directly instead of using `deploy-hf`. Don't push to HF from your real `main` β€” go through the script.
**Build fails on HF**
Open the Space's Logs tab. Most common cause: a Python import error or missing dependency. Tell Claude the error message.
**`deploy-hf` works but the site looks unchanged**
Browser cache. Hard-reload (Cmd-Shift-R) or open the Space URL in a private window.
---
## Important rules
1. **Never paste your GitHub token in chat or commit it to a file.** If you ever do, immediately revoke at https://github.com/settings/tokens.
2. **Never put videos in `git add`.** They're in `.gitignore`, but if you `git add -f` past it, you'll need to filter-repo them out again.
3. **Don't manually push to HF `main`.** Always use `deploy-hf`. Manual pushes will fail because of history mismatch.
4. **Don't filter-repo on your real `main` branch.** The script does this on a throwaway `hf-deploy` branch on purpose. Your `main` should always track `github/main` cleanly.
---
## Known limitations
- **GitHub `main` history still contains the big videos** in old commits. Anyone cloning the repo fresh from GitHub still downloads them. The clean history only exists on HF and in your throwaway `hf-deploy` branch. Living with this; not worth more pain to fully unify.
- **Each `deploy-hf` run does a force-push to HF.** This is intentional and safe β€” HF is a deploy target, not a collaboration repo.
---
If something breaks, tell Claude the error and what you ran. Don't paste tokens. That's it.