426 lines
8.8 KiB
Markdown
426 lines
8.8 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
1. **Generate Assets:**
|
|
```bash
|
|
./scripts/generate-assets.sh
|
|
```
|
|
|
|
2. **Test PWA:**
|
|
```bash
|
|
./scripts/test-pwa.sh
|
|
```
|
|
|
|
3. **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:
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
cd desktop-app
|
|
npm install
|
|
./build.sh
|
|
|
|
# Output: dist/StreamFlow-1.1.0-x86_64.AppImage
|
|
```
|
|
|
|
### Install:
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
./scripts/build-android.sh
|
|
```
|
|
|
|
### Requirements:
|
|
- Node.js 18+
|
|
- Android Studio
|
|
- Android SDK
|
|
- Java JDK 11+
|
|
|
|
### Steps:
|
|
1. Build frontend: `npm run build`
|
|
2. Initialize Capacitor: `npx cap init`
|
|
3. Add Android: `npx cap add android`
|
|
4. Sync assets: `npx cap sync android`
|
|
5. 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:
|
|
|
|
```bash
|
|
./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:**
|
|
```bash
|
|
# Check browser console for errors
|
|
# Verify HTTPS (or localhost)
|
|
# Clear browser cache
|
|
```
|
|
|
|
**Icons not showing:**
|
|
```bash
|
|
./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:**
|
|
```bash
|
|
# Verify update server is running
|
|
docker logs streamflow | grep "Update server"
|
|
curl http://localhost:9000/latest-linux.yml
|
|
```
|
|
|
|
**FUSE errors:**
|
|
```bash
|
|
sudo apt install fuse libfuse2
|
|
./StreamFlow-*.AppImage --appimage-extract-and-run
|
|
```
|
|
|
|
### Docker Issues:
|
|
|
|
**Codec not found:**
|
|
```bash
|
|
# Check FFmpeg installation
|
|
docker exec streamflow ffmpeg -codecs | grep h264
|
|
docker exec streamflow ffmpeg -encoders
|
|
```
|
|
|
|
**Port conflicts:**
|
|
```bash
|
|
# Check ports
|
|
ss -tlnp | grep -E ':(9000|12345)'
|
|
# Kill conflicting processes
|
|
sudo lsof -ti:9000 | xargs -r kill -9
|
|
```
|
|
|
|
---
|
|
|
|
## 📚 Additional Resources
|
|
|
|
### Documentation:
|
|
- [Architecture Guide](ARCHITECTURE.md)
|
|
- [Build Guide](BUILD.md)
|
|
- [Desktop App Guide](../desktop-app/README.md)
|
|
- [Security Audit](../desktop-app/SECURITY_AUDIT.md)
|
|
|
|
### External:
|
|
- [PWA Documentation](https://web.dev/progressive-web-apps/)
|
|
- [Capacitor Documentation](https://capacitorjs.com/docs)
|
|
- [Electron Builder](https://www.electron.build/)
|
|
- [FFmpeg Codecs](https://ffmpeg.org/documentation.html)
|
|
|
|
---
|
|
|
|
## 📞 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)
|