Admin Bud-E

English

Deutsch

English

Deutsch

Appearance

FAQ & Tips ​

Quick answers to common questions and helpful tips for Admin Bud-E administrators.

General Questions ​

What is Admin Bud-E? ​

Admin Bud-E is an open-source middleware that sits between AI assistant frontends (like School Bud-E) and AI providers (like Google Vertex AI, Together, Mistral). It:

  • Routes requests to configured providers
  • Tracks usage (tokens, characters, duration)
  • Manages user credits and budgets
  • Provides admin dashboard for management
  • Supports GDPR-compliant deployments

See Introduction for details.

Is it free? ​

Admin Bud-E software: Yes, open-source and free.

Costs you'll incur:

  • Server hosting: ~€3-7/month for a small VPS
  • AI provider usage: Pay-as-you-go (Google Vertex, Together, etc.)

Do I need coding skills? ​

Basic deployment: No. Follow the Installation Guide step-by-step.

Advanced customization: Yes, if you want to modify code or add features.

Can I use it for commercial purposes? ​

Check the repository's license (typically MIT or Apache 2.0, which allow commercial use). For legal certainty, consult the LICENSE file in the repository.

Setup & Installation ​

Which server should I choose? ​

Recommended for EU/GDPR:

Size: 2 vCPU, 4 GB RAM, 40 GB storage is sufficient for most schools.

See Server Setup for details.

Can I run it on my laptop? ​

For testing: Yes, install locally with python serve.py.

For production: No. Users need 24/7 access, so use a VPS with a public IP.

Do I need a domain name? ​

Recommended: Yes, for HTTPS and professional appearance.

Required: No, you can use http://SERVER_IP:8000/admin for testing.

How to get one:

  • Buy from registrar (Namecheap, Google Domains, etc.)
  • Point A record to your server's IP
  • Set up TLS with Let's Encrypt (free)

How do I enable HTTPS? ​

Use a reverse proxy (Caddy or Nginx) with Let's Encrypt:

Option 1: Caddy (easiest)

bash
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

# Create Caddyfile
sudo nano /etc/caddy/Caddyfile

Caddyfile contents:

admin.yourschool.edu {
    reverse_proxy localhost:8000
}
bash
sudo systemctl reload caddy

Option 2: Nginx + Certbot See Certbot instructions.

Configuration ​

Why doesn't "vertex" appear in my Routes? ​

Cause: Provider name must be exactly vertex (lowercase, no spaces).

Solution:

  1. Navigate to Providers
  2. Check your Vertex provider's name field
  3. If it's Vertex, VERTEX, or anything else, edit it to vertex exactly
  4. Save
  5. Return to Routes — vertex should now appear in the dropdown

What date range does "Export usage reports" use by default? ​

When both Start Date and End Date are empty:

  • Start: First day of current month
  • End: Today

Example: If today is December 15, 2024:

  • Exports: December 1-15, 2024

To export a full month:

  • Set Start: 2024-12-01
  • Set End: 2024-12-31

See Usage Reports for details.

How do I add another AI provider (like OpenAI or Mistral)? ​

  1. Navigate to Providers
  2. Click Add Provider
  3. Fill in:
    • Name: openai (or mistral, etc.)
    • Base URL: https://api.openai.com (or provider's endpoint)
    • API Key: Your key from the provider
  4. Click Save
  5. Navigate to Routes
  6. Create routes pointing to your new provider

See Provider Configuration for examples.

Can I use multiple providers at once? ​

Yes! This is the recommended setup for reliability.

Example:

  • Route 1: vertex, priority 1 (primary)
  • Route 2: together, priority 2 (failover)
  • Route 3: mistral, priority 3 (last resort)

If Vertex fails (rate limit, outage), requests automatically fall back to Together, then Mistral.

See Route Configuration for details.

Usage & Billing ​

How are credits calculated? ​

LLM/VLM:

Credits = (Input tokens × Input price per 1M) + (Output tokens × Output price per 1M)

TTS:

Credits = Characters × Price per character

ASR:

Credits = Audio duration (hours) × Price per hour

See Pricing Setup for examples.

Can I charge users real money? ​

Admin Bud-E doesn't handle payments. It only tracks credits (internal accounting).

If you want to charge:

  1. Use external payment system (Stripe, PayPal, etc.)
  2. Manually add credits to users after payment
  3. Track payments separately (spreadsheet, accounting software)

Alternative: Offer free access, funded by school/organization budget.

What's the difference between Allowance, Common Pool, and Personal Credits? ​

Consumption order:

  1. Allowance (periodic, refreshes daily/weekly/monthly)
  2. Common Pool (shared by all project members)
  3. Personal Credits (individual, permanent)

Example:

  • User has 50 allowance/day + 10,000 common pool + 500 personal
  • Request costs 100 credits
  • Deduction: 50 from allowance, 50 from common pool
  • Personal credits untouched

See Budgets & Allowance for details.

How do I prevent users from overspending? ​

Method 1: Allowance only

  • Set daily/weekly allowance
  • Disable common pool
  • No personal credits
  • Result: Hard cap per user

Method 2: Project budget limit

  • Set total project budget
  • Monitor usage
  • Don't refill common pool beyond budget

Method 3: Monitor and alert

  • Check usage reports weekly
  • Set thresholds (e.g., 80% of budget)
  • Adjust allowances or add credits as needed

Technical Issues ​

Service won't start after reboot ​

Likely cause: systemd service not enabled.

Solution:

bash
sudo systemctl enable admin-bude.service
sudo systemctl start admin-bude.service

Verify:

bash
sudo systemctl status admin-bude.service

Should show enabled in the Loaded: line.

"Database is locked" error ​

Cause: Another process is accessing the database.

Solution:

bash
# Find processes
sudo lsof /opt/bud-e/school-bud-e-middleware/admin_bude.db

# Kill the process (if it's a stuck old instance)
sudo kill <PID>

# Restart service
sudo systemctl restart admin-bude.service

Port 8000 already in use ​

Cause: Another service or old Admin Bud-E instance is using the port.

Solution:

bash
# Find what's using port 8000
sudo lsof -i :8000

# Kill it
sudo kill <PID>

# Or change Admin Bud-E port in env.sh:
export BIND_PORT="8001"

API requests return 401 Unauthorized ​

Possible causes:

  1. User's API key is incorrect
  2. User is deactivated
  3. API key was rotated

Solutions:

  1. Verify key: Have user check their key against Users page
  2. Check status: Ensure user is Active
  3. If key was rotated, provide new key

Requests are slow (high latency) ​

Possible causes:

  1. Server location far from provider region
  2. Provider rate limiting (throttling)
  3. Server underpowered

Solutions:

  1. Move server closer to provider (e.g., EU server for Vertex EU region)
  2. Add failover providers
  3. Upgrade server (more vCPUs)

Privacy & Compliance ​

Where is conversation history stored? ​

In the user's browser (local storage), not on the server.

The middleware only sees:

  • Request metadata (tokens, time)
  • No actual conversation content

See Privacy & EU Regions for details.

Is Admin Bud-E GDPR-compliant? ​

Admin Bud-E is designed for GDPR compliance, but you (as data controller) must:

  • Host in EU region
  • Use EU AI providers (Vertex EU, Mistral)
  • Sign DPAs with providers
  • Maintain data retention policy
  • Respond to user rights requests (access, deletion)

See Privacy & EU Regions for checklist.

Can users request deletion of their data? ​

Yes. Under GDPR, users have the right to erasure.

How to fulfill:

  1. Navigate to Users → Delete user
  2. Optionally anonymize usage logs
  3. Remove from backups after retention period

Do I need to notify my Data Protection Officer (DPO)? ​

If you're a school or public institution: Likely yes. Consult your DPO before deploying.

What to discuss:

  • Legal basis for processing
  • Data minimization measures
  • DPAs with AI providers
  • User notification plan

Best Practices ​

How often should I back up? ​

Minimum: Weekly

Recommended: Daily (automated)

Critical: Before major changes (bulk imports, updates, migrations)

See Backups & Restore for automation scripts.

Should I test backups? ​

Yes! Untested backups may be corrupted or incomplete.

How:

  • Monthly: Restore to test environment
  • Verify users, credits, usage logs

See Testing Restores.

How do I scale for more users? ​

Software scaling:

  • Admin Bud-E handles 1,000+ users on a small VPS
  • No code changes needed

Infrastructure scaling:

  1. Monitor server load (top, htop)
  2. If CPU >80% sustained, add vCPUs
  3. If memory >90%, add RAM
  4. If disk >80%, expand storage

Provider scaling:

  • Request quota increases from providers
  • Add more failover providers

What should I monitor? ​

Daily (automated):

  • Service uptime (UptimeRobot, Pingdom)
  • Backup success

Weekly:

  • Disk space
  • Usage anomalies (sudden spikes)
  • Error rates in logs

Monthly:

  • Total spending vs. budget
  • User growth
  • Provider performance

Troubleshooting Tips ​

Enable detailed logging ​

For debugging, increase log verbosity:

bash
# Edit systemd service
sudo systemctl edit admin-bude.service

Add:

[Service]
Environment="LOG_LEVEL=DEBUG"
bash
sudo systemctl daemon-reload
sudo systemctl restart admin-bude.service

# View detailed logs
sudo journalctl -u admin-bude.service -f

WARNING

Debug logging is verbose. Disable after troubleshooting to save disk space.

Check provider status ​

If many requests are failing:

Google Vertex AI:

Together AI:

Mistral AI:

OpenAI:

Reproduce the issue ​

When debugging:

  1. Note exact steps that trigger the problem
  2. Collect logs from that time period
  3. Try to reproduce in a test environment
  4. Report to GitHub with clear reproduction steps

Simplify configuration ​

If complex setup is failing:

  1. Temporarily remove all but one provider
  2. Use only LLM (disable VLM, TTS, ASR routes)
  3. Test with minimal pricing
  4. Once working, add components back one by one

Performance Tips ​

Optimize database ​

Quarterly:

bash
sudo systemctl stop admin-bude.service
sqlite3 /opt/bud-e/school-bud-e-middleware/admin_bude.db "VACUUM;"
sudo systemctl start admin-bude.service

Benefits: Smaller file, faster queries.

Archive old usage logs ​

After 6-12 months:

bash
# Export old logs
sqlite3 admin_bude.db <<EOF
.mode csv
.output old_logs_2023.csv
SELECT * FROM usage_logs WHERE timestamp < '2024-01-01';
EOF

# Delete from database
sqlite3 admin_bude.db "DELETE FROM usage_logs WHERE timestamp < '2024-01-01';"
sqlite3 admin_bude.db "VACUUM;"

Use caching (if supported) ​

Check Admin Bud-E documentation for caching options:

  • Redis for session caching
  • Query result caching
  • API response caching

Getting More Help ​

Documentation ​

Start here:

  1. Introduction — Understand the system
  2. Installation — Step-by-step setup
  3. Topic-specific guides (Providers, Routes, Pricing, etc.)

Community Support ​

  • GitHub Issues: school-bud-e-middleware issues
  • LAION Discord: Real-time community help
  • Reddit: r/LocalLLaMA or r/selfhosted (for general VPS/hosting questions)

Provider Support ​

For provider-specific issues:

Professional Support ​

For commercial deployments or custom development:

  • Contact LAION via laion.ai
  • Hire a DevOps consultant for infrastructure setup

Quick Reference ​

Common Commands ​

Check service status:

bash
sudo systemctl status admin-bude.service

Restart service:

bash
sudo systemctl restart admin-bude.service

View logs:

bash
sudo journalctl -u admin-bude.service -n 50

Check disk space:

bash
df -h

Backup database:

bash
cp /opt/bud-e/school-bud-e-middleware/admin_bude.db ~/backup_$(date +%Y-%m-%d).db

URLs ​

Admin Dashboard:

https://admin.yourschool.edu/admin

Health Check (for monitoring):

https://admin.yourschool.edu/health

API Endpoint (for frontend):

https://admin.yourschool.edu/v1/chat/completions

Default Locations ​

Database:

/opt/bud-e/school-bud-e-middleware/admin_bude.db

Logs:

/var/log/admin-bude.log
# or
sudo journalctl -u admin-bude.service

Service file:

/etc/systemd/system/admin-bude.service

Environment variables:

/opt/bud-e/env.sh

Still Have Questions? ​

Check these resources:

  1. This documentation (search or browse topics)
  2. GitHub repository README
  3. GitHub Issues (search existing issues)
  4. LAION Discord community

Open an issue: If you've found a bug or need a feature, open an issue on GitHub.

Contribute: Admin Bud-E is open-source! Contributions welcome:

  • Bug fixes
  • Documentation improvements
  • New features
  • Translations

See CONTRIBUTING.md in the repository.

Admin Bud-E / Bud-E / School Bud-E are developed by LAION e. V. (non-profit). Useful links: Hosted frontend · Middleware repo · Frontend repo · LAION blog