first commit
This commit is contained in:
Roger Oriol
348
QUICKSTART.md
Normal file
348
QUICKSTART.md
Normal file
@@ -0,0 +1,348 @@
|
||||
# MyOrg Assistant - Quick Start Guide
|
||||
|
||||
Get your personal assistant up and running in 15 minutes!
|
||||
|
||||
## What You're Building
|
||||
|
||||
A complete AI-powered personal assistant that:
|
||||
- 🤖 Manages your GTD tasks via Discord or web interface
|
||||
- 🌅 Sends morning briefings at 8 AM
|
||||
- 🌆 Sends evening summaries at 8 PM
|
||||
- ⏰ Warns about deadlines automatically
|
||||
- 🔄 Syncs everything via git
|
||||
- 📊 Provides a beautiful web dashboard
|
||||
|
||||
## Prerequisites Checklist
|
||||
|
||||
Before starting, ensure you have:
|
||||
|
||||
- [ ] **Python 3.11+** installed
|
||||
- [ ] **Git** installed
|
||||
- [ ] **LiteLLM endpoint** running (with Claude API access)
|
||||
- [ ] **Discord bot** created (5 min setup - see below)
|
||||
- [ ] **myorg repository** (or use test data)
|
||||
- [ ] **k3s cluster** (optional - for production deployment)
|
||||
|
||||
## Step 1: Get the Code (2 minutes)
|
||||
|
||||
```bash
|
||||
git clone <your-repo-url>
|
||||
cd myorg-assistant
|
||||
|
||||
# Create virtual environment
|
||||
python -m venv venv
|
||||
source venv/bin/activate # Windows: venv\Scripts\activate
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
## Step 2: Create Discord Bot (5 minutes)
|
||||
|
||||
1. Visit [Discord Developer Portal](https://discord.com/developers/applications)
|
||||
2. Click "New Application" → Name it "MyOrg Assistant"
|
||||
3. Go to "Bot" → Click "Add Bot"
|
||||
4. Enable these intents:
|
||||
- ✅ Message Content Intent
|
||||
- ✅ Server Members Intent
|
||||
5. Click "Reset Token" → **Copy this token!**
|
||||
6. Go to "OAuth2" → "URL Generator"
|
||||
- Check: `bot`, `applications.commands`
|
||||
- Bot Permissions: `Send Messages`, `Read Messages`, `Read Message History`
|
||||
7. Open the generated URL to invite bot to your server
|
||||
|
||||
## Step 3: Configure Environment (3 minutes)
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Edit `.env` and fill in:
|
||||
|
||||
```bash
|
||||
# === REQUIRED ===
|
||||
|
||||
# Your LiteLLM endpoint
|
||||
LITELLM_ENDPOINT=http://localhost:4000
|
||||
LITELLM_API_KEY=sk-your-key
|
||||
|
||||
# Discord bot token (from Step 2)
|
||||
DISCORD_BOT_TOKEN=YOUR.BOT.TOKEN.HERE
|
||||
DISCORD_CHANNEL_ID=123456789 # Right-click channel → Copy ID
|
||||
|
||||
# Your myorg repository
|
||||
MYORG_REPO_PATH=./tests/fixtures/test_myorg # Use test data for now
|
||||
GIT_REPO_URL=https://github.com/yourusername/myorg.git
|
||||
GIT_USERNAME=yourusername
|
||||
GIT_TOKEN=ghp_your_github_token
|
||||
|
||||
# === OPTIONAL ===
|
||||
|
||||
# Web interface password (leave empty for no password)
|
||||
WEB_PASSWORD=mypassword
|
||||
|
||||
# Your timezone
|
||||
TIMEZONE=Europe/Madrid
|
||||
```
|
||||
|
||||
**Quick Tip**: Don't have a myorg repo? Use the test data included:
|
||||
```bash
|
||||
export MYORG_REPO_PATH=./tests/fixtures/test_myorg
|
||||
```
|
||||
|
||||
## Step 4: Test Locally (2 minutes)
|
||||
|
||||
### Test CLI Mode
|
||||
|
||||
```bash
|
||||
python -m src.main cli
|
||||
```
|
||||
|
||||
Try these commands:
|
||||
```
|
||||
You: list files
|
||||
You: show all tasks
|
||||
You: add task: Test the system @computer-deep
|
||||
You: exit
|
||||
```
|
||||
|
||||
### Test Discord Bot
|
||||
|
||||
```bash
|
||||
python -m src.main bot
|
||||
```
|
||||
|
||||
In Discord:
|
||||
```
|
||||
@MyOrgBot help
|
||||
@MyOrgBot add task: Test Discord integration
|
||||
@MyOrgBot /tasks
|
||||
```
|
||||
|
||||
### Test Web Interface
|
||||
|
||||
```bash
|
||||
python -m src.main web
|
||||
```
|
||||
|
||||
Visit: http://localhost:8000
|
||||
|
||||
## Step 5: Deploy to Kubernetes (3 minutes)
|
||||
|
||||
### Quick Deploy
|
||||
|
||||
```bash
|
||||
cd k8s
|
||||
|
||||
# 1. Create secret with your credentials
|
||||
cp secret.yaml.example secret.yaml
|
||||
# Edit secret.yaml with your tokens
|
||||
|
||||
kubectl apply -f secret.yaml
|
||||
|
||||
# 2. Run deployment script
|
||||
./deploy.sh
|
||||
```
|
||||
|
||||
### Verify Deployment
|
||||
|
||||
```bash
|
||||
# Check pod status
|
||||
kubectl get pods -l app=myorg-assistant
|
||||
|
||||
# View logs
|
||||
kubectl logs -f deployment/myorg-assistant
|
||||
|
||||
# Check scheduled jobs
|
||||
kubectl get cronjobs
|
||||
```
|
||||
|
||||
You should see:
|
||||
- Main pod running (Discord bot + web server)
|
||||
- 5 CronJobs configured
|
||||
- Web service exposed on port 8000
|
||||
|
||||
## What Happens Next?
|
||||
|
||||
Once deployed, your assistant will:
|
||||
|
||||
**Immediately:**
|
||||
- ✅ Respond to Discord messages
|
||||
- ✅ Serve web interface at port 8000
|
||||
- ✅ Sync git every 15 minutes
|
||||
|
||||
**At 8:00 AM (your timezone):**
|
||||
- 🌅 Send morning briefing to Discord
|
||||
|
||||
**Every Hour:**
|
||||
- ⏰ Check deadlines and send warnings if needed
|
||||
|
||||
**At 8:00 PM:**
|
||||
- 🌆 Send evening summary to Discord
|
||||
|
||||
**Every Monday at 9 AM:**
|
||||
- ⏸️ Send waiting list follow-up
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Discord
|
||||
|
||||
**Add Tasks:**
|
||||
```
|
||||
@MyOrgBot Add task: Buy groceries tomorrow @recados
|
||||
@MyOrgBot Recordatori: Review PR +work due:2026-02-05
|
||||
```
|
||||
|
||||
**Check Tasks:**
|
||||
```
|
||||
@MyOrgBot What should I work on? I have 2 hours @computer-deep
|
||||
@MyOrgBot /tasks priority:A
|
||||
@MyOrgBot Show tasks for project myorg-assistant
|
||||
```
|
||||
|
||||
**Get Information:**
|
||||
```
|
||||
@MyOrgBot /today
|
||||
@MyOrgBot /briefing
|
||||
@MyOrgBot What's my calendar like this week?
|
||||
```
|
||||
|
||||
### Web Interface
|
||||
|
||||
Navigate to:
|
||||
- **Dashboard** (`/`) - Today's overview
|
||||
- **Chat** (`/chat`) - Talk to assistant
|
||||
- **Tasks** (`/tasks`) - Manage todos
|
||||
- **Calendar** (`/calendar`) - View events
|
||||
- **Projects** (`/projects`) - Track projects
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Bot Not Responding?
|
||||
|
||||
```bash
|
||||
# Check logs
|
||||
kubectl logs -f deployment/myorg-assistant
|
||||
|
||||
# Common fixes:
|
||||
# 1. Verify Discord token in secret
|
||||
# 2. Check bot has permissions in server
|
||||
# 3. Ensure Message Content Intent is enabled
|
||||
```
|
||||
|
||||
### LiteLLM Connection Error?
|
||||
|
||||
```bash
|
||||
# Test endpoint
|
||||
curl http://your-litellm-endpoint:4000/health
|
||||
|
||||
# Verify these in .env:
|
||||
LITELLM_ENDPOINT=http://... (correct URL?)
|
||||
LITELLM_API_KEY=... (valid key?)
|
||||
```
|
||||
|
||||
### Git Sync Failing?
|
||||
|
||||
```bash
|
||||
# Check git job logs
|
||||
kubectl logs job/myorg-git-sync-xxxxx
|
||||
|
||||
# Common fixes:
|
||||
# 1. Verify git token has repo permissions
|
||||
# 2. Check repository URL is correct
|
||||
# 3. Ensure branch name matches (default: main)
|
||||
```
|
||||
|
||||
### Web Interface 401 Unauthorized?
|
||||
|
||||
If you set `WEB_PASSWORD`, use HTTP Basic Auth:
|
||||
- Username: (any value)
|
||||
- Password: your WEB_PASSWORD value
|
||||
|
||||
Or remove the password from .env to disable auth.
|
||||
|
||||
## Next Steps
|
||||
|
||||
### For Production Use
|
||||
|
||||
1. **Set up your real myorg repository:**
|
||||
```bash
|
||||
# Update .env with your repo
|
||||
MYORG_REPO_PATH=/path/to/your/myorg
|
||||
GIT_REPO_URL=https://github.com/you/myorg.git
|
||||
```
|
||||
|
||||
2. **Configure external access:**
|
||||
```bash
|
||||
# Edit k8s/ingress.yaml with your domain
|
||||
kubectl apply -f k8s/ingress.yaml
|
||||
```
|
||||
|
||||
3. **Adjust timezone:**
|
||||
```bash
|
||||
# In .env or k8s/configmap.yaml
|
||||
TIMEZONE=Your/Timezone
|
||||
```
|
||||
|
||||
4. **Customize briefing times:**
|
||||
Edit the schedule in:
|
||||
- `k8s/cronjobs/morning-briefing.yaml` (default: 8 AM)
|
||||
- `k8s/cronjobs/evening-summary.yaml` (default: 8 PM)
|
||||
|
||||
### Explore Features
|
||||
|
||||
- Read [README.md](README.md) for full documentation
|
||||
- Check [DEPLOYMENT.md](DEPLOYMENT.md) for advanced deployment
|
||||
- See [project-plan.md](project-plan.md) for architecture details
|
||||
|
||||
## Getting Help
|
||||
|
||||
**Logs are your friend:**
|
||||
```bash
|
||||
# Main app logs
|
||||
kubectl logs -f deployment/myorg-assistant
|
||||
|
||||
# Specific job logs
|
||||
kubectl get jobs
|
||||
kubectl logs job/myorg-morning-briefing-xxxxx
|
||||
```
|
||||
|
||||
**Common Commands:**
|
||||
```bash
|
||||
# Restart deployment
|
||||
kubectl rollout restart deployment/myorg-assistant
|
||||
|
||||
# Check all resources
|
||||
kubectl get all -l app=myorg-assistant
|
||||
|
||||
# Delete everything (careful!)
|
||||
kubectl delete -f k8s/
|
||||
```
|
||||
|
||||
## Success! 🎉
|
||||
|
||||
You now have:
|
||||
- ✅ AI assistant managing your GTD system
|
||||
- ✅ Discord bot for mobile/quick access
|
||||
- ✅ Web dashboard for detailed management
|
||||
- ✅ Automated daily briefings
|
||||
- ✅ Deadline warnings
|
||||
- ✅ Automatic git synchronization
|
||||
|
||||
**Your morning tomorrow will look like this:**
|
||||
|
||||
```
|
||||
🌅 Good Morning! - Saturday, February 01, 2026
|
||||
|
||||
📅 Today's Schedule:
|
||||
• 09:00 Morning coffee @personal
|
||||
• 14:00 Work on myorg assistant +myorg-assistant
|
||||
|
||||
✅ Priority Tasks:
|
||||
• (A) Complete Phase 4 +myorg-assistant @computer-deep
|
||||
• (B) Review documentation +myorg-assistant
|
||||
|
||||
Have a productive day! 🚀
|
||||
```
|
||||
|
||||
Welcome to your new AI-powered productivity system! 🤖✨
|
||||
Reference in New Issue
Block a user