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:

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

./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:

./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:

./scripts/stop.sh

What it does:

• Stops all running containers
• Removes containers
• Preserves volumes (data persistence)
• Shows final status

Options:

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

---

Creating New Scripts

When adding new scripts to this directory:

1. Make it executable:

   chmod +x scripts/your-script.sh
   

2. Use proper shebang:

   #!/bin/bash
   

3. Add error handling:

   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

# 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

# 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

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

   cd "$(dirname "$0")/.." || exit
   

2. Check prerequisites:

   if ! command -v docker &> /dev/null; then
       echo "Docker is not installed"
       exit 1
   fi
   

3. Provide feedback:

   echo "Starting application..."
   # command here
   echo "✓ Application started successfully"
   

4. Handle errors gracefully:

   if ! docker-compose up -d; then
       echo "Failed to start application"
       exit 1
   fi
   

5. Use colors for output (optional):

   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:

   ls -la scripts/
   chmod +x scripts/script-name.sh
   

2. Run with verbose output:

   bash -x scripts/script-name.sh
   

3. Check Docker status:

   docker ps
   docker-compose ps
   

4. View logs:

   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