Skip to content

Commit 7b4eaa8

Browse files
JuliaEdomclaude
andcommitted
docs(deploy): rewrite DEPLOY.md for the real HF Space deploy; drop unused langfuse
DEPLOY.md described a Streamlit Community Cloud flow the project doesn't use — the public demo is a Hugging Face Space (Docker). Rewritten to document the actual mechanism: publish only what git tracks (git ls-files) then prune the host, with the repo-hygiene gate keeping internal notes out. docker-compose loses the langfuse service (it was never wired to any code); only the Postgres target remains. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent a6f8ae7 commit 7b4eaa8

2 files changed

Lines changed: 55 additions & 102 deletions

File tree

‎DEPLOY.md‎

Lines changed: 55 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -1,89 +1,58 @@
1-
# Deployment — Streamlit Community Cloud
2-
3-
The fastest free path to a public demo. ~5 minutes after the repo
4-
is on GitHub.
5-
6-
## What's shipped in the repo
7-
8-
The deployed version intentionally carries a subset of the BIRD
9-
Mini-Dev databases, not all 11:
10-
11-
| DB | size | source | shipped |
12-
|---|---|---|---|
13-
| `chinook` | 1 MB | Chinook sample | ✅ |
14-
| `bird_california_schools` | 11 MB | BIRD Mini-Dev | ✅ |
15-
| `bird_debit_card_specializing` | 34 MB | BIRD Mini-Dev | ✅ |
16-
| `bird_financial` | 68 MB | BIRD Mini-Dev | ✅ |
17-
| `bird_formula_1` | 22 MB | BIRD Mini-Dev | ✅ |
18-
| `bird_student_club` | 2.6 MB | BIRD Mini-Dev | ✅ |
19-
| `bird_superhero` | 0.2 MB | BIRD Mini-Dev | ✅ |
20-
| `bird_thrombosis_prediction` | 7 MB | BIRD Mini-Dev | ✅ |
21-
| `bird_toxicology` | 2.6 MB | BIRD Mini-Dev | ✅ |
22-
| `bird_card_games` | 250 MB | BIRD Mini-Dev | ❌ — over GitHub 100 MB/file limit |
23-
| `bird_codebase_community` | 460 MB | BIRD Mini-Dev | ❌ — over GitHub 100 MB/file limit |
24-
| `bird_european_football_2` | 571 MB | BIRD Mini-Dev | ❌ — over GitHub 100 MB/file limit |
25-
26-
The three excluded DBs are gitignored. The registry in
27-
`src/nl_sql/db/registry.py` skips DBs whose SQLite file isn't on
28-
disk, so the deployed UI's database selector only lists the 9
29-
shipped databases.
30-
31-
`chroma_data/` is also committed (~58 MB) so the app doesn't have
32-
to re-embed the schema chunks on first cold start. Orphan chunks
33-
for the three excluded DBs are harmless — the registry never
34-
asks for them.
35-
36-
## Steps
37-
38-
1. **Create a public GitHub repo.** Name suggestion: `NL_SQL` or
39-
`nl-sql-portfolio`. Do not initialise with a README — we already
40-
have one.
41-
42-
2. **Push the local main branch:**
43-
```powershell
44-
git remote add origin https://github.com/<your-username>/<repo>.git
45-
git push -u origin main
46-
```
47-
Repo size will be ~150 MB. The push takes a minute or two.
48-
49-
3. **Sign in to <https://share.streamlit.io>** with the same
50-
GitHub account.
51-
52-
4. **New app:**
53-
- Repository: pick the repo you just pushed.
54-
- Branch: `main`.
55-
- Main file path: `app/streamlit_app.py`.
56-
- App URL: defaults to
57-
`https://<your-username>-<repo>-app-streamlit-app-<hash>.streamlit.app`.
58-
You can rename via the dashboard later.
59-
60-
5. **Set the secret:**
61-
- In the Streamlit Cloud app dashboard → "Settings" → "Secrets".
62-
- Add the API key in TOML format:
63-
```toml
64-
MISTRAL_API_KEY = "your-key-here"
65-
```
66-
- Streamlit Cloud injects every key in this TOML as an
67-
environment variable, which `pydantic-settings` picks up.
68-
- Click "Save". The app reboots automatically.
69-
70-
6. **First load.**
71-
The cold start is ~30 seconds — Streamlit Cloud installs the
72-
`ui` extra deps (streamlit, plotly, pandas), reads the prebuilt
73-
Chroma index, and warms the LLM provider. Subsequent loads are
74-
sub-second.
1+
# Deployment — Hugging Face Space (Docker)
2+
3+
The public demo runs on a Hugging Face Space with a Docker runtime (free tier):
4+
<https://liovina-nl-sql.hf.space>. Cold start ~30 s, then interactive.
5+
6+
## Deploy policy: only what git tracks, then prune
7+
8+
The deploy publishes **exactly the files git tracks** (`git ls-files`), never the
9+
working tree. Working-kitchen files — internal notes, audits, `.env`, scratch
10+
reports — are gitignored and a repo-hygiene CI gate fails if any slip into the
11+
index, so they cannot reach the Space. The upload also **prunes** the Space: files
12+
removed from the repo are deleted on the host, not left behind from an earlier push.
13+
14+
The deploy script itself (`.deploy_hf.py`) is repo-local (it reads a local token
15+
and Mistral key by path) and is intentionally not committed. It:
16+
17+
1. computes the file set from `git ls-files` minus a publish-exclude list
18+
(`tests/`, `.github/`, `docs/research/`, `reviews/`, `eval/baselines/`);
19+
2. drops anything the hygiene detector flags;
20+
3. uploads via `huggingface_hub`, then prunes remote files no longer present;
21+
4. supports `--self-test` (a gate that runs before upload) and `--dry-run`.
22+
23+
## What ships to the Space
24+
25+
The Space is **SQLite-only** — `psycopg` is pruned from its `requirements.txt`, so
26+
the Postgres path (see README) is not present there; it is for local/CI use. The
27+
Space carries a subset of the BIRD Mini-Dev databases (the three largest exceed
28+
GitHub's 100 MB/file limit and are gitignored):
29+
30+
| DB | size | shipped |
31+
|---|---|---|
32+
| `chinook` | 1 MB | ✅ |
33+
| `bird_california_schools` | 11 MB | ✅ |
34+
| `bird_debit_card_specializing` | 34 MB | ✅ |
35+
| `bird_financial` | 68 MB | ✅ |
36+
| `bird_formula_1` | 22 MB | ✅ |
37+
| `bird_student_club` | 2.6 MB | ✅ |
38+
| `bird_superhero` | 0.2 MB | ✅ |
39+
| `bird_thrombosis_prediction` | 7 MB | ✅ |
40+
| `bird_toxicology` | 2.6 MB | ✅ |
41+
| `bird_card_games` | 250 MB | ❌ over 100 MB/file |
42+
| `bird_codebase_community` | 460 MB | ❌ over 100 MB/file |
43+
| `bird_european_football_2` | 571 MB | ❌ over 100 MB/file |
44+
45+
The registry in `src/nl_sql/db/registry.py` skips DBs whose SQLite file isn't on
46+
disk, so the deployed UI's selector lists only the 9 shipped databases. All 11
47+
BIRD slices are present locally for eval. `chroma_data/` is committed (~58 MB) so
48+
the app doesn't re-embed schema chunks on cold start.
49+
50+
## Secret
51+
52+
The Space needs one secret — `MISTRAL_API_KEY` — set in the Space's Settings →
53+
Variables and secrets. `pydantic-settings` reads it from the environment.
7554

7655
## Updating
7756

78-
Push to `main` → Streamlit Cloud auto-redeploys. No manual step.
79-
80-
## Why not Vercel
81-
82-
Streamlit is a long-running Tornado/WebSocket server with stateful
83-
per-session memory. Vercel's serverless model gives you ~10-second
84-
function executions with no persistent process — every page-reload
85-
would lose `st.session_state` and every user keystroke would race
86-
against a cold start. The hacks that "work" run Streamlit in a
87-
container behind Vercel's edge layer, which trades all of Vercel's
88-
strengths for none of Streamlit's. Streamlit Community Cloud is
89-
the natively-supported home for this app.
57+
Re-run the local deploy script; it re-uploads the tracked set and prunes. CI (tests
58+
+ repo-hygiene) gates `main` before any deploy is worth doing.

‎docker-compose.yml‎

Lines changed: 0 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -18,21 +18,5 @@ services:
1818
timeout: 3s
1919
retries: 10
2020

21-
langfuse:
22-
profiles: ["langfuse", "all"]
23-
image: langfuse/langfuse:latest
24-
container_name: nl_sql_langfuse
25-
depends_on:
26-
postgres:
27-
condition: service_healthy
28-
environment:
29-
DATABASE_URL: postgresql://postgres:postgres@postgres:5432/nl_sql_demo
30-
NEXTAUTH_SECRET: "${LANGFUSE_NEXTAUTH_SECRET:-dev-secret-change-me}"
31-
SALT: "${LANGFUSE_SALT:-dev-salt-change-me}"
32-
NEXTAUTH_URL: "http://localhost:3000"
33-
TELEMETRY_ENABLED: "false"
34-
ports:
35-
- "3000:3000"
36-
3721
volumes:
3822
nl_sql_pg_data:

0 commit comments

Comments
 (0)