Skip to content

troubleshooting

Jump to bottom
docisit edited this page Jul 27, 2026 · 2 revisions

❓ Troubleshooting & FAQ

Common issues, solutions, and frequently asked questions for ITG Media App.

🔧 Troubleshooting Guide

WebRTC / LiveKit Issues

Problem Solution
Guests can't connect (ICE failed) Check TURN server is running. Verify firewall ports 7881-7882 TCP/UDP and 50000-60000 UDP are open. Test with LiveKit WebRTC tester
WebSocket connection fails Check Nginx config — ensure Upgrade and Connection headers are set. Verify LIVEKIT_URL uses wss:// (not ws://) in production
LiveKit server won't start Check logs: docker logs livekit. Verify livekit.yaml syntax and API keys. Ensure Docker has network access
No video from guest Guest must allow camera permissions in browser. Check guest's browser console for errors. Verify guest has stable upload bandwidth
Audio echo / feedback Guest must wear headphones/earbuds. Enable echo cancellation in browser. Reduce guest speaker volume
Choppy video Check packet loss in Director panel stream health. Guest may need to reduce resolution. Check server CPU during broadcast
TURN not working Test with turnutils_uclient. Check coturn is running: systemctl status coturn. Verify firewall ports 3478, 5349

Backend Issues

Problem Solution
502 Bad Gateway Django/Next.js not running: pm2 list. Check systemctl status nginx. Verify service ports are correct
500 Internal Server Error Check Django logs: pm2 logs mediasite-django. Verify .env settings. Check database connection
Static files 404 (admin CSS missing) Run python manage.py collectstatic --noinput. Verify STATIC_ROOT and Nginx static location match
WebSocket won't connect Ensure Daphne is running on port 8001: pm2 list. Check Nginx /ws/ location block has WebSocket upgrade headers
Redis connection refused Redis not running: sudo systemctl start redis-server. Check REDIS_URL in .env. Verify Redis is bound to localhost
Database connection error PostgreSQL not running: sudo systemctl start postgresql. Verify DATABASE_URL. Check database user permissions
Migrations fail Run python manage.py migrate --fake <app_name> <migration> if a migration was applied manually. Delete migration files carefully

Frontend Issues

Problem Solution
Page loads blank Check browser console for JavaScript errors. Verify Next.js is running: pm2 list. Check FRONTEND_URL in .env
API calls fail (CORS) Verify FRONTEND_URL matches actual domain. Check ALLOWED_HOSTS includes the domain. Clear browser cache
Login redirects to localhost NEXTAUTH_URL and FRONTEND_URL must match production domain. Update .env.production and rebuild frontend
Slow page loads Next.js may need more resources. Increase PM2 instances. Check server load. Enable CDN caching
Images not loading Verify Nginx /media/ location path. Check file permissions. Run collectstatic

Docker Issues

Problem Solution
Container won't start Check logs: docker logs <container-name>. Verify .env.docker has all required variables. Check port conflicts
Port already in use Stop conflicting service: sudo lsof -i :<port>. Change port mapping in docker-compose
Database container data lost Mount a volume for PostgreSQL data. Add volume to docker-compose: ./pgdata:/var/lib/postgresql/data
Can't connect between containers Verify containers are on the same Docker network. Use container names as hostnames (not localhost)

Email Issues

Problem Solution
Verification emails not sent Check SMTP settings in .env. For dev, emails print to console. For prod, configure real SMTP (SendGrid, Mailgun)
Password reset link expired Links expire after configurable time. Request a new reset link. Check server time is correct
Emails go to spam Set up SPF, DKIM, and DMARC DNS records for your domain. Use a reputable SMTP provider

❓ Frequently Asked Questions

General

What is ITG Media App?

ITG Media App is an all-in-one live broadcasting platform. Host a show, bring in remote guests via their browser (no installs), manage a guest queue, and push your stream to YouTube, Facebook, and TikTok simultaneously. It's built with Django, Next.js, LiveKit, PostgreSQL, and Redis.

Where can I see it in action?

The live deployment is at https://donoconnor.com. You can register an account, explore the dashboard, and see how broadcasting works.

Is ITG Media App free?

Yes! ITG Media App is MIT licensed — free to use, modify, and run for personal or commercial projects. We ask that you keep the Don O'Connor logo and copyright notice on the site.

Does it run on Windows Server?

ITG Media App has been tested on Linux servers (Ubuntu 22.04/24.04 LTS). It has not been tested on Windows Server. Docker-based deployment may work on Windows via WSL2 or Docker Desktop, but production hosting is validated only on Linux.

Setup & Installation

What are the minimum server requirements?
  • CPU: 2 cores (4+ recommended for production)
  • RAM: 4 GB (8+ GB recommended, especially with AI features)
  • Storage: 40 GB SSD (80+ GB recommended)
  • OS: Ubuntu 22.04/24.04 LTS

See the Installation Guide for full details.

Can I use SQLite instead of PostgreSQL?

Yes, for development only. Leave DATABASE_URL blank in your .env and Django will use SQLite. For production, PostgreSQL is required — SQLite can't handle concurrent WebSocket connections and scales poorly.

Do I need Docker?

Docker is required for LiveKit (WebRTC infrastructure). The rest of ITG Media App can run on bare metal with PM2. If you use LiveKit Cloud, you don't need Docker at all. See the LiveKit Setup page.

How do I set up SSL/HTTPS?

Use Let's Encrypt with Certbot:

sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

Full instructions in the Deployment Guide.

Broadcasting

Do guests need to install anything?

No! Guests join through their browser — just click a link, allow camera and mic, and they're on. ITG Media App is a full PWA and works on desktop and mobile (iOS Safari, Android Chrome).

What internet speed do guests need?
  • 720p: 3+ Mbps upload
  • 1080p: 5+ Mbps upload
  • Guests should use a stable connection (Wi-Fi recommended over cellular)
  • Run the built-in speed test at /speedtest
Can I stream to multiple platforms at once?

Yes! ITG Media App supports simulcast to YouTube, Facebook, and TikTok simultaneously. Configure your stream keys in the Director Control panel or .env file. See the Director Control page.

How many guests can I have on a show?

There's no hard limit — it depends on your server's CPU, bandwidth, and the layout you choose (grid, side-by-side, PiP). For practical purposes, 4-6 simultaneous guests works well on a typical VPS. The Director panel lets you manage who's on screen at any time.

What's the default studio room name?

Broadcast_Studio_A1 is the default room. You can create additional rooms for individual shows or guests. Having a known room name makes it easy to reuse OBS browser source URLs.

AI Features

Do I need an OpenAI API key?

No! ITG Media App uses Ollama for local LLM inference. All AI processing happens on your server — no external API keys or third-party services needed. Your data stays private.

What AI model should I use?
  • Llama 3.1 8B — Best overall quality (~4.7 GB)
  • Mistral 7B — Good balance, slightly faster (~4.1 GB)
  • Phi-3 Mini — Lightweight, good for FAQ-only (~2.3 GB)
  • Llama 3.2 3B — Budget option (~2.0 GB)

See the AI Assistant page for setup instructions.

Can I disable the AI features?

Yes! The AI features are optional. Don't install Ollama, and the chatbot and avatar agent won't be available. There's no feature flag to toggle — they simply won't run without Ollama.

Security

How do I secure the admin panel?
  1. Change ADMIN_URL from the default admin/ to something hard to guess
  2. Set ADMIN_IP_WHITELIST to your static IP address(es)
  3. Use a strong password (20+ characters)
  4. Always serve over HTTPS

See the Admin Panel page for full security recommendations.

Is COPPA compliance included?

Yes! ITG Media App includes a COPPA age gate. Users under 13 are flagged for parental consent. A parent/guardian must complete the consent form before the under-13 account gets full access. No personal data is collected without verified consent.

Maintenance

How do I update ITG Media App? 
cd itg-media-engine
git pull origin main
source .venv/bin/activate
pip install -r requirements.txt
python manage.py migrate
python manage.py collectstatic --noinput
cd frontend && npm install && npm run build
pm2 restart all

See the Deployment Guide for full maintenance procedures.

How do I backup my data? 
# PostgreSQL dump
pg_dump -U media_user -h localhost media_db > backup_$(date +%Y%m%d).sql
gzip backup_$(date +%Y%m%d).sql

Set up a cron job for automated daily backups. Store backups off-server (S3, rsync to another machine).

How do I monitor server health?
  • PM2 monitoring: pm2 monit
  • System resources: htop, df -h, free -m
  • Docker: docker stats
  • Logs: pm2 logs, journalctl -u nginx
  • Stream health: Director Control panel shows real-time metrics

🚨 Emergency Procedures

All Services Down

# Check PM2 status
pm2 list

# Restart all services
pm2 restart all

# If PM2 isn't running
pm2 resurrect

# Check system resources
htop
free -m
df -h

Database Corruption

# Stop the application first
pm2 stop all

# Restore from backup
gunzip backup_YYYYMMDD.sql.gz
psql -U media_user -h localhost media_db < backup_YYYYMMDD.sql

# Restart
pm2 start all

SSL Certificate Expired

# Force renewal
sudo certbot renew --force-renewal

# Check certificate status
sudo certbot certificates

# Reload Nginx
sudo systemctl reload nginx

Disk Full

# Find large files
du -sh /* 2>/dev/null | sort -rh | head -20

# Clean Docker
docker system prune -a --volumes

# Clean PM2 logs
pm2 flush

# Clean apt cache
sudo apt clean
sudo apt autoremove

📞 Getting Help

If you've tried the troubleshooting steps and still have issues:

  1. Check logs first — pm2 logs, docker logs, journalctl
  2. Search existing issues — GitHub Issues
  3. Open a new issue — Include:
    • Clear description of the problem
    • Steps to reproduce
    • Expected vs actual behavior
    • Relevant log output
    • Environment (Docker/bare metal, browser, OS version)
  4. Discussions — GitHub Discussions

← Back to Wiki Home

Clone this wiki locally