metaserver-web-python/INSTALL.md

# Installation Guide - Meta File Server Query Application

This guide will help you install and run the Meta File Server Query application on different systems.

## Prerequisites

### Required Software
- **Python 3.7 or higher** - [Download Python](https://www.python.org/downloads/)
- **Git** (optional) - For cloning the repository
- **Modern web browser** - Chrome, Firefox, Safari, or Edge

### System Requirements
- **RAM**: 512MB minimum, 1GB recommended
- **Storage**: 100MB free space
- **Network**: Internet access to reach metafile.oliver.solutions

## Installation Methods

### Method 1: Quick Install (Recommended)

1. **Download/Copy the application folder** to your desired location
2. **Open Terminal/Command Prompt** and navigate to the folder:
   ```bash
   cd /path/to/META-FILE-SERVER-QUERY
   ```
3. **Run the startup script**:
   ```bash
   ./start.sh
   ```
   This will automatically:
   - Create the virtual environment
   - Install all dependencies
   - Start the application

### Method 2: Manual Installation

1. **Navigate to the application directory**:
   ```bash
   cd /path/to/META-FILE-SERVER-QUERY
   ```

2. **Create Python virtual environment**:
   ```bash
   python3 -m venv meta-server-venv
   ```

3. **Activate the virtual environment**:
   
   **On macOS/Linux**:
   ```bash
   source meta-server-venv/bin/activate
   ```
   
   **On Windows**:
   ```cmd
   meta-server-venv\Scripts\activate
   ```

4. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

5. **Run the application**:
   ```bash
   python run.py
   ```

## Platform-Specific Instructions

### macOS

1. **Install Python 3** (if not already installed):
   ```bash
   # Using Homebrew (recommended)
   brew install python3
   
   # Or download from python.org
   ```

2. **Make startup script executable**:
   ```bash
   chmod +x start.sh
   ```

3. **Run the application**:
   ```bash
   ./start.sh
   ```

### Windows

1. **Install Python 3** from [python.org](https://www.python.org/downloads/windows/)
   - ✅ Check "Add Python to PATH" during installation

2. **Open Command Prompt or PowerShell**:
   ```cmd
   cd C:\path\to\META-FILE-SERVER-QUERY
   ```

3. **Create virtual environment**:
   ```cmd
   python -m venv meta-server-venv
   ```

4. **Activate virtual environment**:
   ```cmd
   meta-server-venv\Scripts\activate
   ```

5. **Install dependencies**:
   ```cmd
   pip install -r requirements.txt
   ```

6. **Run application**:
   ```cmd
   python run.py
   ```

### Linux (Ubuntu/Debian)

1. **Install Python 3 and pip**:
   ```bash
   sudo apt update
   sudo apt install python3 python3-pip python3-venv
   ```

2. **Navigate and setup**:
   ```bash
   cd /path/to/META-FILE-SERVER-QUERY
   chmod +x start.sh
   ./start.sh
   ```

### Linux (CentOS/RHEL/Fedora)

1. **Install Python 3**:
   ```bash
   # CentOS/RHEL
   sudo yum install python3 python3-pip
   
   # Fedora
   sudo dnf install python3 python3-pip
   ```

2. **Run setup**:
   ```bash
   cd /path/to/META-FILE-SERVER-QUERY
   chmod +x start.sh
   ./start.sh
   ```

## Docker Installation (Optional)

If you prefer using Docker:

1. **Create Dockerfile**:
   ```dockerfile
   FROM python:3.9-slim
   
   WORKDIR /app
   COPY . /app
   
   RUN pip install -r requirements.txt
   
   EXPOSE 5000
   
   CMD ["python", "run.py"]
   ```

2. **Build and run**:
   ```bash
   docker build -t meta-file-server .
   docker run -p 5000:5000 meta-file-server
   ```

## Verification

After installation, verify the application is working:

1. **Check the startup output** - you should see:
   ```
   Meta File Server Query Application
   ====================================
   Starting server on http://localhost:5000
   Press Ctrl+C to stop the server
   ```

2. **Open your web browser** and go to: `http://localhost:5000`

3. **Test with a job number** (e.g., `6046034`)

4. **Check the API directly**: `http://localhost:5000/api/health`

## Troubleshooting Installation

### Python Not Found
**Error**: `python3: command not found`

**Solution**:
- Install Python 3 from python.org
- On Windows, try `python` instead of `python3`
- Make sure Python is added to your system PATH

### Permission Denied
**Error**: `Permission denied: ./start.sh`

**Solution**:
```bash
chmod +x start.sh
```

### Module Not Found
**Error**: `ModuleNotFoundError: No module named 'flask'`

**Solution**:
- Make sure you activated the virtual environment
- Run: `pip install -r requirements.txt`

### Port Already in Use
**Error**: `OSError: [Errno 48] Address already in use`

**Solution**:
- Stop any other applications using port 5000
- Or modify `run.py` to use a different port:
  ```python
  app.run(debug=True, host='0.0.0.0', port=5001)  # Change port
  ```

### SSL Certificate Warnings
**Warning**: `InsecureRequestWarning: Unverified HTTPS request`

**This is expected** - The application disables SSL verification for the metafile server due to certificate issues. This is safe for this specific use case.

## Uninstallation

To remove the application:

1. **Stop the application** (Ctrl+C)
2. **Delete the entire folder**:
   ```bash
   rm -rf /path/to/META-FILE-SERVER-QUERY
   ```

The application is self-contained in its directory and doesn't install anything system-wide.

## Moving to Another Machine

To transfer the application to another computer:

1. **Copy the entire META-FILE-SERVER-QUERY folder**
2. **Install Python 3** on the target machine
3. **Run the installation** using Method 1 or 2 above

The `meta-server-venv` folder can be deleted before copying - it will be recreated during installation.

## Production Deployment

For production use on a server:

1. **Install using Method 2** (manual installation)
2. **Install a production WSGI server**:
   ```bash
   pip install gunicorn
   ```
3. **Run with Gunicorn**:
   ```bash
   gunicorn -w 4 -b 0.0.0.0:5000 app:app
   ```
4. **Set up reverse proxy** (nginx/Apache) and SSL certificate
5. **Configure firewall** to allow traffic on your chosen port

## Support

If you encounter issues during installation:

1. Check the **Troubleshooting** section above
2. Verify your Python version: `python3 --version`
3. Check that all required files are present in the application directory
4. Ensure you have internet connectivity to download dependencies

---

**Need help?** The application includes comprehensive error messages and logging to help diagnose issues.