claude-configs/skills/major-domo/workflows/bot-deployment.md

# Discord Bot Deployment Workflow

## Overview

Deploy Discord bot updates to production or test servers safely.

## When to Use

- After code changes or bug fixes
- New feature implementation
- Configuration updates
- Dependency updates

## Environments

### Production Bot
- **Server**: Main SBA Discord server
- **Bot Location**: Akamai Linode server (ssh akamai)
- **Code Path**: `/home/cal/major-domo/discord-app/` or `/home/cal/major-domo/discord-app-v2/`
- **Impact**: Affects all league members

### Development Bot
- **Server**: Test Discord server
- **Bot Location**: Dev server (10.10.0.42) or local machine
- **Code Path**: `/mnt/NV2/Development/major-domo/discord-app-v2/`
- **Impact**: Testing only

## Pre-Deployment Checklist

- [ ] Code changes tested locally
- [ ] Tests passing (`pytest`)
- [ ] Environment variables configured
- [ ] API connectivity verified
- [ ] Breaking changes documented
- [ ] Version number updated (if applicable)

## Deployment Steps

### 1. Test on Development Bot First

**Local Testing**:
```bash
cd /mnt/NV2/Development/major-domo/discord-app-v2
python bot.py
```

**Verify**:
- Bot comes online
- Commands respond correctly
- No error messages in console
- API calls work properly

### 2. Commit Changes (if needed)

```bash
cd /mnt/NV2/Development/major-domo
git status
git add <files>
git commit -m "Description of changes"
git push origin main
```

### 3. Deploy to Production

**SSH to Production Server**:
```bash
ssh akamai
cd ~/major-domo/discord-app-v2  # or discord-app
```

**Pull Latest Changes**:
```bash
git pull origin main
```

**Stop Current Bot**:
```bash
# Find the bot process
ps aux | grep bot.py

# Kill the process (replace PID)
kill <PID>

# Or if using screen/tmux
screen -r major-domo  # Attach to screen session
# Ctrl+C to stop bot
```

**Restart Bot**:
```bash
# If using screen
screen -S major-domo
python bot.py

# Detach with Ctrl+A then D

# Or run in background
nohup python bot.py > bot.log 2>&1 &
```

**Verify Bot is Online**:
- Check Discord - bot should show as online
- Test a simple command (e.g., `/league`, `/teams`)
- Monitor logs for errors

### 4. Post-Deployment Verification

**Check Logs**:
```bash
# If using nohup
tail -f bot.log

# If using screen
screen -r major-domo
# View output
```

**Test Key Commands**:
- `/league` - League status
- `/teams` - Team list
- `/player <name>` - Player lookup
- Custom commands if modified

**Monitor for Issues**:
- Watch Discord for error messages
- Check API response times
- Verify database connectivity
- Test with multiple users

### 5. Rollback (if needed)

If issues arise:

```bash
# SSH to production
ssh akamai
cd ~/major-domo/discord-app-v2

# Stop bot
kill <PID>  # or Ctrl+C in screen

# Revert to previous commit
git log --oneline  # Find previous commit hash
git checkout <previous-commit-hash>

# Restart bot
python bot.py
```

## Common Issues

### Bot Won't Start

**Check Environment Variables**:
```bash
echo $BOT_TOKEN
echo $API_TOKEN
echo $DB_URL
```

**Missing Dependencies**:
```bash
pip install -r requirements.txt
```

**Port Already in Use**:
```bash
# Find process using bot's port
ps aux | grep bot.py
kill <PID>
```

### Bot Online But Commands Fail

**API Connectivity**:
```bash
curl http://10.10.0.42/api/v3/current
```

**Check Bot Logs**:
- Look for error messages
- Verify API token is valid
- Check database connection

### Permission Errors

**Discord Permissions**:
- Verify bot has necessary Discord permissions
- Check role hierarchy
- Ensure slash commands are registered

## Bot-Specific Notes

### Discord Bot v2 (Recommended)

**Features**:
- Enhanced logging with `@logged_command` decorator
- Structured command packages
- Improved type safety
- Better error handling

**Location**: `/home/cal/major-domo/discord-app-v2/`

**Running**:
```bash
python bot.py
```

### Discord Bot v1 (Legacy)

**Location**: `/home/cal/major-domo/discord-app/`

**Running**:
```bash
python majordomo.py
```

## Emergency Procedures

### Bot Goes Offline During Game

1. **Quick Restart**:
```bash
ssh akamai
screen -r major-domo
# If frozen, Ctrl+C then restart
python bot.py
```

2. **Use Backup Bot** (if configured):
- Start secondary bot instance
- Announce temporary backup bot to users

3. **Notify Users**:
- Post in Discord about bot status
- Provide ETA for resolution

## Production Server Access

**SSH Connection**:
```bash
ssh akamai
```

**Bot Management**:
```bash
# Check if bot is running
ps aux | grep bot.py

# View screen sessions
screen -ls

# Attach to bot screen
screen -r major-domo

# Create new screen session
screen -S major-domo

# Detach from screen
# Ctrl+A then D
```

## Environment Variables

**Required**:
- `BOT_TOKEN` - Discord bot token
- `API_TOKEN` - Database API token
- `DB_URL` - API endpoint URL (http://10.10.0.42/api/v3)
- `GUILD_ID` - Discord server ID

**Optional**:
- `LOG_LEVEL` - Logging verbosity (DEBUG/INFO/WARN/ERROR)
- `TESTING` - Enable test mode

**Set Environment Variables**:
```bash
export BOT_TOKEN='your-token'
export API_TOKEN='your-api-token'
export DB_URL='http://10.10.0.42/api/v3'
export GUILD_ID='your-guild-id'
```

**Persistent Variables** (add to `~/.bashrc` or `~/.profile`):
```bash
echo 'export BOT_TOKEN="your-token"' >> ~/.bashrc
source ~/.bashrc
```

## Monitoring

**Log Files**:
- Discord bot v2: `logs/discord.log` (rotating, 32MB max)
- Discord bot v1: `logs/discord.log`

**Watch Logs in Real-Time**:
```bash
tail -f logs/discord.log
```

**Check Bot Health**:
```bash
# Test API connectivity
curl -H "Authorization: Bearer $API_TOKEN" http://10.10.0.42/api/v3/current

# Check bot process
ps aux | grep bot.py
```

## Post-Deployment

- [ ] Bot is online and responding
- [ ] All commands tested and working
- [ ] No errors in logs
- [ ] Users notified of any changes
- [ ] Documentation updated (if needed)
- [ ] Monitoring confirmed working

## Automation Opportunities

**Future Improvements**:
- Automated deployment script
- Health check monitoring
- Automatic restart on crash
- Deployment notifications to Discord
- Integration with CI/CD pipeline

---

**Last Updated**: 2025-11-10
**Maintainer**: Cal Corum