amitis55/grimlock

Fork 0

Files

JA 82a54dd7b0 Documentation: Complete deployment and operations guide

2026-02-13 16:38:42 +00:00

13 KiB

Raw Blame History

GRIMLOCK DEPLOYMENT CHECKLIST

PRE-DEPLOYMENT CHECKS

✅ Backend Verification

cd grimlock

# 1. Start backend
docker-compose up -d

# 2. Check health
curl http://localhost:8000/api/health
# Expected: {"status":"healthy","context_loaded":true,...}

# 3. Run tests
python test_api.py
# Expected: All tests pass

# 4. Check logs
docker-compose logs backend
# Expected: No errors, "Application startup complete"

✅ Frontend Verification

cd grimlock/frontend

# 1. Install dependencies
npm install

# 2. Build check
npm run build
# Expected: ✓ Compiled successfully

# 3. Start dev server
npm run dev
# Expected: Server running on http://localhost:3000

✅ Environment Variables

Backend (.env)

# Required
ANTHROPIC_API_KEY=sk-ant-xxxxx  # Your Claude API key
SECRET_KEY=xxxxx                 # Random secret for JWT
DATABASE_URL=postgresql://grimlock:grimlock@postgres/grimlock

# Optional (already configured)
REDIS_URL=redis://redis:6379

Frontend (.env.local)

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_WS_URL=http://localhost:8000

FIRST-TIME SETUP

Step 1: Clone Repository

git clone https://gittea.979labs.com/amitis55/grimlock.git
cd grimlock

Step 2: Configure Backend

cd backend

# Copy example env
cp .env.example .env

# Edit .env and add:
# - Your ANTHROPIC_API_KEY
# - Generate SECRET_KEY: openssl rand -hex 32
nano .env

Step 3: Start Services

cd ..  # back to grimlock/

# Start backend with Docker
docker-compose up -d

# Wait 10 seconds for startup
sleep 10

# Verify backend
curl http://localhost:8000/api/health

Step 4: Setup Frontend

cd frontend

# Install dependencies
npm install

# Create env file
cat > .env.local << EOF
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_WS_URL=http://localhost:8000
EOF

# Start frontend
npm run dev

Step 5: First User

# Open browser: http://localhost:3000
# Click "Sign up"
# Fill in:
#   Email: admin@vectorzulu.com
#   Name: Admin
#   Password: (secure password)
#   Role: admin

# This creates first user and channel

PRODUCTION DEPLOYMENT

Option 1: Docker Compose (Recommended)

1. Production Environment

# Create production .env
cd grimlock/backend
cp .env.example .env.production

# Edit with production values:
# - DATABASE_URL (production PostgreSQL)
# - REDIS_URL (production Redis)
# - ANTHROPIC_API_KEY
# - Secure SECRET_KEY

2. Frontend Build

cd grimlock/frontend

# Production build
npm run build

# Test production build
npm start

3. Deploy with Docker

cd grimlock

# Use production env
export ENV_FILE=backend/.env.production

# Build and start
docker-compose -f docker-compose.prod.yml up -d

# Note: You'll need to create docker-compose.prod.yml
# with production settings

Option 2: Separate Services

Backend Deployment (e.g., AWS EC2, DigitalOcean)

# On server
cd grimlock/backend

# Install Python dependencies
pip install -r requirements.txt

# Run with production server
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

# Or with gunicorn
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000

Frontend Deployment (e.g., Vercel, Netlify)

# Set environment variables in platform:
NEXT_PUBLIC_API_URL=https://api.yourdomain.com
NEXT_PUBLIC_WS_URL=https://api.yourdomain.com

# Deploy
npm run build

# Platform will auto-deploy from git

Option 3: Kubernetes (Advanced)

Coming soon: Helm charts and K8s manifests

DATABASE SETUP

Local Development

# PostgreSQL is included in docker-compose
# No additional setup needed

# To access database:
docker-compose exec postgres psql -U grimlock -d grimlock

Production Database

Option A: Managed Database (Recommended)

AWS RDS (PostgreSQL)
DigitalOcean Managed Database
Google Cloud SQL
Heroku Postgres

Option B: Self-Hosted

# Install PostgreSQL
sudo apt install postgresql postgresql-contrib

# Create database
sudo -u postgres psql
CREATE DATABASE grimlock;
CREATE USER grimlock WITH PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE grimlock TO grimlock;

# Update DATABASE_URL in .env
DATABASE_URL=postgresql://grimlock:secure_password@localhost/grimlock

TESTING DEPLOYMENT

Automated Health Checks

#!/bin/bash
# health_check.sh

# Backend health
HEALTH=$(curl -s http://localhost:8000/api/health)
if echo "$HEALTH" | grep -q '"status":"healthy"'; then
  echo "✓ Backend healthy"
else
  echo "✗ Backend unhealthy"
  exit 1
fi

# Frontend health
FRONTEND=$(curl -s http://localhost:3000)
if [ $? -eq 0 ]; then
  echo "✓ Frontend accessible"
else
  echo "✗ Frontend not accessible"
  exit 1
fi

# WebSocket test
# (would need more complex test)

echo "✓ All services healthy"

Manual Test Flow

Registration
- Go to /register
- Create account
- Should redirect to /
Channel Creation
- Click "+" next to Channels
- Create "general" channel
- Should open channel page
Messaging
- Send test message
- Should appear instantly
- Send "@grimlock hello"
- Should get AI response
Real-Time
- Open second browser/incognito
- Login as different user
- Send message from one
- Should appear in both instantly
Direct Messages
- Click on a user in sidebar
- Send DM
- Should work like channels

MONITORING

Backend Logs

# Docker logs
docker-compose logs -f backend

# Look for:
# - "Application startup complete"
# - "Connected to database"
# - "WebSocket server started"
# - No error tracebacks

Frontend Logs

# Terminal output
npm run dev

# Browser console
# - No red errors
# - WebSocket connected
# - API calls succeeding

Database Health

# Check connections
docker-compose exec postgres psql -U grimlock -d grimlock -c "SELECT count(*) FROM pg_stat_activity;"

# Check table sizes
docker-compose exec postgres psql -U grimlock -d grimlock -c "
SELECT 
  schemaname,
  tablename,
  pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size
FROM pg_tables
WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;
"

PERFORMANCE TUNING

Backend

# main.py - increase workers for production
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(
        "main:app",
        host="0.0.0.0",
        port=8000,
        workers=4,  # Adjust based on CPU cores
        reload=False  # Disable in production
    )

Database

-- Add indexes for common queries
CREATE INDEX idx_messages_channel_id ON messages(channel_id);
CREATE INDEX idx_messages_created_at ON messages(created_at DESC);
CREATE INDEX idx_direct_messages_sender ON direct_messages(sender_id);
CREATE INDEX idx_direct_messages_recipient ON direct_messages(recipient_id);

Frontend

# Production build is already optimized
npm run build

# Features:
# - Code splitting
# - Minification
# - Tree shaking
# - Image optimization

BACKUP & RECOVERY

Database Backup

# Automated daily backup
#!/bin/bash
# backup.sh

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="grimlock_backup_$DATE.sql"

docker-compose exec -T postgres pg_dump -U grimlock grimlock > "$BACKUP_FILE"

# Compress
gzip "$BACKUP_FILE"

# Upload to S3 (optional)
# aws s3 cp "$BACKUP_FILE.gz" s3://your-bucket/backups/

echo "Backup completed: $BACKUP_FILE.gz"

Restore from Backup

# Stop services
docker-compose down

# Restore database
gunzip grimlock_backup_20260213.sql.gz
docker-compose exec -T postgres psql -U grimlock grimlock < grimlock_backup_20260213.sql

# Start services
docker-compose up -d

SECURITY CHECKLIST

✅ Before Production

Change default SECRET_KEY
Use strong database password
Enable HTTPS (SSL/TLS)
Set CORS policies
Rate limiting configured
Input validation enabled
SQL injection protection (using ORM)
XSS protection (React auto-escapes)
CSRF tokens (for forms)
Regular security updates

✅ Access Control

Database not publicly accessible
Redis not publicly accessible
Backend API behind firewall
Only HTTPS endpoints exposed
Admin routes protected
File uploads size-limited
File types validated

TROUBLESHOOTING

Backend Won't Start

# Check logs
docker-compose logs backend

# Common issues:
# 1. Database not ready
#    Solution: Wait 10 seconds after docker-compose up

# 2. ANTHROPIC_API_KEY missing
#    Solution: Add to .env file

# 3. Port 8000 in use
#    Solution: Stop other service or change port

Frontend Won't Build

# Clear cache and rebuild
rm -rf .next node_modules package-lock.json
npm install
npm run build

# Check for type errors
npm run build 2>&1 | grep "Type error"

WebSocket Not Connecting

# Check backend WebSocket server
docker-compose logs backend | grep -i websocket

# Check frontend .env.local
cat frontend/.env.local

# Must have:
# NEXT_PUBLIC_WS_URL=http://localhost:8000

# In browser console, should see:
# "WebSocket connected"

Database Connection Issues

# Test database connectivity
docker-compose exec postgres psql -U grimlock -d grimlock -c "SELECT 1;"

# Check DATABASE_URL in .env
# Should be: postgresql://grimlock:grimlock@postgres/grimlock

SCALING CONSIDERATIONS

Horizontal Scaling

Backend:

Stateless design allows multiple instances
Load balancer distributes requests
Shared PostgreSQL + Redis
WebSocket sticky sessions required

Frontend:

Static files can be CDN-cached
Multiple Next.js instances
API calls to load balancer

Database Scaling

Read Replicas:

Master for writes
Replicas for reads
Update DATABASE_URL for reads

Connection Pooling:

Use PgBouncer
Limit connections per instance
Monitor connection usage

Caching

Redis:

Cache user sessions
Cache channel lists
Cache recent messages
Set TTL appropriately

COST ESTIMATES

Development (Current)

Backend: Local Docker (free)
Frontend: Local development (free)
Database: Local PostgreSQL (free)
AI: ~$0.003/query
- 100 queries/day = $9/month

Production (Estimated)

Small Team (10 users)

VPS (2 GB RAM): $12/month
Database (managed): $15/month
AI (1000 queries/day): $90/month
Total: ~$120/month

Medium Team (50 users)

VPS (4 GB RAM): $24/month
Database (managed): $25/month
AI (5000 queries/day): $450/month
Total: ~$500/month

Enterprise (500 users)

Kubernetes cluster: $200/month
Database (HA): $100/month
AI (50K queries/day): $4,500/month
CDN: $50/month
Total: ~$5,000/month

SUCCESS METRICS

Technical Health

Backend uptime > 99.9%
API response time < 200ms
WebSocket latency < 50ms
Database queries < 100ms
Zero critical errors

User Adoption

10+ daily active users
100+ messages per day
10+ channels created
50+ @grimlock queries/day
Users prefer over Slack

Business Impact

5+ hours saved per week
Reduced context switching
Faster decision making
Better knowledge retention
Team satisfaction improved

NEXT STEPS AFTER DEPLOYMENT

Week 1: Internal Alpha
- Deploy to staging
- Team of 5 tests
- Gather feedback
- Fix critical bugs
Week 2: Internal Beta
- Deploy to production
- All Vector Zulu employees
- Monitor performance
- Iterate on UX
Week 3-4: Optimization
- Add missing features
- Improve performance
- Polish UI/UX
- Write user docs
Month 2: Scale
- Handle more users
- Add integrations
- External beta
- Prepare for launch

SUPPORT & MAINTENANCE

Daily

Monitor logs for errors
Check system health
Review AI usage
Respond to user issues

Weekly

Database backup verification
Security updates
Performance review
User feedback review

Monthly

Dependency updates
Feature planning
Cost review
Capacity planning

CONTACT & RESOURCES

Repository: https://gittea.979labs.com/amitis55/grimlock

Documentation:

FINAL.md - Backend API
FRONTEND.md - Frontend deployment
ARCHITECTURE.md - System design
This file - Deployment guide

Questions? Create an issue in the repository or contact the dev team.

🚀 READY TO DEPLOY

You now have:

✅ Complete backend platform
✅ Complete frontend application
✅ Deployment documentation
✅ Testing procedures
✅ Monitoring setup
✅ Troubleshooting guide

Next command:

cd grimlock && docker-compose up -d && cd frontend && npm run dev

Then open: http://localhost:3000

Welcome to Grimlock.

13 KiB Raw Blame History