Documentation: Add 60-second visual deployment guide
This commit is contained in:
444
QUICKSTART_VISUAL.md
Normal file
444
QUICKSTART_VISUAL.md
Normal file
@@ -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.** 🚀
|
||||
Reference in New Issue
Block a user