streamflow/scripts/README.md

# StreamFlow Scripts

Utility scripts for managing the StreamFlow IPTV application.

## Available Scripts

### test-vpn.sh
Tests VPN connection and checks for IP/DNS leaks.

**Usage:**
```bash
# From inside the container
docker exec -it streamflow bash
./scripts/test-vpn.sh

# Or directly from host
docker exec -it streamflow /app/scripts/test-vpn.sh
```

**What it checks:**
- VPN interface (tun0) status
- Routing table configuration
- DNS server configuration
- Public IP address
- IP geolocation information
- OpenVPN process status
- Firewall rules

**Example output:**
```
=========================================
   VPN Connection Test
=========================================

1. Checking VPN Interface (tun0)...
✓ VPN interface (tun0) is UP
  IP: 10.2.0.2/32

2. Checking Routing Table...
  default via 10.2.0.1 dev tun0
✓ Traffic is routed through VPN

3. Checking DNS Configuration...
  DNS Servers: 10.2.0.1 10.2.0.2
✓ Using VPN DNS servers

4. Checking Public IP Address...
  Public IP: 185.159.x.x
  Location: Amsterdam, NL
  ISP: AS62371 ProtonVPN AG
✓ IP appears to be from VPN provider

5. Checking OpenVPN Process...
✓ OpenVPN process is running
  PID: 1234

6. Checking Firewall Rules...
✓ VPN firewall rules are active (3 rules)

=========================================
   Summary
=========================================
✓ VPN appears to be working correctly!
```

---

### start.sh
Starts the StreamFlow application using Docker Compose.

**Usage:**
```bash
./scripts/start.sh
```

**What it does:**
- Checks if Docker is running
- Builds Docker images if needed
- Starts all containers in detached mode
- Shows container status
- Displays access URL

**Options:**
```bash
./scripts/start.sh --build  # Force rebuild images
./scripts/start.sh --logs   # Show logs after starting
```

---

### stop.sh
Stops the StreamFlow application and removes containers.

**Usage:**
```bash
./scripts/stop.sh
```

**What it does:**
- Stops all running containers
- Removes containers
- Preserves volumes (data persistence)
- Shows final status

**Options:**
```bash
./scripts/stop.sh --volumes  # Also remove volumes (WARNING: deletes data)
```

---

## Creating New Scripts

When adding new scripts to this directory:

1. **Make it executable:**
   ```bash
   chmod +x scripts/your-script.sh
   ```

2. **Use proper shebang:**
   ```bash
   #!/bin/bash
   ```

3. **Add error handling:**
   ```bash
   set -e  # Exit on error
   ```

4. **Document the script:**
   - Add comments explaining what it does
   - Update this README with usage instructions

5. **Test thoroughly:**
   - Test on a clean environment
   - Handle edge cases
   - Provide helpful error messages

---

## Common Script Patterns

### Docker Commands
```bash
# Start in development mode with logs
docker-compose up

# Start in production (detached)
docker-compose up -d

# View logs
docker-compose logs -f

# Rebuild and start
docker-compose up -d --build

# Stop containers
docker-compose down

# Stop and remove volumes
docker-compose down -v
```

### Development Scripts
```bash
# Install dependencies
cd backend && npm install
cd frontend && npm install

# Run in development mode
cd backend && npm run dev
cd frontend && npm run dev

# Run tests
npm test

# Lint code
npm run lint
```

### Maintenance Scripts
```bash
# Clean Docker system
docker system prune -a

# View container logs
docker logs streamflow-app

# Execute command in container
docker exec -it streamflow-app sh

# Database backup
docker exec streamflow-app sqlite3 /app/data/streamflow.db .dump > backup.sql
```

---

## Script Guidelines

### Best Practices

1. **Always use absolute paths or relative from project root:**
   ```bash
   cd "$(dirname "$0")/.." || exit
   ```

2. **Check prerequisites:**
   ```bash
   if ! command -v docker &> /dev/null; then
       echo "Docker is not installed"
       exit 1
   fi
   ```

3. **Provide feedback:**
   ```bash
   echo "Starting application..."
   # command here
   echo "✓ Application started successfully"
   ```

4. **Handle errors gracefully:**
   ```bash
   if ! docker-compose up -d; then
       echo "Failed to start application"
       exit 1
   fi
   ```

5. **Use colors for output (optional):**
   ```bash
   RED='\033[0;31m'
   GREEN='\033[0;32m'
   NC='\033[0m' # No Color
   echo -e "${GREEN}Success!${NC}"
   ```

---

## Future Scripts (Ideas)

Potential scripts that could be added:

- `backup.sh` - Backup database and uploads
- `restore.sh` - Restore from backup
- `update.sh` - Pull latest changes and rebuild
- `logs.sh` - View application logs with options
- `clean.sh` - Clean up unused Docker resources
- `test.sh` - Run test suite
- `deploy.sh` - Deploy to production server
- `health-check.sh` - Check application health
- `db-migrate.sh` - Run database migrations
- `generate-icons.sh` - Generate PWA icons from source

---

## Debugging Scripts

If a script fails:

1. **Check permissions:**
   ```bash
   ls -la scripts/
   chmod +x scripts/script-name.sh
   ```

2. **Run with verbose output:**
   ```bash
   bash -x scripts/script-name.sh
   ```

3. **Check Docker status:**
   ```bash
   docker ps
   docker-compose ps
   ```

4. **View logs:**
   ```bash
   docker-compose logs
   ```

---

## Platform Compatibility

All scripts should be compatible with:
- Linux (Ubuntu, Debian, Fedora, Arch)
- macOS
- Windows (via Git Bash or WSL)

For Windows native support, consider creating `.bat` or `.ps1` versions.

---

**Last Updated:** December 10, 2025