# 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
```bash
# 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](https://huggingface.co/spaces) -> "Create new Space".
   - SDK: **Docker**
   - Template: **Blank**
2. **Push Code**:
   ```bash
   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.