Documentation: Add 60-second visual deployment guide

2026-02-13 20:45:14 +00:00
parent 6695f434b7
commit a00956e458
1 changed files with 444 additions and 0 deletions
--- a/QUICKSTART_VISUAL.md
+++ 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 <PID>
 # 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.** 🚀