README.md

metadata

title: GeoGlyph Gateway API
emoji: 🛰️
colorFrom: pink
colorTo: gray
sdk: docker
app_port: 7860
pinned: false

GeoGlyph Gateway API

FastAPI gateway for GeoGlyph SAM2 running on a Slurm worker.

The gateway does not run SAM2. It:

1. Starts a long-running Slurm worker API with sbatch.
2. Opens an SSH tunnel to the worker node.
3. Proxies /process, /status/{task_id}, and /download/{task_id} to the worker.

Required Hugging Face Space Secrets / Variables

Secrets:

• SSH_PRIVATE_KEY: private key allowed to SSH into the cluster login node.
• GATEWAY_API_TOKEN: bearer token used by QGIS/client requests.
• Optional SSH_KNOWN_HOSTS: known_hosts content for the cluster login host.

Variables:

• CLUSTER_LOGIN_HOST: public DNS/IP of the cluster login node, e.g. kraken.example.edu.
• CLUSTER_USER: cluster username, e.g. manolo.
• CLUSTER_MODEL_DIR: path to GeoGlyphFinal/model on the cluster.
• WORKER_INFO_DIR: path where the Slurm worker writes node/port files.
• WORKER_PORT: usually 8000.
• GATEWAY_LOCAL_PORT: usually 18000.
• SBATCH_SCRIPT: usually run_geoglyph_worker_env.sbatch.

Endpoints

• GET /health
• POST /worker/start
• POST /worker/connect
• GET /worker/health
• POST /process
• GET /status/{task_id}
• GET /download/{task_id}

SSH authentication options

Preferred for production/prototype stability:

• SSH_PRIVATE_KEY_BASE64: base64-encoded private key, single line.

Alternative quick test:

• SSH_PASSWORD: cluster password. This requires the Docker image to include sshpass. It will not work if the cluster requires MFA or interactive Duo-like prompts.

If both a key and password are configured, the gateway prefers the key.