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
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:

cd k8s
cp secret.yaml.example secret.yaml

Edit secret.yaml and replace the placeholder values:

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:

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:

# 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

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

# 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

kubectl logs -f deployment/myorg-assistant

Access Pod Shell

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

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

Check Git Repository

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

Troubleshooting

Pod Crashes or Restarts

# 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:

   kubectl logs -f $POD_NAME
   

Repository Not Syncing

# 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

# 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

# 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:

# 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:

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:

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