DEPLOY_UNIFIED.md

Unified deployment notes

This package is intentionally the same source tree for the Hugging Face Space and the school server. Deployment settings, not separate code branches, select the data plane.

School server

Set MARINE_API_URL=http://127.0.0.1:8000 and MARINE_PROXY_UPSTREAM_URL=http://127.0.0.1:8000. If local data mirrors are available, set LOCAL_SQUID_DATA_ROOT=/data0/zqyan/squid_data/raw and LOCAL_TUNA_DATA_ROOT=/data0/zqyan/tuna_data/raw. These are read-through caches: a same-path local file is preferred, while every missing file is read from the configured Hugging Face Dataset. Do not set different repository names on the two deployments.

Set the browser-facing export base before restarting the school UI:

export PUBLIC_BASE_URL="https://subway-unbiased-barcode.ngrok-free.dev/marine"

This prevents localhost download links. Public exports then use /marine/download/<token> through the fixed ngrok UI endpoint.

The public ngrok URL exposes the UI on / and the Marine API through /marine/*. Therefore its health endpoint is /marine/health, not /health.

Hugging Face Space

Set the following Variables:

• MARINE_API_URL=https://subway-unbiased-barcode.ngrok-free.dev/marine
• CODEX_PROVIDER=zai
• CODEX_MODEL=glm-5.3
• CODEX_HARNESS_RUNTIME=native
• REQUIRE_CODEX_HARNESS=1

Set these Secrets:

• ZAI_API_KEY
• CODEWHALE_RUNTIME_TOKEN
• HF_TOKEN when the fisheries datasets require authenticated reads

Do not set MARINE_PROXY_UPSTREAM_URL or local data-root variables in the Space. They belong only to the school server.

Runtime behavior

The following read-only requests bypass the model and are returned by the application directly: greetings, runtime identity, Marine health, and metadata-only Tuna/Squid file inventories. This makes these operations fast and avoids the non-interactive MCP approval problem.

Actual Ocean exports and fisheries content analysis remain guarded operations through the official Codex CLI Harness. CODEX_ALLOW_MCP_BYPASS is forbidden: startup fails if it is enabled. The model receives only the read/query/export Marine MCP allow-list; it has no shell, arbitrary filesystem, process-control, Git-write or deletion tool. Server maintenance belongs to a separate SSH super-administrator workflow, not to chat.

Multi-day Ocean downloads

The unified build adds mcp_marine_marine_export_range. It creates one real download for each day in an inclusive date range and returns all URLs. A single request is capped at 31 days to protect the Ocean API; request longer periods month by month. Set MARINE_EXPORT_RANGE_MAX_DAYS only to a value from 1 to 31 (default: 31).