| # 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. | |