445 lines
9.7 KiB
Markdown
445 lines
9.7 KiB
Markdown
# 🚀 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.** 🚀
|