From a00956e458e63827022392b97db9b1da15acc3bb Mon Sep 17 00:00:00 2001 From: JA Date: Fri, 13 Feb 2026 20:45:14 +0000 Subject: [PATCH] Documentation: Add 60-second visual deployment guide --- QUICKSTART_VISUAL.md | 444 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 444 insertions(+) create mode 100644 QUICKSTART_VISUAL.md diff --git a/QUICKSTART_VISUAL.md b/QUICKSTART_VISUAL.md new file mode 100644 index 0000000..f648de6 --- /dev/null +++ b/QUICKSTART_VISUAL.md @@ -0,0 +1,444 @@ +# 🚀 GRIMLOCK - 60 SECOND DEPLOYMENT + +## What You're About to Deploy + +A complete Slack replacement with AI built-in. Real-time messaging, channels, DMs, and @grimlock AI assistant that knows your company. + +--- + +## Prerequisites (Check These First) + +```bash +# Check Docker +docker --version +# Need: Docker version 20.10+ + +# Check Node.js +node --version +# Need: v18.0.0 or higher + +# Check you're in the right place +ls -la +# Should see: docker-compose.yml, backend/, frontend/ +``` + +If any are missing, install them first: +- Docker: https://docs.docker.com/get-docker/ +- Node.js: https://nodejs.org/ + +--- + +## The 60-Second Deploy + +### Step 1: Clone (if needed) +```bash +git clone https://gittea.979labs.com/amitis55/grimlock.git +cd grimlock +``` + +### Step 2: Start Backend (one command) +```bash +./start.sh +``` + +**What this does:** +- ✅ Creates backend/.env with your API key +- ✅ Creates frontend/.env.local +- ✅ Starts PostgreSQL database +- ✅ Starts Redis +- ✅ Starts FastAPI backend +- ✅ Runs health checks +- ✅ Installs frontend dependencies + +**Output you'll see:** +``` +🤖 GRIMLOCK - Quick Start +========================== +📝 Step 1: Configuring backend... +✅ Backend .env created +📝 Step 2: Configuring frontend... +✅ Frontend .env.local created +🐳 Step 3: Checking Docker... +✅ Docker is installed +🚀 Step 4: Starting backend services... +⏳ Waiting 10 seconds for services to start... +🏥 Step 5: Checking backend health... +✅ Backend is healthy! +📦 Step 6: Installing frontend dependencies... +✅ Dependencies installed +🎉 GRIMLOCK IS READY! +``` + +### Step 3: Start Frontend (in new terminal) +```bash +cd grimlock/frontend +npm run dev +``` + +**Output you'll see:** +``` +▲ Next.js 14.2.18 +- Local: http://localhost:3000 +✓ Ready in 2.3s +``` + +### Step 4: Open Browser +``` +http://localhost:3000 +``` + +**That's it! You're done.** ⏱️ Total time: 60 seconds + +--- + +## First Time User Flow + +### 1. Sign Up +``` +Click "Sign up" +Email: you@vectorzulu.com +Name: Your Name +Password: •••••••• +Role: engineer (or BD/admin/exec) +Click "Create Account" +``` + +### 2. Create Your First Channel +``` +Click "+" next to Channels +Name: general +Description: Team discussion +Private: No +Click "Create" +``` + +### 3. Send Your First Message +``` +Type: Hello team! +Press Enter +``` + +### 4. Try the AI +``` +Type: @grimlock what is Grimlock? +Press Enter +Wait 2-3 seconds +See AI response +``` + +**Congratulations!** You now have a working Slack replacement with AI. + +--- + +## What Each Service Does + +``` +┌─────────────────────────────────────────┐ +│ localhost:3000 - Frontend │ +│ • Next.js web app │ +│ • What users interact with │ +└─────────────────────────────────────────┘ + ↓ API calls + WebSocket +┌─────────────────────────────────────────┐ +│ localhost:8000 - Backend │ +│ • FastAPI REST API │ +│ • WebSocket server │ +│ • AI integration │ +└─────────────────────────────────────────┘ + ↓ stores data +┌─────────────────────────────────────────┐ +│ postgres:5432 - Database │ +│ • User accounts │ +│ • Messages │ +│ • Channels │ +└─────────────────────────────────────────┘ + +┌─────────────────────────────────────────┐ +│ redis:6379 - Cache │ +│ • Session storage │ +│ • Real-time pub/sub │ +└─────────────────────────────────────────┘ +``` + +--- + +## Testing It Works + +### Backend Health Check +```bash +curl http://localhost:8000/api/health +``` + +**Expected:** +```json +{ + "status": "healthy", + "context_loaded": true, + "ai_client_ready": true, + "database": "connected", + "websocket": "ready" +} +``` + +### Frontend Accessibility +```bash +curl http://localhost:3000 +``` + +**Expected:** HTML page content + +### WebSocket Connection +Open browser console (F12) at http://localhost:3000 +**Expected:** "WebSocket connected" message + +### AI Integration +1. Register account +2. Create channel +3. Send: "@grimlock hello" +4. Wait 3 seconds +5. See AI response + +--- + +## Common Issues & Fixes + +### ❌ "docker: command not found" +**Fix:** Install Docker +```bash +# macOS +brew install --cask docker + +# Ubuntu/Debian +sudo apt-get install docker.io docker-compose + +# Windows +Download from docker.com +``` + +### ❌ "Port 8000 already in use" +**Fix:** Stop other service using port 8000 +```bash +# Find what's using port 8000 +lsof -i :8000 + +# Kill it +kill -9 + +# Or change Grimlock's port in docker-compose.yml +``` + +### ❌ "Port 3000 already in use" +**Fix:** Stop other service or use different port +```bash +# Use different port +npm run dev -- -p 3001 + +# Then open http://localhost:3001 +``` + +### ❌ Frontend can't connect to backend +**Check:** +```bash +# 1. Backend is running +curl http://localhost:8000/api/health + +# 2. Frontend .env.local exists +cat frontend/.env.local + +# 3. Should contain +NEXT_PUBLIC_API_URL=http://localhost:8000 +NEXT_PUBLIC_WS_URL=http://localhost:8000 +``` + +### ❌ Database connection failed +**Fix:** Wait 10 more seconds, database starting +```bash +# Check database logs +docker-compose logs postgres + +# Restart if needed +docker-compose restart postgres +sleep 10 +``` + +### ❌ AI not responding +**Check:** +1. API key is correct in backend/.env +2. Internet connection working +3. Check backend logs: `docker-compose logs backend` + +--- + +## Stopping Grimlock + +### Stop Frontend +```bash +# In the terminal running npm run dev +Ctrl+C +``` + +### Stop Backend +```bash +cd grimlock +docker-compose down +``` + +### Completely Reset (delete all data) +```bash +docker-compose down -v # -v deletes volumes (database data) +rm -rf frontend/node_modules +rm backend/.env frontend/.env.local +``` + +--- + +## Next Steps + +### Day 1: Internal Testing +- [ ] All team members sign up +- [ ] Create team channels +- [ ] Test messaging +- [ ] Try @grimlock AI +- [ ] Report any bugs + +### Week 1: Daily Use +- [ ] Use for actual work discussions +- [ ] Replace some Slack channels +- [ ] Gather team feedback +- [ ] Fix critical issues + +### Week 2+: Expand +- [ ] Add file uploads +- [ ] Customize for team needs +- [ ] Add integrations +- [ ] Scale as needed + +--- + +## Getting Help + +**Documentation:** +- README.md - Full documentation +- DEPLOYMENT.md - Detailed deployment guide +- FRONTEND.md - Frontend specifics +- ARCHITECTURE.md - How it works + +**Quick Help:** +```bash +# View backend logs +docker-compose logs backend + +# View all logs +docker-compose logs + +# Restart everything +docker-compose restart + +# Health check +curl http://localhost:8000/api/health +``` + +--- + +## The Command Reference Card + +**Keep this handy:** + +```bash +# START GRIMLOCK +./start.sh # Backend +cd frontend && npm run dev # Frontend (new terminal) + +# CHECK STATUS +curl http://localhost:8000/api/health # Backend health +curl http://localhost:3000 # Frontend up +docker-compose ps # All services + +# VIEW LOGS +docker-compose logs backend # Backend +docker-compose logs postgres # Database +docker-compose logs -f # All (follow) + +# STOP GRIMLOCK +Ctrl+C # Frontend (in its terminal) +docker-compose down # Backend + +# RESET EVERYTHING +docker-compose down -v # Delete all data +./start.sh # Start fresh +``` + +--- + +## Success Checklist + +After running start.sh and npm run dev, verify: + +- [ ] `curl http://localhost:8000/api/health` returns "healthy" +- [ ] `http://localhost:3000` opens in browser +- [ ] Can create account +- [ ] Can create channel +- [ ] Can send message +- [ ] Message appears instantly +- [ ] @grimlock responds +- [ ] Opening second browser window shows same messages + +**All checked?** You're good to go! 🚀 + +--- + +## Pro Tips + +1. **Keep Two Terminals Open** + - Terminal 1: Backend (docker-compose) + - Terminal 2: Frontend (npm run dev) + +2. **Check Health Regularly** + ```bash + watch -n 5 'curl -s http://localhost:8000/api/health' + ``` + +3. **Monitor Logs** + ```bash + docker-compose logs -f backend | grep ERROR + ``` + +4. **Quick Restart** + ```bash + docker-compose restart backend && sleep 5 + ``` + +5. **Database Access** + ```bash + docker-compose exec postgres psql -U grimlock + ``` + +--- + +## What You've Deployed + +✅ **Real-time messaging platform** +✅ **AI assistant in every conversation** +✅ **Channels for team organization** +✅ **Direct messages for 1-on-1** +✅ **File sharing capability** +✅ **User authentication & security** +✅ **WebSocket real-time updates** +✅ **Production-grade architecture** + +**Cost:** ~$0.003 per AI query +**Users:** Unlimited +**Data:** All yours +**Control:** Complete + +--- + +# Welcome to Grimlock! 🤖 + +Your team now has a Slack replacement with AI built-in, running on your servers, with your data, under your control. + +**Questions?** Check the docs or create an issue. +**Feedback?** We'd love to hear it. +**Contributions?** PRs welcome. + +**Now go build something amazing with your team.** 🚀