Installation Guide

This guide will walk you through installing WifiX on your system.

System Requirements

Minimum Requirements

  • OS: Windows 10+, macOS 10.15+, or Linux (Ubuntu 20.04+, Fedora 34+)

  • Python: 3.8 or higher

  • Node.js: 16.0 or higher

  • RAM: 512 MB available

  • Disk Space: 200 MB for installation

  • Network: Active LAN connection

Recommended Requirements

  • Python: 3.11+

  • Node.js: 18.0+

  • RAM: 1 GB available

  • Disk Space: 500 MB for installation and file storage

Prerequisites

Before installing WifiX, ensure you have the following installed:

Python Installation

Windows:

  1. Download Python from python.org

  2. Run the installer and check “Add Python to PATH”

  3. Verify installation:

python --version
# Should output: Python 3.11.x or higher

macOS:

# Using Homebrew
brew install python@3.11

# Verify
python3 --version

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install python3.11 python3.11-venv python3-pip

# Verify
python3 --version

Node.js Installation

Windows:

  1. Download Node.js from nodejs.org

  2. Run the installer (choose LTS version)

  3. Verify:

node --version
npm --version

macOS:

# Using Homebrew
brew install node

# Verify
node --version
npm --version

Linux:

# Using NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify
node --version
npm --version

Git Installation

Windows:

Download and install from git-scm.com

macOS:

brew install git

Linux:

sudo apt install git

Installation Steps

Step 1: Clone the Repository

git clone https://github.com/mehmoodulhaq570/WifiX.git
cd WifiX

Step 2: Backend Setup

Navigate to the backend directory and install dependencies:

cd backend
pip install -r requirements.txt

Alternative: Using Virtual Environment (Recommended)

# Windows
cd backend
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

# macOS/Linux
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Step 3: Frontend Setup

Navigate to the frontend directory and install dependencies:

cd ../frontend
npm install

Step 4: Configuration

Create a .env file in the backend directory:

# backend/.env
FLASK_ENV=development
SECRET_KEY=your-secret-key-here
ACCESS_PIN=1234
CORS_ORIGINS=http://localhost:5173,http://localhost:5174
MAX_CONTENT_LENGTH=104857600

See Configuration Guide for detailed configuration options.

Step 5: Verify Installation

Test Backend:

cd backend
python app.py

You should see:

🚀 WifiX Server Starting...
📡 Network: 192.168.1.100:5000
🔗 Room Code: ABC123
✅ Server running at http://192.168.1.100:5000

Test Frontend (in a new terminal):

cd frontend
npm run dev

You should see:

VITE v5.0.0  ready in 500 ms
➜  Local:   http://localhost:5173/
➜  Network: http://192.168.1.100:5173/

Step 6: Access WifiX

Open your browser and navigate to:

  • Local: http://localhost:5173

  • Network: http://192.168.1.100:5173

You should see the WifiX interface! 🎉

Docker Installation (Alternative)

If you prefer using Docker:

# Clone repository
git clone https://github.com/mehmoodulhaq570/WifiX.git
cd WifiX

# Build and run with Docker Compose
docker-compose up -d

# Access at http://localhost:5173

Platform-Specific Notes

Windows

Firewall Configuration:

Windows Firewall may block network access. Allow Python and Node.js:

  1. Open Windows Defender Firewall

  2. Click “Allow an app through firewall”

  3. Add Python (python.exe) and Node.js (node.exe)

  4. Check both “Private” and “Public” networks

Running on Startup:

Create a batch script start-wifix.bat:

@echo off
cd /d "C:\path\to\WifiX\backend"
start cmd /k "venv\Scripts\activate && python app.py"
cd /d "C:\path\to\WifiX\frontend"
start cmd /k "npm run dev"

macOS

Bonjour Service:

macOS includes Bonjour (mDNS) by default, so automatic discovery works out of the box.

Running on Startup:

Create a Launch Agent at ~/Library/LaunchAgents/com.wifix.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.wifix</string>
    <key>ProgramArguments</key>
    <array>
        <string>/path/to/WifiX/start.sh</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

Linux

Avahi (mDNS):

Install Avahi for automatic discovery:

# Ubuntu/Debian
sudo apt install avahi-daemon avahi-utils

# Fedora
sudo dnf install avahi avahi-tools

# Start service
sudo systemctl start avahi-daemon
sudo systemctl enable avahi-daemon

Systemd Service:

Create /etc/systemd/system/wifix.service:

[Unit]
Description=WifiX File Sharing Server
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/WifiX/backend
ExecStart=/path/to/WifiX/backend/venv/bin/python app.py
Restart=always

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable wifix
sudo systemctl start wifix

Troubleshooting Installation

Port Already in Use

If port 5000 or 5173 is already in use:

Backend (change port):

# Set PORT environment variable
export PORT=5001  # macOS/Linux
set PORT=5001     # Windows CMD
$env:PORT=5001    # Windows PowerShell

Frontend (change port):

Edit frontend/vite.config.js:

export default {
  server: {
    port: 5174  // Change to desired port
  }
}

Python Module Not Found

If you get ModuleNotFoundError:

# Ensure you're in virtual environment
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

# Reinstall dependencies
pip install --upgrade -r requirements.txt

npm Install Fails

If npm install fails:

# Clear npm cache
npm cache clean --force

# Delete node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Reinstall
npm install

Permission Denied

On macOS/Linux, if you get permission errors:

# Don't use sudo with pip, use virtual environment instead
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Network Not Detected

If mDNS/Bonjour isn’t working:

  1. Check firewall settings - Allow UDP port 5353

  2. Verify mDNS service:

    • Windows: Bonjour Service should be running

    • macOS: Built-in, should work automatically

    • Linux: Check sudo systemctl status avahi-daemon

  3. Use manual IP: If discovery fails, connect via IP address directly

Verification Checklist

After installation, verify everything works:

# 1. Backend is running
curl http://localhost:5000/api/info
# Should return JSON with server info

# 2. Frontend is accessible
# Open browser to http://localhost:5173
# You should see WifiX interface

# 3. WebSocket connection
# In browser console, check for "Connected" message

# 4. File upload/download works
# Try uploading a test file

✅ Installation Complete!

Next Steps

Need Help?