streamflow/desktop-app/INSTALLATION.md

StreamFlow Desktop - Installation & Setup Guide

Quick Start

For End Users

1. Download the latest AppImage from the releases page
2. Make it executable:

   chmod +x StreamFlow-*.AppImage
   

3. Run it:

   ./StreamFlow-*.AppImage
   

That's it! The application will guide you through the server connection setup.

---

Detailed Installation

System Requirements

Minimum:

• Linux kernel 3.10+ (2013+)
• GLIBC 2.28+ (Ubuntu 18.04+, Debian 10+, Fedora 28+)
• 2 GB RAM
• 200 MB disk space
• X11 or Wayland display server

Recommended:

• Linux kernel 5.0+
• 4 GB+ RAM
• GPU with hardware acceleration (Intel QSV, AMD VA-API, or NVIDIA NVDEC)
• 1920x1080 display

FUSE Requirement

AppImage requires FUSE to run. Most modern Linux distributions have it installed by default.

Ubuntu/Debian:

sudo apt update
sudo apt install fuse libfuse2

Fedora:

sudo dnf install fuse fuse-libs

Arch Linux:

sudo pacman -S fuse2

openSUSE:

sudo zypper install fuse libfuse2

Alternative: Extract and Run

If FUSE is not available or you prefer not to use it:

./StreamFlow-*.AppImage --appimage-extract
cd squashfs-root
./AppRun

---

Desktop Integration

Method 1: Using AppImageLauncher (Recommended)

AppImageLauncher automatically integrates AppImages with your desktop environment.

Ubuntu/Debian:

sudo add-apt-repository ppa:appimagelauncher-team/stable
sudo apt update
sudo apt install appimagelauncher

After installation, just double-click the AppImage, and AppImageLauncher will offer to integrate it.

Method 2: Manual Integration

Step 1: Create application directory

sudo mkdir -p /opt/streamflow
./StreamFlow-*.AppImage --appimage-extract
sudo mv squashfs-root/* /opt/streamflow/

Step 2: Create desktop entry

sudo tee /usr/share/applications/streamflow.desktop > /dev/null << EOF
[Desktop Entry]
Name=StreamFlow
Comment=Stream IPTV content
Exec=/opt/streamflow/AppRun
Icon=/opt/streamflow/streamflow.png
Type=Application
Categories=AudioVideo;Player;TV;
Terminal=false
StartupNotify=true
EOF

Step 3: Update desktop database

sudo update-desktop-database

Step 4: Create symlink (optional)

sudo ln -s /opt/streamflow/AppRun /usr/local/bin/streamflow

Now you can launch StreamFlow from your application menu or by running streamflow in terminal.

---

First Launch Configuration

When you first launch StreamFlow Desktop, you'll see the server connection window.

Step 1: Enter Server URL

Enter the full URL of your StreamFlow server, including the protocol:

• https://streamflow.example.com (recommended)
• http://192.168.1.100:3000 (local network)
• http://localhost:3000 (local development)

Step 2: Test Connection

Click "Test Connection" to verify that:

• The server is reachable
• The URL is correct
• No firewall is blocking the connection

Step 3: Enter Credentials

Once the connection test succeeds:

1. Enter your username (or email)
2. Enter your password
3. (Optional) Check "Remember credentials" for automatic login

Security Note: Credentials are encrypted and stored locally on your device using Electron's secure storage.

Step 4: 2FA Authentication (if enabled)

If you have Two-Factor Authentication enabled:

1. Complete the username/password login
2. You'll be automatically redirected to the web app's 2FA page
3. Enter your 6-digit authenticator code
4. Or use one of your 8-character backup codes

---

Configuration Management

Changing Servers

To connect to a different server:

1. Go to File → Change Server in the menu bar
2. Enter the new server URL
3. Test connection and enter credentials

Clearing Stored Credentials

If you want to stop auto-login:

1. Go to File → Change Server
2. Uncheck "Remember credentials"
3. Connect again

Or delete the config file:

rm ~/.config/streamflow-config/config.json

---

Codec Support

StreamFlow Desktop includes native support for all modern video and audio codecs through Electron's Chromium engine.

Supported Video Codecs

• H.264 (AVC)
• H.265 (HEVC) - with hardware acceleration
• VP8
• VP9
• AV1

Supported Audio Codecs

• AAC
• MP3
• Opus
• Vorbis
• AC3 / E-AC3

Hardware Acceleration

Hardware acceleration is automatically enabled when available:

Intel (Quick Sync):

• Supported on 2nd gen Core processors and newer
• Automatically detected via VA-API

AMD:

• Supported on all modern Radeon GPUs
• Automatically detected via VA-API

NVIDIA:

• Supported on Maxwell (GTX 900 series) and newer
• Requires proprietary NVIDIA drivers with NVDEC support

To verify hardware acceleration is working:

1. Open Chrome/Chromium's internal page in StreamFlow (Developer Tools)
2. Navigate to chrome://gpu
3. Check "Video Acceleration Information"

---

Troubleshooting

AppImage doesn't start

Problem: Double-clicking does nothing, or shows "Permission denied"

Solution:

chmod +x StreamFlow-*.AppImage
./StreamFlow-*.AppImage

Problem: Error: fuse: device not found

Solution: Install FUSE (see installation section above) or extract and run manually.

---

Connection Issues

Problem: "Connection refused" error

Possible causes and solutions:

1. Server is not running

   • Verify the server is running: docker ps (if using Docker)
   • Check server logs for errors

2. Incorrect URL

   • Ensure you included http:// or https://
   • Verify the port number is correct
   • Try accessing the URL in a web browser first

3. Firewall blocking connection

   • Check local firewall: sudo ufw status
   • Check server firewall settings
   • If using Docker, ensure ports are exposed

4. SSL/TLS certificate issues

   • For self-signed certificates, the browser will show a warning
   • Accept the certificate in the browser first
   • Or use HTTP instead (not recommended for production)

---

Video Playback Issues

Problem: Video stutters or lags

Solutions:

1. Enable hardware acceleration (should be automatic)
2. Close other applications using GPU
3. Check your internet connection speed
4. Lower video quality in server settings

Problem: No video, only audio (or vice versa)

Solutions:

1. Check codec support in chrome://gpu
2. Update your GPU drivers
3. Try a different browser to verify it's not a server issue
4. Check server transcoding settings

Problem: Black screen

Solutions:

1. Check if hardware acceleration is causing issues:
   • Disable it temporarily in Chrome flags
   • Launch with: ./StreamFlow-*.AppImage --disable-gpu
2. Update GPU drivers
3. Check server stream format

---

2FA Issues

Problem: 2FA code always shows as invalid

Solutions:

1. Check system time synchronization:

   timedatectl status
   

   If time is not synchronized:

   sudo timedatectl set-ntp true
   

2. Verify authenticator app time:

   • Ensure your phone's time is set to automatic
   • Time zone should match your location

3. Use a backup code:

   • If you saved backup codes during 2FA setup
   • Use one of the 8-character codes instead

Problem: Lost 2FA device and no backup codes

Solution: Contact your server administrator to disable 2FA for your account.

---

Language/Translation Issues

Problem: UI appears in wrong language

Solution:

1. Change language in the connection window
2. Or change it in the web app settings after logging in
3. Language preference is saved automatically

---

Performance Issues

Problem: High CPU usage

Solutions:

1. Ensure hardware acceleration is enabled
2. Close unnecessary browser tabs in the app
3. Lower video quality settings
4. Check for background processes

Problem: High memory usage

Solutions:

1. Close and reopen the application
2. Clear browser cache (in web app settings)
3. Reduce number of simultaneous streams

---

Advanced Configuration

Custom Launch Parameters

You can pass additional parameters to Electron:

# Disable GPU acceleration
./StreamFlow-*.AppImage --disable-gpu

# Enable verbose logging
./StreamFlow-*.AppImage --enable-logging --v=1

# Use different config directory
./StreamFlow-*.AppImage --user-data-dir=/path/to/config

Development Mode

To enable developer tools:

./StreamFlow-*.AppImage --dev

Then press Ctrl+Shift+I to open DevTools.

---

Uninstallation

If installed via AppImageLauncher

# Remove from applications
appimagelauncherd --uninstall StreamFlow

# Delete the AppImage
rm ~/Applications/StreamFlow-*.AppImage

If manually integrated

# Remove desktop entry
sudo rm /usr/share/applications/streamflow.desktop
sudo update-desktop-database

# Remove application files
sudo rm -rf /opt/streamflow

# Remove symlink
sudo rm /usr/local/bin/streamflow

Remove configuration

rm -rf ~/.config/streamflow-config
rm -rf ~/.config/StreamFlow  # Electron user data

---

Getting Help

1. Check the documentation in /docs
2. Search for similar issues on GitHub
3. Enable debug logging and check logs
4. Contact your server administrator for server-specific issues
5. Open an issue on GitHub with:
   • OS version and distribution
   • AppImage version
   • Error messages or logs
   • Steps to reproduce

---

Security Best Practices

1. Always use HTTPS when connecting to remote servers
2. Enable 2FA on your account for additional security
3. Don't share credentials or backup codes
4. Keep the application updated to get security patches
5. Only download AppImages from official sources
6. Verify checksums of downloaded AppImages
7. Use strong passwords (minimum 12 characters)

---

Network Configuration

Using with Reverse Proxy (nginx, Apache)

If your StreamFlow server is behind a reverse proxy, ensure WebSocket connections are properly proxied.

nginx example:

location / {
    proxy_pass http://localhost:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

Using with VPN

StreamFlow Desktop works seamlessly with VPN connections. If your server is on a VPN:

1. Connect to your VPN first
2. Use the VPN IP address or hostname in the server URL
3. Ensure the VPN allows the necessary ports

---

Updating

AppImage Updates

AppImage doesn't have automatic updates. To update:

1. Download the new AppImage
2. Replace the old one
3. Your configuration and credentials are preserved

Checking for Updates

Check the releases page periodically for new versions:

• Bug fixes
• New features
• Security updates
• Performance improvements

---

Credits

Built with:

• Electron - Cross-platform desktop framework
• Node.js - JavaScript runtime
• Chromium - Web rendering engine
• electron-builder - Application packaging

---

For more information, visit the project documentation or contact your system administrator.