8.8 KiB
8.8 KiB
StreamFlow - Cross-Platform Deployment Guide
Complete guide for deploying StreamFlow across all platforms: Web, PWA, Linux AppImage, and Android APK.
🎯 Platform Support Matrix
| Feature | Web | PWA | Linux AppImage | Android APK |
|---|---|---|---|---|
| Live TV Streaming | ✅ | ✅ | ✅ | 🔄 (Planned) |
| Hardware Acceleration | ✅ | ✅ | ✅ | 🔄 (Planned) |
| Offline Mode | ⚠️ | ✅ | ✅ | 🔄 (Planned) |
| System Tray | ❌ | ❌ | ✅ | ❌ |
| Auto-Update | ❌ | ⚠️ | ✅ | 🔄 (Planned) |
| Picture-in-Picture | ✅ | ✅ | ✅ | 🔄 (Planned) |
| 2FA Support | ✅ | ✅ | ✅ | 🔄 (Planned) |
| Chromecast | ⚠️ | ⚠️ | ✅ | 🔄 (Planned) |
Legend:
- ✅ Fully Supported
- ⚠️ Partial Support / Browser Dependent
- 🔄 Planned / In Development
- ❌ Not Available
🐳 Docker Container (Server-Side)
What's Bundled in Docker:
✅ Media Processing:
- FFmpeg with all codecs (H.264, H.265, VP8, VP9, AV1)
- Hardware acceleration (Intel Quick Sync, VAAPI, NVIDIA)
- Audio codecs (AAC, Opus, MP3, Vorbis, Theora)
- Streamlink for stream extraction
- yt-dlp for additional sources
✅ Server Features:
- Live TV & Radio streaming
- Recording scheduler
- User authentication & 2FA
- Database (SQLite)
- API endpoints
- Update server for desktop app
✅ PWA Assets:
- Service worker
- Web manifest
- Icons (all sizes)
- Offline caching strategy
Codecs Included:
# Video Codecs
- H.264 (AVC) via x264
- H.265 (HEVC) via x265
- VP8/VP9 via libvpx
- AV1 via aom
- Theora
# Audio Codecs
- AAC via fdk-aac
- MP3 via lame
- Opus via libopus
- Vorbis via libvorbis
# Subtitle Support
- ASS/SSA via libass
- WebVTT
- SRT
# Container Formats
- MP4, MKV, WebM, FLV, TS
- M3U8 (HLS)
- DASH
Build Docker Container:
cd /home/iulian/projects/tv
docker compose build --no-cache
docker compose up -d
🌐 Web Application
Features (Client-Side):
- React 18 + Vite + MUI
- Responsive design (mobile, tablet, desktop)
- Light/Dark theme
- Multi-language (EN, RO)
- Video.js player with HLS support
- WebRTC for low-latency (when available)
What's NOT in Docker (Client-Side):
❌ Native OS integration ❌ System tray ❌ Auto-update mechanism ❌ Full offline mode ❌ Native notifications (uses browser)
Access:
http://localhost:12345
📱 Progressive Web App (PWA)
Features:
✅ Installable on desktop & mobile ✅ Offline static assets caching ✅ Service worker for background sync ✅ Push notifications (browser dependent) ✅ App-like experience ✅ Home screen icon
Setup:
-
Generate Assets:
./scripts/generate-assets.sh -
Test PWA:
./scripts/test-pwa.sh -
Install on Device:
- Desktop Chrome: Click install icon in address bar
- Android Chrome: Menu → "Add to Home screen"
- iOS Safari: Share → "Add to Home Screen"
Requirements:
- HTTPS in production (localhost works for testing)
- Valid manifest.json ✅
- Service worker registered ✅
- Icons (192x192, 512x512 minimum) ✅
Lighthouse Audit:
npm install -g lighthouse
lighthouse http://localhost:12345 --view --only-categories=pwa
🐧 Linux Desktop App (Electron AppImage)
Features:
✅ Native desktop application ✅ System tray integration ✅ Auto-update from Docker container ✅ Offline mode with caching ✅ Picture-in-Picture ✅ Chromecast support ✅ Encrypted credential storage ✅ Hardware acceleration
Build:
cd desktop-app
npm install
./build.sh
# Output: dist/StreamFlow-1.1.0-x86_64.AppImage
Install:
chmod +x StreamFlow-*.AppImage
./StreamFlow-*.AppImage
Features from Container:
- Updates served from http://localhost:9000
- Streams media from http://localhost:12345
- Uses container's codecs for transcoding
🤖 Android APK (Future)
Planned Features:
🔄 Native Android app via Capacitor 🔄 Google Play Store distribution 🔄 Hardware video decoding 🔄 Background playback 🔄 Android TV support 🔄 Picture-in-Picture 🔄 Offline downloads
Build (When Ready):
./scripts/build-android.sh
Requirements:
- Node.js 18+
- Android Studio
- Android SDK
- Java JDK 11+
Steps:
- Build frontend:
npm run build - Initialize Capacitor:
npx cap init - Add Android:
npx cap add android - Sync assets:
npx cap sync android - Build APK:
cd android && ./gradlew assembleDebug
Distribution:
- Debug APK: For testing
- Release APK: Signed for production
- Google Play: AAB format required
🎨 Asset Management
Generate All Platform Assets:
./scripts/generate-assets.sh
Generates:
- PWA icons (72px to 512px)
- iOS icons (180x180, 167x167)
- Android icons (mdpi to xxxhdpi)
- Desktop icons (512x512)
- Favicon (16x16, 32x32)
- Splash screens (all iOS sizes)
Source Icon:
- Location:
frontend/public/icons/icon-512x512.svg - Format: SVG (vector) for best quality
- Fallback: PNG files generated automatically
🚀 Deployment Checklist
Development:
- Docker container running
- Update server running (port 9000)
- Main server running (port 12345)
- PWA manifest configured
- Service worker registered
- Icons generated
Testing:
- Test web app in Chrome/Firefox
- Install PWA on desktop
- Install PWA on Android
- Install PWA on iOS
- Test AppImage on Linux
- Run Lighthouse audit
- Test offline mode
- Test hardware acceleration
Production:
- HTTPS enabled
- Valid SSL certificate
- Environment variables set
- Secrets configured
- Backup strategy in place
- Monitoring enabled
- Update server accessible
- CDN for static assets (optional)
📊 Platform Comparison
Web App:
Pros:
- ✅ Universal access (any device)
- ✅ No installation required
- ✅ Easy updates (server-side)
- ✅ Cross-platform
Cons:
- ❌ Requires internet connection
- ❌ No native OS integration
- ❌ Limited background tasks
- ❌ Browser dependent features
PWA:
Pros:
- ✅ Installable like native app
- ✅ Works offline (partial)
- ✅ Push notifications
- ✅ Smaller download than native
- ✅ Automatic updates
Cons:
- ❌ Limited iOS support
- ❌ No system tray
- ❌ Browser engine limitations
- ❌ Partial offline support
Linux AppImage:
Pros:
- ✅ Full native experience
- ✅ System tray integration
- ✅ Auto-updates
- ✅ Complete offline mode
- ✅ Best performance
Cons:
- ❌ Linux only
- ❌ Larger download (~100MB)
- ❌ Requires desktop environment
- ❌ Platform-specific builds
Android APK (Planned):
Pros:
- ✅ Native Android experience
- ✅ Play Store distribution
- ✅ Background playback
- ✅ Android TV support
- ✅ Better mobile performance
Cons:
- ❌ Requires development
- ❌ Separate codebase maintenance
- ❌ Play Store requirements
- ❌ Android-specific testing
🔧 Troubleshooting
Web/PWA Issues:
Service worker not registering:
# Check browser console for errors
# Verify HTTPS (or localhost)
# Clear browser cache
Icons not showing:
./scripts/generate-assets.sh
docker compose build --no-cache
docker compose up -d
Offline mode not working:
- Check service worker in DevTools → Application
- Verify cache strategy in service-worker.js
- Test with DevTools → Network → Offline
AppImage Issues:
Update check failing:
# Verify update server is running
docker logs streamflow | grep "Update server"
curl http://localhost:9000/latest-linux.yml
FUSE errors:
sudo apt install fuse libfuse2
./StreamFlow-*.AppImage --appimage-extract-and-run
Docker Issues:
Codec not found:
# Check FFmpeg installation
docker exec streamflow ffmpeg -codecs | grep h264
docker exec streamflow ffmpeg -encoders
Port conflicts:
# Check ports
ss -tlnp | grep -E ':(9000|12345)'
# Kill conflicting processes
sudo lsof -ti:9000 | xargs -r kill -9
📚 Additional Resources
Documentation:
External:
📞 Support
For issues, questions, or contributions:
- Check documentation first
- Review troubleshooting section
- Check Docker logs:
docker logs streamflow - Check browser console for client errors
Version: 1.1.0
Last Updated: December 2025
Platforms: Web, PWA, Linux AppImage, Android (Planned)