streamflow/docs/CROSS_PLATFORM_DEPLOYMENT.md

# 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)