DEPLOYMENT.md

Deployment Guide

This guide describes how to deploy the GeoQuery platform for public access.

Strategy

We use a single-container approach where the backend (FastAPI) serves the frontend (Next.js) as static files. This simplifies deployment to PaaS providers like Railway, Render, or Hugging Face Spaces.

Architecture

• Build Stage: Node.js builder compiles the Next.js frontend into static HTML/CSS/JS (frontend/out).
• Runtime Stage: Python 3.11 image installs backend dependencies.
• Serving: FastAPI mounts the static build at / and serves the API at /api.
• Data: Geospatial data (backend/data) is included in the image (~2GB).

Prerequisites

• Docker
• ~5GB Free disk space (for image build)
• 4GB+ RAM on host machine (for DuckDB in-memory analytics)

Local Build & Run

# Build the image
docker build -t geoquery .

# Run the container (Mapping 7860 to 7860 to match standard Space config)
docker run -p 7860:7860 -e GEMINI_API_KEY=your_key_here geoquery

Hosting Options (Getting a Public URL)

To share this demo with others, you need to host the Docker container on a cloud provider.

Option A: Hugging Face Spaces (Easiest & Free)

This will give you a public URL like https://huggingface.co/spaces/username/geoquery.

1. Create Space: Go to huggingface.co/spaces -> "Create new Space".
   • SDK: Docker
   • Template: Blank
2. Push Code:

   git remote add space https://huggingface.co/spaces/YOUR_USERNAME/SPACE_NAME
   git push space main
   

3. Configure Secrets: In the Space "Settings" tab, add a "Repository Secret" named GEMINI_API_KEY with your key.

Option B: Railway / Render

1. Connect your GitHub repository.
2. Railway/Render will detect the Dockerfile.
3. Set the environment variable GEMINI_API_KEY.
4. Detailed output will be available at a URL like https://geoquery-production.up.railway.app.

Option C: Google Cloud Run

1. Build: gcloud builds submit --tag gcr.io/PROJECT_ID/geoquery
2. Deploy: gcloud run deploy geoquery --image gcr.io/PROJECT_ID/geoquery --platform managed

Notes

• Data Persistence: The current setup uses read-only data baked into the image. User uploads will be lost on restart unless a volume is mounted to /app/backend/data/custom.
• Memory Usage: DuckDB processes data in-memory. For large queries, ensure the host has sufficient RAM.