Spaces:
Sleeping
Sleeping
|
Download DEPLOY.md from joemartis/Video2Guide: direct link, hf CLI and curl.
- Browser
- Download file 5.71 kB
-
https://huggingface.co/spaces/joemartis/Video2Guide/resolve/main/DEPLOY.md
- Command line
-
hf download hf://spaces/joemartis/Video2Guide/DEPLOY.md
-
curl -L -o DEPLOY.md https://huggingface.co/spaces/joemartis/Video2Guide/resolve/main/DEPLOY.md
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. | |