streamflow/docs/SETUP.md

# StreamFlow IPTV - Setup Guide

## System Requirements

- **Operating System**: Linux, macOS, or Windows with WSL2
- **Docker**: Version 20.10 or higher
- **Docker Compose**: Version 2.0 or higher
- **RAM**: Minimum 2GB (4GB recommended)
- **Storage**: Minimum 10GB free space
- **Ports**: Port 12345 must be available

## Installation Steps

### 1. Prerequisites Installation

#### Install Docker on Linux (Ubuntu/Debian)
```bash
# Update package index
sudo apt-get update

# Install required packages
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg lsb-release

# Add Docker's official GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Set up stable repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Add your user to docker group
sudo usermod -aG docker $USER

# Log out and back in for group changes to take effect
```

### 2. Clone or Navigate to Project

```bash
cd /home/iulian/projects/tv
```

### 3. Configure Environment Variables

```bash
# Copy the example environment file
cp .env.example .env

# Edit the .env file with your preferred text editor
nano .env  # or vim, code, etc.
```

**Important**: Change these values in production:
- `JWT_SECRET`: Use a strong, random string (at least 32 characters)
- `SESSION_SECRET`: Use a different strong, random string

Generate secure secrets:
```bash
# Generate random secrets
openssl rand -base64 32
```

### 4. Build and Start the Application

#### Option A: Using the provided script (Recommended)
```bash
chmod +x start.sh
./start.sh
```

#### Option B: Using Docker Compose directly
```bash
docker-compose build
docker-compose up -d
```

#### Option C: Using npm scripts
```bash
npm run docker:build
npm run docker:up
```

### 5. Verify Installation

Check if containers are running:
```bash
docker-compose ps
```

Expected output:
```
NAME                IMAGE               STATUS              PORTS
streamflow-app      streamflow:latest   Up X minutes        0.0.0.0:12345->12345/tcp
```

Check application health:
```bash
curl http://localhost:12345/api/health
```

Expected response:
```json
{"status":"ok","timestamp":"2024-XX-XXTXX:XX:XX.XXXZ"}
```

### 6. Access the Application

Open your web browser and navigate to:
```
http://localhost:12345
```

Or if accessing remotely:
```
http://YOUR_SERVER_IP:12345
```

### 7. Create Your First User Account

1. Click on "Sign Up" or "Register"
2. Fill in your details:
   - Username (alphanumeric, 3-50 characters)
   - Email (valid email address)
   - Password (minimum 8 characters)
3. Click "Sign Up"
4. You'll be automatically logged in

## Post-Installation Configuration

### Adding IPTV Playlists

1. Log in to the application
2. Navigate to Settings or use the sidebar
3. Choose one of these methods:
   - **Upload M3U File**: Click "Upload M3U" and select your file
   - **Add URL**: Click "Add Playlist URL" and enter the M3U URL
   - **With Authentication**: Include username and password if required

### Supported Playlist Formats

- M3U files (`.m3u`)
- M3U8 files (`.m3u8`)
- HTTP/HTTPS URLs pointing to M3U playlists
- Authentication-protected playlists

### Example M3U Format

```m3u
#EXTM3U
#EXTINF:-1 tvg-id="bbc1" tvg-name="BBC One" tvg-logo="http://example.com/logo.png" group-title="News",BBC One
http://example.com/stream/bbc1
#EXTINF:-1 tvg-id="cnn" tvg-name="CNN" tvg-logo="http://example.com/cnn.png" group-title="News",CNN
http://example.com/stream/cnn
```

## Managing the Application

### View Logs
```bash
# All logs
docker-compose logs -f

# Specific service logs
docker-compose logs -f streamflow
```

### Stop the Application
```bash
./stop.sh
# or
docker-compose down
```

### Restart the Application
```bash
docker-compose restart
```

### Update the Application
```bash
# Pull latest changes
git pull

# Rebuild and restart
docker-compose down
docker-compose build
docker-compose up -d
```

## Backup and Restore

### Backup Data

```bash
# Backup database and uploaded files
docker run --rm \
  -v streamflow-data:/data \
  -v $(pwd)/backup:/backup \
  alpine tar czf /backup/streamflow-backup-$(date +%Y%m%d).tar.gz /data
```

### Restore Data

```bash
# Restore from backup
docker run --rm \
  -v streamflow-data:/data \
  -v $(pwd)/backup:/backup \
  alpine tar xzf /backup/streamflow-backup-YYYYMMDD.tar.gz -C /
```

## Troubleshooting

### Port Already in Use

If port 12345 is already in use:

1. Edit `docker-compose.yml`
2. Change the port mapping:
   ```yaml
   ports:
     - "8080:12345"  # Change 8080 to any available port
   ```
3. Restart the application

### Container Won't Start

Check logs:
```bash
docker-compose logs
```

Common issues:
- **Permissions**: Ensure Docker has proper permissions
- **Port conflicts**: Check if port 12345 is already in use
- **Disk space**: Ensure sufficient disk space

### Cannot Connect to Application

1. Verify container is running: `docker-compose ps`
2. Check firewall settings
3. Verify port 12345 is open:
   ```bash
   sudo ufw allow 12345/tcp  # Ubuntu/Debian
   ```

### Database Issues

Reset database (WARNING: This deletes all data):
```bash
docker-compose down -v
docker-compose up -d
```

## Security Recommendations

1. **Change Default Secrets**: Update JWT_SECRET and SESSION_SECRET in `.env`
2. **Use HTTPS**: Deploy behind a reverse proxy (nginx, Caddy) with SSL
3. **Firewall**: Restrict access to port 12345 to trusted IPs
4. **Regular Updates**: Keep Docker and the application updated
5. **Strong Passwords**: Use strong passwords for user accounts
6. **Backup Regularly**: Implement regular backup schedule

## Performance Tuning

### Increase Recording Storage

Edit `.env`:
```bash
MAX_RECORDING_SIZE=50GB
```

### Adjust EPG Update Interval

Edit `.env`:
```bash
EPG_UPDATE_INTERVAL=7200000  # 2 hours in milliseconds
```

### Docker Resource Limits

Edit `docker-compose.yml`:
```yaml
services:
  streamflow:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          memory: 512M
```

## Support

For issues and questions:
1. Check the logs: `docker-compose logs -f`
2. Review this documentation
3. Check GitHub issues (if applicable)
4. Contact the development team

## Next Steps

After successful installation:
1. ✅ Add your IPTV playlists
2. ✅ Configure EPG sources
3. ✅ Set up user profiles
4. ✅ Customize theme and language preferences
5. ✅ Explore features like recording, favorites, and groups

Enjoy streaming with StreamFlow! 🎬