9.7 KiB
9.7 KiB
🚀 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)
# 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)
git clone https://gittea.979labs.com/amitis55/grimlock.git
cd grimlock
Step 2: Start Backend (one command)
./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)
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
curl http://localhost:8000/api/health
Expected:
{
"status": "healthy",
"context_loaded": true,
"ai_client_ready": true,
"database": "connected",
"websocket": "ready"
}
Frontend Accessibility
curl http://localhost:3000
Expected: HTML page content
WebSocket Connection
Open browser console (F12) at http://localhost:3000
Expected: "WebSocket connected" message
AI Integration
- Register account
- Create channel
- Send: "@grimlock hello"
- Wait 3 seconds
- See AI response
Common Issues & Fixes
❌ "docker: command not found"
Fix: Install Docker
# 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
# 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
# Use different port
npm run dev -- -p 3001
# Then open http://localhost:3001
❌ Frontend can't connect to backend
Check:
# 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
# Check database logs
docker-compose logs postgres
# Restart if needed
docker-compose restart postgres
sleep 10
❌ AI not responding
Check:
- API key is correct in backend/.env
- Internet connection working
- Check backend logs:
docker-compose logs backend
Stopping Grimlock
Stop Frontend
# In the terminal running npm run dev
Ctrl+C
Stop Backend
cd grimlock
docker-compose down
Completely Reset (delete all data)
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:
# 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:
# 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/healthreturns "healthy"http://localhost:3000opens 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
-
Keep Two Terminals Open
- Terminal 1: Backend (docker-compose)
- Terminal 2: Frontend (npm run dev)
-
Check Health Regularly
watch -n 5 'curl -s http://localhost:8000/api/health' -
Monitor Logs
docker-compose logs -f backend | grep ERROR -
Quick Restart
docker-compose restart backend && sleep 5 -
Database Access
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. 🚀