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

   cd /path/to/META-FILE-SERVER-QUERY
   

3. Run the startup script:

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

   cd /path/to/META-FILE-SERVER-QUERY
   

2. Create Python virtual environment:

   python3 -m venv meta-server-venv
   

3. Activate the virtual environment:

   On macOS/Linux:

   source meta-server-venv/bin/activate
   

   On Windows:

   meta-server-venv\Scripts\activate
   

4. Install dependencies:

   pip install -r requirements.txt
   

5. Run the application:

   python run.py
   

Platform-Specific Instructions

macOS

1. Install Python 3 (if not already installed):

   # Using Homebrew (recommended)
   brew install python3
   
   # Or download from python.org
   

2. Make startup script executable:

   chmod +x start.sh
   

3. Run the application:

   ./start.sh
   

Windows

1. Install Python 3 from python.org

   • ✅ Check "Add Python to PATH" during installation

2. Open Command Prompt or PowerShell:

   cd C:\path\to\META-FILE-SERVER-QUERY
   

3. Create virtual environment:

   python -m venv meta-server-venv
   

4. Activate virtual environment:

   meta-server-venv\Scripts\activate
   

5. Install dependencies:

   pip install -r requirements.txt
   

6. Run application:

   python run.py
   

Linux (Ubuntu/Debian)

1. Install Python 3 and pip:

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

2. Navigate and setup:

   cd /path/to/META-FILE-SERVER-QUERY
   chmod +x start.sh
   ./start.sh
   

Linux (CentOS/RHEL/Fedora)

1. Install Python 3:

   # CentOS/RHEL
   sudo yum install python3 python3-pip
   
   # Fedora
   sudo dnf install python3 python3-pip
   

2. Run setup:

   cd /path/to/META-FILE-SERVER-QUERY
   chmod +x start.sh
   ./start.sh
   

Docker Installation (Optional)

If you prefer using Docker:

1. Create 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:

   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:

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:

  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:

   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:

   pip install gunicorn
   

3. Run with Gunicorn:

   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.