myorg-assistant/DEPLOYMENT.md

# MyOrg Assistant - Deployment Guide

This guide explains how to deploy the MyOrg Assistant to a k3s Kubernetes cluster.

## Prerequisites

- k3s cluster running and accessible
- `kubectl` configured to connect to your cluster
- Docker installed for building images
- Discord bot token (see "Creating a Discord Bot" below)
- Access to LiteLLM endpoint
- Git repository for your myorg data

## Creating a Discord Bot

1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
2. Click "New Application" and give it a name
3. Go to "Bot" section and click "Add Bot"
4. Under "Privileged Gateway Intents", enable:
   - Message Content Intent
   - Server Members Intent
5. Click "Reset Token" to get your bot token (save this securely!)
6. Go to "OAuth2" → "URL Generator"
7. Select scopes: `bot`, `applications.commands`
8. Select bot permissions: `Send Messages`, `Read Messages/View Channels`, `Read Message History`
9. Copy the generated URL and open it to invite the bot to your server

## Configuration

### 1. Create Secret

Copy the secret template and fill in your credentials:

```bash
cd k8s
cp secret.yaml.example secret.yaml
```

Edit `secret.yaml` and replace the placeholder values:

```yaml
stringData:
  DISCORD_BOT_TOKEN: "your-actual-discord-bot-token"
  DISCORD_CHANNEL_ID: "your-discord-channel-id"
  LITELLM_API_KEY: "your-litellm-api-key"
  GIT_REPO_URL: "https://github.com/yourusername/myorg.git"
  GIT_USERNAME: "yourusername"
  GIT_TOKEN: "your-github-personal-access-token"
  WEB_SECRET_KEY: "generate-a-random-secret-key"
  WEB_PASSWORD: "optional-web-ui-password"
```

**Important:** Never commit `secret.yaml` to git! It contains sensitive credentials.

### 2. Review ConfigMap

Check `k8s/configmap.yaml` and adjust if needed:

- `LITELLM_ENDPOINT`: Your LiteLLM service endpoint
- `TIMEZONE`: Your timezone (default: Europe/Madrid)
- Storage class in `pvc.yaml` (default: local-path for k3s)

## Deployment

### Automated Deployment

Use the deployment script for easy setup:

```bash
cd k8s
./deploy.sh
```

This script will:
1. Build the Docker image
2. Load it into k3s
3. Apply all Kubernetes manifests
4. Wait for the deployment to be ready
5. Show logs and status

### Manual Deployment

If you prefer to deploy manually:

```bash
# Build Docker image
docker build -t myorg-assistant:latest .

# Load into k3s
docker save myorg-assistant:latest | sudo k3s ctr images import -

# Apply Kubernetes resources
kubectl apply -f k8s/secret.yaml
kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/pvc.yaml
kubectl apply -f k8s/service.yaml
kubectl apply -f k8s/deployment.yaml

# Check status
kubectl get pods -l app=myorg-assistant
kubectl logs -f deployment/myorg-assistant
```

## Verification

### Check Pod Status

```bash
kubectl get pods -l app=myorg-assistant
```

You should see:
```
NAME                               READY   STATUS    RESTARTS   AGE
myorg-assistant-xxxxx-xxxxx        1/1     Running   0          2m
```

### View Logs

```bash
# Get pod name
POD_NAME=$(kubectl get pods -l app=myorg-assistant -o jsonpath='{.items[0].metadata.name}')

# View logs
kubectl logs -f $POD_NAME

# You should see:
# ✅ Logged in as YourBotName#1234
# 📊 Connected to X server(s)
# 🤖 Agent initialized with 12 tools
# 🎉 MyOrg Assistant is ready!
```

### Test in Discord

1. Go to your Discord server where the bot is installed
2. Mention the bot or send it a DM:
   - `@YourBot help`
   - `@YourBot add task: Test the bot`
   - `@YourBot /tasks`

## Repository Sync

The deployment includes an init container that:
- Clones your myorg repository on first start
- Pulls latest changes on restart
- Configures git credentials

The bot will:
- Commit changes when you modify tasks
- Auto-push after commits (can be disabled)
- Sync with remote every 15 minutes (Phase 3 feature)

## Monitoring

### View Logs

```bash
kubectl logs -f deployment/myorg-assistant
```

### Access Pod Shell

```bash
kubectl exec -it $POD_NAME -- /bin/bash

# Inside pod:
cd /data/myorg
git status
ls -la
```

### Check Git Repository

```bash
kubectl exec -it $POD_NAME -- sh -c "cd /data/myorg && git log --oneline -10"
```

## Troubleshooting

### Pod Crashes or Restarts

```bash
# Check pod events
kubectl describe pod $POD_NAME

# Check logs including previous crashes
kubectl logs $POD_NAME --previous
```

Common issues:
- **Missing secret**: Ensure `secret.yaml` is applied
- **Wrong Discord token**: Check token in secret
- **LiteLLM connection failed**: Verify endpoint and API key
- **Git clone failed**: Check repository URL and token permissions

### Bot Not Responding

1. Check bot is online in Discord
2. Verify bot has proper permissions in server
3. Check logs for errors:
   ```bash
   kubectl logs -f $POD_NAME
   ```

### Repository Not Syncing

```bash
# Check git status inside pod
kubectl exec -it $POD_NAME -- sh -c "cd /data/myorg && git status"

# Check git remote
kubectl exec -it $POD_NAME -- sh -c "cd /data/myorg && git remote -v"

# Manual pull
kubectl exec -it $POD_NAME -- sh -c "cd /data/myorg && git pull"
```

## Updating the Deployment

### Update Code

```bash
# Rebuild image
docker build -t myorg-assistant:latest .

# Reload into k3s
docker save myorg-assistant:latest | sudo k3s ctr images import -

# Restart deployment
kubectl rollout restart deployment/myorg-assistant

# Wait for new pod
kubectl rollout status deployment/myorg-assistant
```

### Update Configuration

```bash
# Edit configmap or secret
kubectl edit configmap myorg-assistant-config
# or
kubectl apply -f k8s/secret.yaml

# Restart to pick up changes
kubectl rollout restart deployment/myorg-assistant
```

## Scaling

The bot is designed to run as a single replica (one instance). If you need higher availability:

```bash
# Note: Multiple replicas may cause conflicts with git repository
# Consider implementing distributed locking first
kubectl scale deployment myorg-assistant --replicas=1
```

## Cleanup

To remove the deployment:

```bash
kubectl delete -f k8s/deployment.yaml
kubectl delete -f k8s/service.yaml
kubectl delete -f k8s/pvc.yaml
kubectl delete -f k8s/configmap.yaml
kubectl delete -f k8s/secret.yaml
```

Or delete everything at once:

```bash
kubectl delete deployment,service,pvc,configmap,secret -l app=myorg-assistant
```

**Warning:** This will delete the PVC and all data in it. Back up your myorg repository first!

## Next Steps

- **Phase 3**: Add scheduled briefings (morning/evening)
- **Phase 4**: Deploy web interface with Ingress
- **Phase 5**: Add intelligent suggestions and goal tracking

## Support

For issues or questions:
- Check logs: `kubectl logs -f deployment/myorg-assistant`
- Review pod events: `kubectl describe pod $POD_NAME`
- Test locally first: `python -m src.main cli`