# 🚀 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.** 🚀