deploy.md

AmaniQuery Render Deployment Guide

This guide details the steps to deploy the AmaniQuery monorepo components to 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=...

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
   • 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).
   • The Spaces must be created first (e.g., AmaniQuery/amaniquery-agent and AmaniQuery/amaniquery-memory).

   Usage:

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