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**:
   ```bash
   chmod +x StreamFlow-*.AppImage
   ```
3. **Run it**:
   ```bash
   ./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:**
```bash
sudo apt update
sudo apt install fuse libfuse2
```

**Fedora:**
```bash
sudo dnf install fuse fuse-libs
```

**Arch Linux:**
```bash
sudo pacman -S fuse2
```

**openSUSE:**
```bash
sudo zypper install fuse libfuse2
```

### Alternative: Extract and Run

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

```bash
./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:**
```bash
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**
```bash
sudo mkdir -p /opt/streamflow
./StreamFlow-*.AppImage --appimage-extract
sudo mv squashfs-root/* /opt/streamflow/
```

**Step 2: Create desktop entry**
```bash
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**
```bash
sudo update-desktop-database
```

**Step 4: Create symlink (optional)**
```bash
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:
```bash
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:**
```bash
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:**
   ```bash
   timedatectl status
   ```
   
   If time is not synchronized:
   ```bash
   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:

```bash
# 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:

```bash
./StreamFlow-*.AppImage --dev
```

Then press `Ctrl+Shift+I` to open DevTools.

---

## Uninstallation

### If installed via AppImageLauncher

```bash
# Remove from applications
appimagelauncherd --uninstall StreamFlow

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

### If manually integrated

```bash
# 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

```bash
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:**
```nginx
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.