DEPLOY.md

Deployment checklist

Hugging Face Space type: Docker, preferably Private while testing.

Required Space Secrets:

• ZAI_API_KEY（智谱 API key；启动脚本会映射给官方 Codex CLI）
• CODEWHALE_RUNTIME_TOKEN

Recommended Space Secret:

• HF_TOKEN with read access to any private/restricted fisheries Dataset used by the Space. The two default public repositories can be read without a token.

Required Space Variable:

• MARINE_API_URL

For the school deployment, keep MARINE_API_URL=http://127.0.0.1:8000 and set MARINE_PROXY_UPSTREAM_URL=http://127.0.0.1:8000. The fixed ngrok web domain continues to point to port 7861; requests sent to /marine/... are forwarded to the local Marine API. On Hugging Face, set MARINE_API_URL to the public web URL with the /marine suffix, for example: https://subway-unbiased-barcode.ngrok-free.dev/marine.

When the school network cannot reach Hugging Face, set these school-only variables so fisheries inventory and downloads use the local mirror:

• LOCAL_SQUID_DATA_ROOT=/data0/zqyan/squid_data/raw
• LOCAL_TUNA_DATA_ROOT=/data0/zqyan/tuna_data/raw

Optional Space Variables:

• HF_SQUID_DATASET_REPO (default globalsquiddatabase/squid_dataset)
• HF_TUNA_DATASET_REPO (default globalsquiddatabase/Tuna-Fisheries-Dataset)
• HF_SQUID_DATASET_REVISION and HF_TUNA_DATASET_REVISION (optional approved commit SHAs; otherwise each repository's current SHA is resolved and cached)
• PUBLIC_BASE_URL (normally inferred from SPACE_HOST)
• HF_FISHERIES_MAX_CSV_BYTES and HF_FISHERIES_MAX_ZIP_BYTES

The current temporary Marine API URL can be used for the first smoke test. Later replace the Quick Tunnel with a fixed Named Tunnel URL.

After the Space is Running:

1. Open /mobile if the root does not redirect there.
2. Test Ocean status: 检查我的海洋数据服务器，并告诉我三个数据中心状态。
3. Test a real fisheries CSV read/export: 实际读取 current/sprfmo_effort.csv，报告字段、记录数、缺失、重复并导出 CSV。
4. Test Tuna routing and export: 只查询 Tuna-Fisheries-Dataset，查找并读取 ICCAT/EFFDIS_LL2000-2024.csv，报告真实字段、记录数、缺失和重复并导出 CSV。 Expected exports: filtered raw detail, exact-deduplicated detail and annual summary. ICCAT YearC must be reported as the year field.
5. Expected model-visible tools include mcp_marine_fisheries_analyze_export.
6. Open the returned /api/fisheries/download/{token} URL and confirm the CSV downloads successfully.

Next server phase:

• add /query
• add /subset
• add /download/{token}
• add job/update APIs Then extend marine_mcp.py with corresponding tools.

v3.4.0 deployment stability

• VERSION is the single application version source.
• Only root app.html is served; do not re-create templates/app.html.
• scripts/preflight.py runs automatically from start.sh and fails fast if Space metadata or the frontend entry is inconsistent.
• For durable user favorites and project-package downloads, attach Hugging Face Persistent Storage and set:
  • USER_STATE_ROOT=/data/squid_user_state
  • PROJECT_PACKAGE_ROOT=/data/squid_project_packages