first commit

2026-02-03 23:50:19 +01:00
commit 87fb32b559
80 changed files with 8884 additions and 0 deletions
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -0,0 +1,290 @@
+# 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`