deploy.md

# AmaniQuery Render Deployment Guide

This guide details the steps to deploy the AmaniQuery monorepo components to [Render.com](https://render.com).

## Prerequisites

1. **GitHub Repository**: Ensure your code is pushed to a GitHub repository connected to Render.
2. **Docker**, **Node.js**, and **Go** knowledge.
3. **Render Account**: Created and ready.

## 1. Database & Infrastructure (Render Postgres & Redis)

Before deploying services, set up your managed data stores.

### PostgreSQL

- **Type**: PostgreSQL
- **Name**: `amaniquery-db`
- **Region**: Frankfurt (EU-Central) or nearest.
- **Environment**:
  - `POSTGRES_USER`: `amaniquery`
  - `POSTGRES_DB`: `amaniquery`
- **Internal Connection URL**: Copy this for use in service env vars.

### Redis

- **Type**: Redis
- **Name**: `amaniquery-redis`
- **Max Memory Policy**: `allkeys-lru`
- **Internal Connection URL**: Copy this (`redis://...`).

## 2. Backend Services (Docker Runtime)

Since AmaniQuery is a monorepo, using **Docker** as the Runtime is recommended for Go services to handle build context correctly (copying `go.mod` from root).

### Common Configuration for All Backend Services

- **Runtime**: Docker
- **Repository**: `your-repo/amaniquery`
- **Region**: Same as Database.

| Service Name | Dockerfile Path | Build Context Directory | Env Vars |
| :--- | :--- | :--- | :--- |
| `amaniquery-portal` | `services/portal/Dockerfile` | `.` (Root) | `SERVER_HTTP_PORT=8080`, `DB_HOST=...` |
| `amaniquery-ingestion`| `services/ingestion/Dockerfile`| `.` (Root) | `QDRANT_URL=...`, `RABBITMQ_URL=...` |
| `amaniquery-voice` | `services/voice/Dockerfile` | `.` (Root) | `OPENAI_API_KEY=...` |
| `amaniquery-files` | `services/files/Dockerfile` | `.` (Root) | `MINIO_ENDPOINT=...` |
| `amaniquery-notifications`| `services/notifications/Dockerfile.gateway` | `.` (Root) | `MAILTRAP_API_KEY=...` |

> [!TIP]
> **Root Directory Setting**: In Render, set "Root Directory" to `.` (default) so Docker builds have access to the full monorepo context.

## 3. Frontend Applications (Static Sites)

We will use the **Static Site** type for frontends, relying on the `Dockerfile` or Render's Native Node build.
*Recommendation*: Use **Static Site** with Node build command for faster deploys, or **Docker** if you need Nginx customization.

### Option A: Static Site (Native Node - Recommended)

- **Build Command**: `yarn && yarn turbo run build --filter=admin-portal`
- **Publish Directory**: `frontend/apps/admin/dist`
- **Root Directory**: `frontend`

### Option B: Docker (Using our new Turbo Dockerfiles)

- **Runtime**: Docker
- **Dockerfile Path**: `frontend/apps/admin/Dockerfile`
- **Context**: `frontend` (Important: context is `frontend` subfolder, not root, for these specific Dockerfiles)

| App Name | Build Command (Static) | Publish Dir | Context |
| :--- | :--- | :--- | :--- |
| `admin-portal` | `yarn build:admin` | `apps/admin/dist` | `frontend` |
| `developer-portal` | `yarn build:dev` | `apps/developer-portal/dist` | `frontend` |
| `web-app` | `yarn build:web` | `apps/web/dist` | `frontend` |

> *Note: You may need to add helper scripts in `frontend/package.json` like `"build:admin": "turbo run build --filter=admin-portal"` to keep commands simple.*

## 4. HuggingFace Spaces (Docker Deployment)

For users preferring HuggingFace Spaces (free tier: 2 vCPU, 16GB RAM, 50GB disk), follow these steps.

### Prerequisites

- HuggingFace Account
- External Databases (Managed Services):
  - **PostgreSQL**: Neon.tech (Free Tier available)
  - **Redis**: Upstash (Free Tier available)
  - **Qdrant**: Qdrant Cloud (Free Tier available)

### Deployment Steps

1. **Create a New Space**:
    - Go to [HuggingFace Spaces](https://huggingface.co/new-space)
    - Enter a name (e.g., `amaniquery`)
    - Select **Docker** as the Space SDK
    - Choose "Blank" for the template

2. **Deploy via Script (Recommended)**:
    - Set `HF_TOKEN` in your local `.env`.
    - Run: `python scripts/deploy_hf.py agent`
    - This deploys both the Go Agent and Rust Memory Service in a single container (Sidecar pattern) for maximum efficiency and localhost communication.

3. **Deploy Manually (Alternative)**:
    - Clone your Space's repository locally.
    - Copy `deployments/huggingface/Dockerfile.hf` to `Dockerfile` in the root.
    - Copy `deployments/huggingface/README.md` to the root.
    - Push to HuggingFace.

4. **Configure Secrets**:
    - Go to **Settings** -> **Variables and Secrets** in your Space.
    - Add the secrets listed in `deployments/huggingface/.env.hf.example`.

5. **Status**:
    - The Space will build and start both `agent-server` and `memory-server`.
    - The Go agent will automatically connect to the local memory service.

6. **Automated Deployment (Optional)**:
   We provided a script `scripts/deploy_hf.py` to automate the deployment process.

   **Prerequisites**:
   - `HF_TOKEN` must be set in your `.env` file (Get it from [HF Settings](https://huggingface.co/settings/tokens)).
   - The Spaces must be created first (e.g., `AmaniQuery/amaniquery-agent` and `AmaniQuery/amaniquery-memory`).

   **Usage**:

   ```bash
   # Deploy Agent
   python scripts/deploy_hf.py agent
   
   # Deploy Memory Service
   python scripts/deploy_hf.py memory
   
   # Deploy Both
   python scripts/deploy_hf.py all
   ```

## 5. Environment Variables Checklist

Transfer these from your `env.example` files to Render's "Environment" tab for each service.

- [ ] **Portal**: `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`, `REDIS_URL`, `JWT_SECRET`
- [ ] **Voice**: `OPENAI_API_KEY`, `ELEVENLABS_API_KEY`, `REDIS_URL`
- [ ] **Frontend**: `VITE_API_BASE_URL` (Set this to the `https://...onrender.com` URL of your Portal service).

## 6. Deployment Order

1. **Infrastructure** (Postgres/Redis) - Wait for healthy.
2. **Backend Services** (Portal, etc.) - Deploy & check logs.
3. **Frontend Apps** - Deploy & update `VITE_API_BASE_URL` with backend URL.