Claude commited on
Commit
9760d47
Β·
1 Parent(s): 09ba151

Add DEPLOY.md: deploy workflow, deploy-hf script, troubleshooting

Browse files
Files changed (1) hide show
  1. DEPLOY.md +160 -0
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.