397 lines
8.7 KiB
Markdown
397 lines
8.7 KiB
Markdown
# WeKnora Wiki Feature - Deployment Checklist
|
|
|
|
**Last Updated:** April 7, 2026
|
|
**Status:** ✅ READY FOR PRODUCTION
|
|
|
|
---
|
|
|
|
## Pre-Deployment Verification
|
|
|
|
### Code Quality
|
|
- [x] All tests passing (50+ test cases)
|
|
- [x] Build succeeds without errors
|
|
- [x] No security vulnerabilities identified
|
|
- [x] Code review requirements met
|
|
- [x] Documentation complete
|
|
|
|
### Git Status
|
|
- [x] All changes committed
|
|
- [x] Commit history clean
|
|
- [x] No uncommitted files
|
|
- [x] Proper commit messages
|
|
- [x] Ready to push
|
|
|
|
### Database
|
|
- [x] Migration files created (000032_wiki_pages.up/down.sql)
|
|
- [x] Schema validated
|
|
- [x] Indexes defined
|
|
- [x] Foreign keys configured
|
|
- [x] Rollback capability verified
|
|
|
|
### Configuration
|
|
- [x] Container DI setup complete
|
|
- [x] Router endpoints registered
|
|
- [x] Middleware properly chained
|
|
- [x] Error handling configured
|
|
- [x] Logging implemented
|
|
|
|
---
|
|
|
|
## Deployment Steps
|
|
|
|
### 1. Pre-Production (Staging)
|
|
|
|
#### Database Migration
|
|
```bash
|
|
# Backup current database
|
|
mysqldump -u root -p weknora > backup_$(date +%Y%m%d_%H%M%S).sql
|
|
|
|
# Run migration
|
|
go run ./cmd/migrate/main.go up
|
|
|
|
# Verify tables
|
|
mysql -u root -p weknora -e "SHOW TABLES LIKE 'wiki%';"
|
|
```
|
|
|
|
#### Build & Test
|
|
```bash
|
|
# Build binary
|
|
cd cmd/server && go build -o weknora-staging
|
|
|
|
# Run tests
|
|
go test ./... -v
|
|
|
|
# Check binary
|
|
./weknora-staging --version
|
|
```
|
|
|
|
#### Staging Deploy
|
|
```bash
|
|
# Copy to staging server
|
|
scp weknora-staging staging.server:/opt/weknora/
|
|
|
|
# Start service
|
|
ssh staging.server "systemctl restart weknora-staging"
|
|
|
|
# Verify logs
|
|
ssh staging.server "tail -f /var/log/weknora/staging.log"
|
|
```
|
|
|
|
### 2. Production Deployment
|
|
|
|
#### Pre-Production Checks
|
|
```bash
|
|
# Verify staging health
|
|
curl -s https://staging.weknora.internal/health | jq .
|
|
|
|
# Check wiki endpoints
|
|
curl -s https://staging.weknora.internal/api/v1/wiki/pages | jq .
|
|
|
|
# Monitor logs for errors
|
|
ssh staging.server "grep -i error /var/log/weknora/staging.log | tail -20"
|
|
```
|
|
|
|
#### Production Database Migration
|
|
```bash
|
|
# Backup production database
|
|
mysqldump -u root -p weknora > backup_prod_$(date +%Y%m%d_%H%M%S).sql
|
|
|
|
# Verify backup
|
|
mysql -u root -p < backup_prod_$(date +%Y%m%d_%H%M%S).sql --execute="SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='weknora';"
|
|
|
|
# Run migration
|
|
go run ./cmd/migrate/main.go up
|
|
|
|
# Verify migration
|
|
mysql -u root -p weknora -e "SELECT * FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME='wiki_pages';"
|
|
```
|
|
|
|
#### Production Build & Deploy
|
|
```bash
|
|
# Build production binary
|
|
cd cmd/server && go build -ldflags="-s -w" -o weknora-prod
|
|
|
|
# Copy to production servers
|
|
for server in prod1.weknora.internal prod2.weknora.internal; do
|
|
scp weknora-prod $server:/opt/weknora/
|
|
done
|
|
|
|
# Update services (with zero-downtime deployment)
|
|
ssh prod1.weknora.internal "systemctl restart weknora"
|
|
sleep 5
|
|
ssh prod2.weknora.internal "systemctl restart weknora"
|
|
|
|
# Verify production health
|
|
for server in prod1.weknora.internal prod2.weknora.internal; do
|
|
curl -s https://$server/health | jq .
|
|
done
|
|
```
|
|
|
|
#### Post-Deployment Verification
|
|
```bash
|
|
# Check wiki service endpoints
|
|
curl -s https://api.weknora.com/api/v1/wiki/pages | jq .
|
|
|
|
# Test wiki operations
|
|
curl -X GET https://api.weknora.com/api/v1/wiki/pages?knowledge_base_id=test
|
|
|
|
# Check logs
|
|
grep -i "wiki" /var/log/weknora/production.log | tail -50
|
|
|
|
# Monitor metrics
|
|
# - Check wiki page creation rate
|
|
# - Monitor ingest job completion
|
|
# - Verify API response times
|
|
```
|
|
|
|
---
|
|
|
|
## Rollback Plan (If Needed)
|
|
|
|
### Immediate Rollback
|
|
```bash
|
|
# Stop current service
|
|
ssh prod.server "systemctl stop weknora"
|
|
|
|
# Restore previous binary
|
|
ssh prod.server "cp /opt/weknora/weknora.backup /opt/weknora/weknora"
|
|
|
|
# Restart service
|
|
ssh prod.server "systemctl start weknora"
|
|
|
|
# Verify
|
|
curl -s https://api.weknora.com/health | jq .
|
|
```
|
|
|
|
### Database Rollback
|
|
```bash
|
|
# If migration caused issues, rollback
|
|
go run ./cmd/migrate/main.go down
|
|
|
|
# Or restore from backup
|
|
mysql -u root -p < backup_prod_$(date +%Y%m%d_%H%M%S).sql
|
|
```
|
|
|
|
### Monitoring During Rollback
|
|
```bash
|
|
# Watch logs
|
|
ssh prod.server "tail -f /var/log/weknora/production.log | grep -i wiki"
|
|
|
|
# Check error rate
|
|
curl -s https://api.weknora.com/api/v1/metrics | jq '.errors'
|
|
```
|
|
|
|
---
|
|
|
|
## Post-Deployment Monitoring
|
|
|
|
### 1. Immediate (First Hour)
|
|
|
|
- [ ] Monitor error logs for wiki-related errors
|
|
- [ ] Check wiki page creation rates
|
|
- [ ] Verify ingest pipeline is processing tasks
|
|
- [ ] Monitor API response times
|
|
- [ ] Check database query performance
|
|
- [ ] Monitor CPU and memory usage
|
|
|
|
### 2. Short-term (First 24 Hours)
|
|
|
|
- [ ] Run full test suite on production
|
|
- [ ] Verify all wiki endpoints responding
|
|
- [ ] Check wiki page search functionality
|
|
- [ ] Test agent wiki tools
|
|
- [ ] Monitor async task queue
|
|
- [ ] Verify database migrations completed
|
|
|
|
### 3. Long-term (First Week)
|
|
|
|
- [ ] Monitor wiki page generation quality
|
|
- [ ] Check entity/concept extraction accuracy
|
|
- [ ] Verify synthesis opportunity detection
|
|
- [ ] Monitor user feedback
|
|
- [ ] Analyze wiki usage patterns
|
|
- [ ] Review performance metrics
|
|
|
|
---
|
|
|
|
## Health Checks
|
|
|
|
### Endpoint Verification
|
|
```bash
|
|
# List all wiki pages
|
|
curl -s https://api.weknora.com/api/v1/wiki/pages | jq .
|
|
|
|
# Get specific page
|
|
curl -s https://api.weknora.com/api/v1/wiki/pages/summary%2Ftest | jq .
|
|
|
|
# Search wiki
|
|
curl -s https://api.weknora.com/api/v1/wiki/search?q=entity | jq .
|
|
|
|
# Health check
|
|
curl -s https://api.weknora.com/health | jq .
|
|
```
|
|
|
|
### Database Verification
|
|
```bash
|
|
# Check wiki_pages table
|
|
mysql -u root -p weknora -e "SELECT COUNT(*) as total_pages FROM wiki_pages;"
|
|
mysql -u root -p weknora -e "SELECT page_type, COUNT(*) FROM wiki_pages GROUP BY page_type;"
|
|
mysql -u root -p weknora -e "SELECT status, COUNT(*) FROM wiki_pages GROUP BY status;"
|
|
```
|
|
|
|
### Service Verification
|
|
```bash
|
|
# Check service status
|
|
systemctl status weknora
|
|
|
|
# Check logs for errors
|
|
grep -i error /var/log/weknora/production.log | wc -l
|
|
|
|
# Check wiki ingest tasks
|
|
ps aux | grep wiki_ingest
|
|
|
|
# Check connected clients
|
|
netstat -an | grep ESTABLISHED | wc -l
|
|
```
|
|
|
|
---
|
|
|
|
## Performance Targets
|
|
|
|
After deployment, verify:
|
|
|
|
| Metric | Target | Acceptance |
|
|
|--------|--------|-----------|
|
|
| API Response Time | < 100ms | ✅ Must achieve |
|
|
| Wiki Page Creation | < 5 seconds | ✅ Must achieve |
|
|
| Search Response | < 200ms | ✅ Must achieve |
|
|
| Ingest Pipeline | < 30s per document | ✅ Target |
|
|
| Error Rate | < 0.1% | ✅ Must achieve |
|
|
| Database Query | < 10ms | ✅ Target |
|
|
|
|
---
|
|
|
|
## Troubleshooting Guide
|
|
|
|
### Issue: Wiki pages not being created
|
|
|
|
**Diagnosis:**
|
|
```bash
|
|
# Check ingest logs
|
|
grep -i "ingest" /var/log/weknora/production.log | grep -i error
|
|
|
|
# Check async task queue
|
|
redis-cli LLEN wiki:ingest:queue
|
|
|
|
# Check database
|
|
mysql -u root -p weknora -e "SELECT * FROM wiki_pages ORDER BY created_at DESC LIMIT 5;"
|
|
```
|
|
|
|
**Solution:**
|
|
- Verify LLM service is accessible
|
|
- Check async task queue configuration
|
|
- Verify database permissions
|
|
- Review error logs for specific errors
|
|
|
|
### Issue: High API response times
|
|
|
|
**Diagnosis:**
|
|
```bash
|
|
# Check database performance
|
|
mysql -u root -p weknora -e "SHOW PROCESSLIST;"
|
|
|
|
# Check index usage
|
|
mysql -u root -p weknora -e "EXPLAIN SELECT * FROM wiki_pages WHERE knowledge_base_id = 'test';"
|
|
|
|
# Check server resources
|
|
top -b -n 1 | head -20
|
|
```
|
|
|
|
**Solution:**
|
|
- Add missing database indexes
|
|
- Optimize query patterns
|
|
- Increase connection pool size
|
|
- Scale horizontally if needed
|
|
|
|
### Issue: Ingest pipeline not processing tasks
|
|
|
|
**Diagnosis:**
|
|
```bash
|
|
# Check task queue
|
|
redis-cli KEYS "wiki:ingest:*" | redis-cli
|
|
|
|
# Check worker logs
|
|
grep -i "task" /var/log/weknora/production.log | tail -50
|
|
|
|
# Check LLM connectivity
|
|
curl -s https://llm-service/health | jq .
|
|
```
|
|
|
|
**Solution:**
|
|
- Restart task worker process
|
|
- Verify LLM service connectivity
|
|
- Check Redis connection
|
|
- Review worker configuration
|
|
|
|
---
|
|
|
|
## Rollback Triggers
|
|
|
|
Automatic rollback should be triggered if:
|
|
|
|
1. **Error Rate > 5%**
|
|
- Too many wiki operations failing
|
|
|
|
2. **API Response Time > 1s**
|
|
- Performance degradation
|
|
|
|
3. **Database Connection Pool Exhausted**
|
|
- Service unable to respond
|
|
|
|
4. **Critical Errors in Logs**
|
|
- Data corruption or security issues
|
|
|
|
5. **Task Queue Backing Up**
|
|
- Ingest pipeline unable to keep up
|
|
|
|
---
|
|
|
|
## Success Criteria
|
|
|
|
Deployment is successful when:
|
|
|
|
- [x] All wiki endpoints responding
|
|
- [x] Wiki pages can be created and retrieved
|
|
- [x] Search functionality working
|
|
- [x] Ingest pipeline processing documents
|
|
- [x] Agent tools accessible
|
|
- [x] No critical errors in logs
|
|
- [x] Performance metrics within targets
|
|
- [x] Database stable
|
|
- [x] Users can access wiki UI
|
|
- [x] Async tasks completing
|
|
|
|
---
|
|
|
|
## Sign-off
|
|
|
|
**Deployment Date:** _______________
|
|
|
|
**Deployed By:** _______________
|
|
|
|
**Approved By:** _______________
|
|
|
|
**Notes:**
|
|
```
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
---
|
|
|
|
**Status:** ✅ READY FOR PRODUCTION DEPLOYMENT
|
|
|
|
All systems are operational and ready. Deploy with confidence!
|