Spaces:
Sleeping
Sleeping
Claude commited on
Commit Β·
9760d47
1
Parent(s): 09ba151
Add DEPLOY.md: deploy workflow, deploy-hf script, troubleshooting
Browse files
DEPLOY.md
ADDED
|
@@ -0,0 +1,160 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# VideoGuideMaker / Video2Guide β Deploy Guide
|
| 2 |
+
|
| 3 |
+
## TL;DR
|
| 4 |
+
|
| 5 |
+
To ship code changes to https://huggingface.co/spaces/joemartis/Video2Guide:
|
| 6 |
+
|
| 7 |
+
```bash
|
| 8 |
+
~/bin/deploy-hf
|
| 9 |
+
```
|
| 10 |
+
|
| 11 |
+
That's the whole deploy. Wait ~1β3 minutes for HF to rebuild.
|
| 12 |
+
|
| 13 |
+
---
|
| 14 |
+
|
| 15 |
+
## Where everything lives
|
| 16 |
+
|
| 17 |
+
| Thing | Location |
|
| 18 |
+
|---|---|
|
| 19 |
+
| Local checkout | `/Users/jmartis/Documents/GitHub/VideoGuideMaker` |
|
| 20 |
+
| GitHub repo (source of truth) | https://github.com/JoeMartis/VideoGuideMaker |
|
| 21 |
+
| HF Space (live site) | https://huggingface.co/spaces/joemartis/Video2Guide |
|
| 22 |
+
| Deploy script | `/Users/jmartis/bin/deploy-hf` |
|
| 23 |
+
|
| 24 |
+
## Remotes inside the repo
|
| 25 |
+
|
| 26 |
+
```
|
| 27 |
+
github β https://github.com/JoeMartis/VideoGuideMaker.git (source)
|
| 28 |
+
origin β https://huggingface.co/spaces/joemartis/Video2Guide (live site)
|
| 29 |
+
```
|
| 30 |
+
|
| 31 |
+
(There's also a duplicate `space` remote pointing at HF; harmless, ignore it.)
|
| 32 |
+
|
| 33 |
+
---
|
| 34 |
+
|
| 35 |
+
## How code reaches production
|
| 36 |
+
|
| 37 |
+
```
|
| 38 |
+
You ask Claude β Claude commits to claude/general-session-* branch on GitHub
|
| 39 |
+
β
|
| 40 |
+
Auto-merge bot opens & merges PR into main on GitHub
|
| 41 |
+
β
|
| 42 |
+
You run `deploy-hf`
|
| 43 |
+
β
|
| 44 |
+
Script pulls main, strips video files from history, force-pushes to HF
|
| 45 |
+
β
|
| 46 |
+
HF rebuilds Docker container (~1β3 min) β live
|
| 47 |
+
```
|
| 48 |
+
|
| 49 |
+
You don't push to GitHub yourself. Claude handles all writes; the bot merges; `deploy-hf` reads.
|
| 50 |
+
|
| 51 |
+
---
|
| 52 |
+
|
| 53 |
+
## What `deploy-hf` does, step by step
|
| 54 |
+
|
| 55 |
+
```bash
|
| 56 |
+
#!/usr/bin/env bash
|
| 57 |
+
set -euo pipefail
|
| 58 |
+
cd /Users/jmartis/Documents/GitHub/VideoGuideMaker
|
| 59 |
+
|
| 60 |
+
# 1. Fetch the latest main from GitHub
|
| 61 |
+
git fetch github main
|
| 62 |
+
|
| 63 |
+
# 2. Throwaway working branch built fresh from GitHub each run
|
| 64 |
+
git checkout -B hf-deploy github/main
|
| 65 |
+
|
| 66 |
+
# 3. Strip every video file from the entire git history.
|
| 67 |
+
# HF rejects any file >10MB not in LFS; a few old commits
|
| 68 |
+
# include big .m4v / .mp4 sample inputs that have to be gone.
|
| 69 |
+
git filter-repo --invert-paths \
|
| 70 |
+
--path-glob '*.mp4' --path-glob '*.m4v' \
|
| 71 |
+
--path-glob '*.mov' --path-glob '*.mkv' --path-glob '*.webm' \
|
| 72 |
+
--force
|
| 73 |
+
|
| 74 |
+
# 4. filter-repo defensively drops `origin`; re-add (silent if it's there)
|
| 75 |
+
git remote add origin https://huggingface.co/spaces/joemartis/Video2Guide 2>/dev/null || true
|
| 76 |
+
|
| 77 |
+
# 5. Force-push to HF. Force is required because each filter-repo run
|
| 78 |
+
# produces a new SHA chain β content matches, history doesn't.
|
| 79 |
+
git push origin hf-deploy:main --force
|
| 80 |
+
```
|
| 81 |
+
|
| 82 |
+
You never need to touch your real local `main` β the script lives on a separate `hf-deploy` branch.
|
| 83 |
+
|
| 84 |
+
---
|
| 85 |
+
|
| 86 |
+
## Verifying a deploy worked
|
| 87 |
+
|
| 88 |
+
After running `deploy-hf`:
|
| 89 |
+
|
| 90 |
+
```bash
|
| 91 |
+
curl -s https://huggingface.co/api/spaces/joemartis/Video2Guide | \
|
| 92 |
+
python3 -c 'import json,sys; d=json.load(sys.stdin); print("sha:", d.get("sha"), "stage:", d.get("runtime",{}).get("stage"))'
|
| 93 |
+
```
|
| 94 |
+
|
| 95 |
+
- `stage: BUILDING` β still building, wait
|
| 96 |
+
- `stage: RUNNING` β live
|
| 97 |
+
- `sha: <hash>` β the commit currently deployed (different from your local SHA because of the filter-repo rewrite β that's expected)
|
| 98 |
+
|
| 99 |
+
You can also watch the build live in the **Logs** tab on the Space page.
|
| 100 |
+
|
| 101 |
+
---
|
| 102 |
+
|
| 103 |
+
## Adding new code changes
|
| 104 |
+
|
| 105 |
+
You don't run git for code changes. Tell Claude what you want, e.g.:
|
| 106 |
+
|
| 107 |
+
- "Default the LLM toggles to off"
|
| 108 |
+
- "When I pick an alternate frame, update the OCR text"
|
| 109 |
+
- "Remove the TL;DR mode"
|
| 110 |
+
|
| 111 |
+
Claude will:
|
| 112 |
+
|
| 113 |
+
1. Make the edits
|
| 114 |
+
2. Run the test suite (for backend changes)
|
| 115 |
+
3. Commit on `claude/general-session-*` and push
|
| 116 |
+
4. The auto-merge bot opens a PR and merges it into `main`
|
| 117 |
+
|
| 118 |
+
Then **you** run `deploy-hf` to push it to HF.
|
| 119 |
+
|
| 120 |
+
---
|
| 121 |
+
|
| 122 |
+
## Troubleshooting
|
| 123 |
+
|
| 124 |
+
**`'github' does not appear to be a git repository`**
|
| 125 |
+
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.
|
| 126 |
+
|
| 127 |
+
**`error: unknown option 'force~'` (or any `~` typo)**
|
| 128 |
+
Open `~/bin/deploy-hf` in `nano`, look for stray `~` characters, remove them.
|
| 129 |
+
|
| 130 |
+
**HF push rejected with `files larger than 10 MiB`**
|
| 131 |
+
A new video file in history slipped past the glob list. Run the script's filter-repo step again with the offending extension added.
|
| 132 |
+
|
| 133 |
+
**HF push rejected with `non-fast-forward`**
|
| 134 |
+
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.
|
| 135 |
+
|
| 136 |
+
**Build fails on HF**
|
| 137 |
+
Open the Space's Logs tab. Most common cause: a Python import error or missing dependency. Tell Claude the error message.
|
| 138 |
+
|
| 139 |
+
**`deploy-hf` works but the site looks unchanged**
|
| 140 |
+
Browser cache. Hard-reload (Cmd-Shift-R) or open the Space URL in a private window.
|
| 141 |
+
|
| 142 |
+
---
|
| 143 |
+
|
| 144 |
+
## Important rules
|
| 145 |
+
|
| 146 |
+
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.
|
| 147 |
+
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.
|
| 148 |
+
3. **Don't manually push to HF `main`.** Always use `deploy-hf`. Manual pushes will fail because of history mismatch.
|
| 149 |
+
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.
|
| 150 |
+
|
| 151 |
+
---
|
| 152 |
+
|
| 153 |
+
## Known limitations
|
| 154 |
+
|
| 155 |
+
- **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.
|
| 156 |
+
- **Each `deploy-hf` run does a force-push to HF.** This is intentional and safe β HF is a deploy target, not a collaboration repo.
|
| 157 |
+
|
| 158 |
+
---
|
| 159 |
+
|
| 160 |
+
If something breaks, tell Claude the error and what you ran. Don't paste tokens. That's it.
|