nexus-ai

Deployment Guide

NEXUS is designed to run entirely on free tiers for a hackathon submission, with a clear upgrade path when real usage arrives.

Backend (Slack Bolt app)

Socket Mode means the backend never needs an inbound public URL, which makes it deployable to almost any always-on Node.js host. Recommended free options:

Option A: Railway (recommended)

1. Push backend/ to GitHub.
2. In Railway, New Project → Deploy from GitHub repo, select the repo, set root directory to backend.
3. Add all variables from .env.example under Variables.
4. Set the start command: npm run build && npm start.
5. Railway’s free tier includes enough runtime hours for a hackathon demo and light production use.

Option B: Render

1. New → Background Worker (not a Web Service, since Socket Mode doesn’t listen on a port).
2. Build command: npm install && npm run build. Start command: npm start.
3. Add environment variables from .env.example.

Switching to HTTP mode (production Slack event delivery): set SLACK_SOCKET_MODE=false, deploy as a Web Service instead, and update your Slack app’s Event Subscriptions → Request URL to https://<your-host>/slack/events. No application code changes are required — Bolt handles both transports.

Frontend (landing page + dashboard)

Static site, zero build step — deploy as-is.

Vercel

1. Import the repo, set Root Directory to frontend/public.
2. Framework preset: Other (no build command needed).
3. Deploy. index.html and dashboard.html are served directly.

Database (Supabase)

Already hosted — no deployment step. For production:

• Enable Row Level Security on all tables once the planned OAuth-based dashboard API ships (see docs/ROADMAP.md); the current bot-only access pattern uses the service role key server-side, which is safe as long as that key never reaches the client.
• Set up a daily backup via Supabase’s built-in point-in-time recovery (paid tier) before real customer data arrives.

Environment checklist before going live

• SLACK_SOCKET_MODE=false and Request URLs updated in Slack app config
• NODE_ENV=production
• Supabase service role key stored only in the host’s secret manager, never committed
• Groq API key has sufficient rate limit for expected workspace size
• Slack app submitted for review if distributing beyond your own workspace (see Slack’s app approval guidelines)

Scalability plan

Stage	Users	Change needed
Hackathon demo	1 workspace, <10 users	Current architecture as-is
Early adoption	<50 workspaces	Add connection pooling (Supabase Supavisor, already free-tier available)
Growth	50–500 workspaces	Move reminder/digest polling from node-cron in-process to a dedicated worker + queue (BullMQ + Redis) so a backend restart can’t delay deliveries
Scale	500+ workspaces	Introduce pgvector or a managed vector store for memory_entries search as keyword search’s precision degrades with per-user corpus size; move Groq calls behind a queue with concurrency limits

This site is open source. Improve this page.