🚢 Deployment

IntentScope is designed to be deployed across three platforms:

Service	Platform	Why
Backend API (FastAPI + Go)	Render	Free tier, Docker support
Frontend (Next.js)	Vercel	Optimized for Next.js
Database (PostgreSQL)	Neon	Serverless Postgres, free tier
Docs (this site)	Vercel	Auto-deploy from `docs/` folder

1. Database — Neon

Create a Neon project

Sign up at neon.tech
Create a new project → name it intentscope
Copy the connection string (pooled, asyncpg format):

postgresql+asyncpg://user:password@host-pooler.neon.tech/neondb?sslmode=require

Run migrations

Set your DATABASE_URL to the Neon connection string and run:

cd backend-python
alembic upgrade head

Reset stale model preferences (if needed)

In the Neon SQL Editor, run:

UPDATE users
SET default_model = 'groq/llama-3.1-8b-instant'
WHERE default_model IS NULL
   OR default_model NOT IN (
       'groq/llama-3.1-8b-instant',
       'groq/llama-3.3-70b-versatile',
       'groq/gemma2-9b-it',
       'mistral/mistral-small-latest',
       'mistral/mistral-large-latest',
       'ollama/llama3.2'
   );

2. Backend — Render

The repo includes a render.yaml for one-click deployment.

Connect your repo

Go to render.com → New → Blueprint
Connect your GitHub repo (intent-scope)
Render will detect render.yaml and create both services

Add environment variables

In the Render dashboard for intentscope-api, go to Environment and add:

Key	Value
`DATABASE_URL`	Your Neon connection string
`CLERK_SECRET_KEY`	`sk_test_...`
`GROQ_API_KEY`	`gsk_...`
`MISTRAL_API_KEY`	Your key (optional fallback)

OLLAMA_URL is not needed on Render — Ollama cannot run on cloud instances.

Verify deployment

curl https://intentscope-api.onrender.com/health
# {"status":"healthy","db":"connected"}

3. Frontend — Vercel

Import project

Go to vercel.com → Add New Project
Import your GitHub repo
Set Root Directory to frontend
Framework Preset: Next.js (auto-detected)

Add environment variables

In Vercel project settings → Environment Variables:

Key	Value
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	`pk_test_...`
`CLERK_SECRET_KEY`	`sk_test_...`
`NEXT_PUBLIC_CLERK_SIGN_IN_URL`	`/sign-in`
`NEXT_PUBLIC_CLERK_SIGN_UP_URL`	`/sign-up`
`NEXT_PUBLIC_API_URL`	`https://intentscope-api.onrender.com`

Deploy

Click Deploy. Every push to main triggers an automatic redeploy.

4. Docs — Vercel (this site)

Create a separate Vercel project

Go to vercel.com → Add New Project
Import the same GitHub repo
Set Root Directory to docs
Framework Preset: Next.js (auto-detected)

Deploy

No environment variables needed. Click Deploy.

Your docs will be live at https://intent-scope-docs-lake.vercel.app (or a custom domain).

Production Checklist

Neon DB created and migrations run
GROQ_API_KEY set on Render
CLERK_SECRET_KEY set on both Render and Vercel
NEXT_PUBLIC_API_URL points to Render backend URL
/health endpoint returns {"status":"healthy","db":"connected"}
Stale model preferences cleaned up via Neon SQL Editor

Docker (Self-Hosted)

To run the full stack locally with Docker:

docker compose -f docker-compose.prod.yml up --build -d

Container	Port
`intentscope-postgres`	5434
`intentscope-ollama`	11434
`intentscope-api`	8000
`intentscope-validator`	8081
`intentscope-frontend`	3000

API Reference