deploy.md

🚀 ArunCore — Production Deployment Guide

Architecture: Next.js static frontend on Vercel + FastAPI backend on Railway + custom domain neuralarun.in (GoDaddy). Monorepo is deployed from GitHub (neural-arun/aruncore).

Browser (https://neuralarun.in)
└── Vercel  (serves frontend/out static export)
      └── calls ──> Railway  (FastAPI, uvicorn, port $PORT)
                      ├── OPENAI / COHERE / GITHUB / TELEGRAM keys (env)
                      └── volume /app/data  (persists active-learning answers)

---

Table of Contents

1. Prerequisites
2. Push repository to GitHub
3. Deploy backend on Railway
4. Deploy frontend on Vercel
5. Point neuralarun.in (GoDaddy) to Vercel
6. Verification checklist
7. Security notes
8. Troubleshooting

---

1. Prerequisites

• Accounts: Railway, Vercel, GoDaddy (domain neuralarun.in).
• All API keys available (from local .env — never commit it):
  • OPENAI_API_KEY, COHERE_API_KEY
  • GITHUB_USERNAME, GITHUB_TOKEN
  • TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID
  • TELEGRAM_ALERT_BOT_TOKEN, TELEGRAM_ALERT_CHAT_ID
  • TELEGRAM_PUBLIC_BOT_TOKEN, ADMIN_SECRET_KEY
  • APIFY_API_TOKEN, LINKEDIN_PROFILE_URL (optional)

---

2. Push repository to GitHub

cd /home/arun/projects/profile
git add -A
git commit -m "chore: production deploy prep"
git push origin main

This pushes the whole monorepo (backend + frontend + data/ + tenants/). Railway and Vercel each build only the part they need. .env, db/, and frontend/out/ are gitignored.

---

3. Deploy backend on Railway

1. railway.app → New Project → Deploy from GitHub repo → neural-arun/aruncore.
2. Railway detects the Dockerfile and builds automatically.
   • Docker CMD already runs uvicorn backend.app.main:app --host 0.0.0.0 --port $PORT.
3. Variables tab → add every key listed in Prerequisites.
   • Set RUN_TELEGRAM_PUBLIC_BOT=true only if you want the public Telegram bot process.
4. Volumes tab → add a volume mounted at /app/data.
   • Persists data/raw/unknown_questions.json (AI-trained answers). Without it, every redeploy resets learned answers. First mount is empty (seed it later if needed).
5. Deploy, then open https://<your-app>.up.railway.app/health.
   • Expected: {"status": "ok", "active_sessions": {...}, "telegram_alert_bot_preview": "...", ...}
   • Copy this URL — you'll need it for Vercel.

---

4. Deploy frontend on Vercel

1. vercel.com → Add New → Project → import neural-arun/aruncore.
2. Root Directory → frontend.
3. Framework Preset → Next.js. Output settings → Output directory → out (the project uses output: "export"; Vercel serves the static export).
4. Environment Variables:

   Name	Value
   NEXT_PUBLIC_API_URL	https://<your-app>.up.railway.app
   NEXT_PUBLIC_TELEGRAM_ALERT_BOT_TOKEN	your alert bot token
   NEXT_PUBLIC_TELEGRAM_ALERT_CHAT_ID	your alert chat id

   • Without NEXT_PUBLIC_API_URL the chat falls back to window.location.origin and breaks.
5. Deploy. You get a *.vercel.app URL. CORS already allows * + all vercel.app subdomains.

---

5. Point neuralarun.in (GoDaddy) to Vercel

1. Vercel project → Settings → Domains → add neuralarun.in and www.neuralarun.in.
2. Choose Vercel DNS; Vercel shows the exact records to create.
3. In GoDaddy DNS Manager, create/replace:

   A      @      76.76.21.21
   CNAME  www    cname.vercel-dns.com
   

   Delete any conflicting @ A/CNAME (e.g., old forwarding rows).
4. Vercel auto-provisions HTTPS. Propagation: minutes → up to 24h.

---

6. Verification checklist

• https://<railway-url>/health returns status: ok.
• https://neuralarun.in loads the hero card & tabs.
• Send a chat message → reply arrives, and Telegram alert fires.
• ?tutor=ed_donner demo mode loads Ed Donner branding.
• Voice note (TTS) plays from the client.
• Redeploy does not wipe admin-verified answers (volume mounted).

---

7. Security notes

• No secrets in code. The alert bot token is read from NEXT_PUBLIC_TELEGRAM_ALERT_BOT_TOKEN (client env) — set it in Vercel only.
• If any token was ever committed or deployed publicly, rotate it immediately (Telegram: BotFather → revoke token), then update Railway + Vercel env.
• Future hardening: move client-side Telegram alerts behind a backend endpoint so the token never ships to the browser at all.

---

8. Troubleshooting

Symptom	Fix
Chat calls Vercel URL, not Railway	Set NEXT_PUBLIC_API_URL on Vercel & redeploy
/health returns error on start	All Railway env vars present? OPENAI_API_KEY required at boot
Bot answers reset after redeploy	Volume /app/data not attached
Domain shows Vercel 404	DNS not propagated / domain not added in Vercel settings
CORS errors in console	Backend allow_origins=["*"] already covers all; confirm deploy is newest

---

Optional upgrades

• Backend-only Dockerfile + .dockerignore → faster Railway builds (skip frontend build).
• Branded API subdomain: api.neuralarun.in → CNAME to your Railway app, then point NEXT_PUBLIC_API_URL at it.