File size: 6,901 Bytes
08c9328 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 | # Deployment
**Status tags:** `IMPLEMENTED` · `VERIFIED` · `MEASURED` · `OPEN` · `DEFERRED` · `BLOCKED`.
The live system is deployed across three **private** repositories plus one **public** umbrella repo.
The monorepo working copy is **not** the deployed source. This document records the live topology,
the environment variables, the deploy mechanics, and the traps that cost real debugging time.
---
## 1. Live revisions (VERIFIED)
| Component | Repository | Visibility | Branch | Revision | Host |
|---|---|---|---|---|---|
| Frontend | `Anish-lab-blip/SatQuery-Frontend` | private | `main` | **`2d7ae53b482d`** | Cloudflare Pages → `satquery.pages.dev` |
| Backend / orchestrator | `Anish-lab-blip/SatQuery-Backend` | private | `main` | **`89d80eaddec5`** | Render → `satquery-backend-m4yv.onrender.com` |
| Inference | `Anish-lab-blip/SatQuery-Inference` | private | `main` | **`5a0936ace491`** | Codespace `potential-space-trout-r4ppw969w45j2pvvw`, port 8000 |
| Public umbrella | `Anish-lab-blip/SatQuery-AI` | **public** | `main` | `3dcabd32da41` | this release home |
| Monorepo (working copy) | `C:/Users/anish/satquery-ai` | local only | `master` | `9d57aed` | **no remote**; 334 dirty entries |
> **Trap.** `deploy/` inside the monorepo is **stale and untracked**. It is **not** the deployed
> source. Edits must go to the three real repositories.
## 2. Live health (VERIFIED, probed)
```json
{"status":"ok","service":"satquery-orchestrator",
"tunnel":{"agent_connected":true,"agent_id":"codespaces-fd1038","pending":0,"completed":97},
"config":{"codespace_name":"potential-space-trout-r4ppw969w45j2pvvw\n","codespace_port":8000,
"transport_mode":"auto","tunnel_timeout_s":150.0,"wake_timeout_s":120.0,
"upstream_timeout_s":90.0,"device":"cpu","has_github_token":true}}
```
Note `codespace_name` still carries a trailing `\n` — the cosmetic B-02 patch is **not** deployed.
## 3. Environment variables
### 3.1 Render (gateway) — measured live
| Variable | Value (live) |
|---|---|
| `CODESPACE_NAME` | `potential-space-trout-r4ppw969w45j2pvvw` |
| `CODESPACE_PORT` | `8000` |
| `SATQUERY_ALLOWED_ORIGINS` | `https://satquery.pages.dev` |
| `SATQUERY_DEVICE` | `cpu` |
| `SATQUERY_TRANSPORT` | `auto` |
| `SATQUERY_TUNNEL_TIMEOUT_S` | `150` |
| `SATQUERY_WAKE_TIMEOUT_S` | `120` |
| `SATQUERY_UPSTREAM_TIMEOUT_S` | `90` |
| `GITHUB_TOKEN` | present |
> There is **no** `SATQUERY_UPSTREAM_URL` and **no** `HF_TOKEN` in the live config — the transport is
> the outbound tunnel, not a forwarded port.
### 3.2 Codespace (inference)
| Variable | Purpose |
|---|---|
| `PORT` | platform-assigned; **must be read** |
| `SATQUERY_DEVICE` | `cpu` \| `cuda` \| `mps` \| `null`; read **without importing torch** |
| `SATQUERY_MAX_FILE_BYTES` | per-file cap (shared with Render) |
| `SATQUERY_ASSET_ENABLED` / `SATQUERY_ASSET_DIR` | both required for `/v1/assets`; fails closed (503) otherwise |
| `SATQUERY_ASSET_MAX_FILES` / `SATQUERY_ASSET_TTL_S` | optional handle capacity / lifetime |
## 4. Deploy mechanics
- **Frontend → Cloudflare Pages.** Staged by `scripts/stage_pages.mjs`, deployed with
`npx wrangler pages deploy`.
- **Backend → Render.** `render.yaml` blueprint; `main.py` exposes `app`.
- **Inference → Codespace.** `deploy/codespace/serve.py` serves `build_space_app()` on `$PORT`;
`.devcontainer/` forwards port 8000 and runs the tunnel agent on start via `postStartCommand`.
- **Repository writes** are performed through the **GitHub Git Data API** (blob → tree → commit →
`PATCH` ref) with **sha256 byte-verification** of every uploaded blob. Deletions are expressed as
`sha: null` tree entries. This is used instead of `git push` so each deployed file is verified by
content hash.
### 4.1 Deployed-artifact integrity
Deployed files were re-read from the GitHub API and compared byte-for-byte against the local copies:
**9 files sha256 byte-identical**, and the deployed HEAD re-read from the API. See
`verify_deployed_head.py`.
## 5. Cold start (documented, not hidden)
Render's free tier sleeps when idle and the Codespace may be stopped. The frontend shows
*"Waking inference engine…"* while Render starts the Codespace and polls health. Cold start is
therefore **tens of seconds**, and this is documented rather than papered over.
## 6. Known deployment issues
| ID | Issue | State |
|---|---|---|
| **B-07** | Transient tunnel-agent gaps → a request can hang or return 504. Patch prepared, **NOT deployed**. | **OPEN** |
| — | B-07 root shape: in `auto` mode a tunnel timeout **falls through** to the forward path (`main.py:546`), burning `wake_timeout_s = 120` on a `302` (~249 s ≈ 150 + 120). | measured |
| **B-02** | `/api/health` `codespace_name` trailing `\n`. Cosmetic; the wake path strips it. | **OPEN (cosmetic)** |
| — | Frontend/Backend/Inference repos are **private**, so their links 404 for an outside audience. | by design |
## 7. Platform traps (recorded so they are not rediscovered)
- **Cloudflare `_headers` rules CONCATENATE, they do not override.** Two matching rules are merged;
Chromium takes the **first** `max-age` it encounters. A later rule cannot "fix" an earlier one.
- **Cloudflare 308-redirects `X.html` → `/X`.** Reference the extensionless path.
- **A forwarded Codespace port returns `302` for a private repo** — which is *why* the tunnel exists.
- **The tunnel agent must be started by the devcontainer `postStartCommand`**, or a restarted
Codespace comes up with `agent_connected:false`.
- **Never retry `POST /api/infer` at the gateway** — a retry consumes inference twice.
## 8. Preconditions for a fresh deploy (open items)
1. Cloudflare Pages project name / domain (needed for the deploy command and `robots.txt` sitemap).
2. Artifacts present, or capabilities honestly ship `available: false` (the service **degrades rather
than crashes** on absent artifacts).
3. `HF_TOKEN` set on Render **if** the HF proxy path is used (not used in the live config).
4. Codespace `.devcontainer/` forwarding `:8000` and starting the tunnel agent.
5. The five historical backend blockers closed and verified on the first live run (ASGI stack in
requirements; `$PORT` read; `OPTIONS` preflight; fail-fast app construction; adapter integrity
compared against an expected digest).
## 9. Historical context
The superseded design ran inference on an **HF Space with ZeroGPU** behind a **Railway** gateway. The
active design moves to **Render + Codespace**, CPU-first, with an **outbound tunnel**. The four-endpoint
contract, the gateway responsibility table, the env-var vocabulary and the config freeze are
unchanged — only host names moved. `configs/deploy.yaml` still describes the old HF-Space/ZeroGPU
target and is left **undisturbed as frozen paperwork** (editing it would move the config hash); no
Gradio runtime exists in code.
|