Alkiviades — Deployment Guide

Architecture

alkiviades.cc (Cloudflare Pages)
    └── Next.js static export, CDN-cached

api.alkiviades.cc (Render)
    └── Docker container, Python 3.12 + FastAPI + Uvicorn

Cloudflare DNS
    ├── CNAME @ → alkiviades.pages.dev (proxied)
    ├── CNAME www → alkiviades.pages.dev (proxied)
    └── CNAME api → alkiviades.onrender.com (DNS only)

Backend: Render (Docker)

Initial Setup

1. Go to dashboard.render.com → New → Web Service
2. Connect GitHub: Rumbleaxe/Alkiviades
3. Configure:

Field	Value
Name	alkiviades
Region	Frankfurt
Branch	master
Runtime	Docker (auto-detected)

1. Add environment variables:

Key	Value
DEEPSEEK_API_KEY	Your DeepSeek API key
TAVILY_API_KEY	Your Tavily API key
ALKIVIADES_ADMIN_EMAIL	Your admin email
ALKIVIADES_ADMIN_PASSWORD	Your admin password (≤72 chars)
JWT_SECRET	Stable random string (e.g. UUID)
CORS_ORIGINS	https://alkiviades.cc,https://www.alkiviades.cc
COOKIE_SAMESITE	none
COOKIE_SECURE	true
COOKIE_DOMAIN	.alkiviades.cc

1. Click Create Web Service

First build takes 5-8 minutes (Docker build + knowledge base construction). Test: https://alkiviades.onrender.com/health → {"status": "ok"}.

Custom Domain

1. Settings → Custom Domain → Add api.alkiviades.cc
2. Render verifies DNS and auto-provisions SSL (~5 min)

Auto-Deploy

Every push to master triggers a new build. Manual deploy available from Render dashboard.

Memory (Free Tier)

The free tier has 512 MB RAM. We optimize with: - float16 embedding dtype (halves vector memory) - 15K vocabulary cap - numpy mmap mode (lazy paging)

If OOM occurs, lower MAX_VOCAB_SIZE to 10000 or 8000.

Frontend: Cloudflare Pages

Initial Setup

1. Go to Cloudflare Dashboard → Workers & Pages → Create → Pages tab
2. Connect GitHub: Rumbleaxe/Alkiviades
3. Configure:

Field	Value
Framework preset	Next.js
Build command	npm run build
Build output directory	out
Root directory	frontend

1. Add environment variable:

Key	Value
NEXT_PUBLIC_API_URL	https://api.alkiviades.cc

1. Click Save and Deploy

Custom Domain

1. Cloudflare Pages → alkiviades → Custom Domains
2. Add alkiviades.cc and www.alkiviades.cc
3. Auto-provisions SSL

DNS: Cloudflare Records

In Cloudflare Dashboard → alkiviades.cc → DNS → Records:

Type	Name	Target	Proxy
CNAME	@	alkiviades.pages.dev	Orange (Proxied)
CNAME	www	alkiviades.pages.dev	Orange (Proxied)
CNAME	api	alkiviades.onrender.com	Gray (DNS only)

Verification

After deployment, verify in order:

1. https://api.alkiviades.cc/health → {"status":"ok"}
2. https://api.alkiviades.cc/auth/login → POST returns JWT
3. https://alkiviades.cc → Landing page loads
4. Login from frontend → authenticates against API
5. Chat works (send a prompt, receive SSE streaming response)
6. Admin: /health/debug endpoint accessible to admin user
7. Admin: AdminPanel appears in sidebar for admin users
8. Guest: Click "Try Free" → login → 5 queries available

Updating Secrets

After changing env vars on Render, trigger a manual deploy (or push to master) for changes to take effect.

For JWT secret changes: users will need to log in again (old tokens invalidated).

Monitoring

• Render dashboard: CPU, memory, response time metrics
• Admin logs: GET /api/admin/logs (authenticated admin)
• Health debug: GET /health/debug (authenticated admin)
• Frontend: Browser DevTools → Network tab for SSE stream inspection