UAV-CO2/EXE_BUILD_README.md

GasFlux Web API - Executable Build Guide

This guide explains how to build and deploy the GasFlux Web API as a standalone executable using Waitress WSGI server.

Prerequisites

Before building the executable, ensure you have all dependencies installed:

# Install all required packages
pip install -r requirements.txt

# Install build tools
pip install pyinstaller waitress

Building the Executable

Windows

Run the build script:

build_exe.bat

Or manually:

pyinstaller --onefile ^
    --name GasFluxAPI ^
    --hidden-import waitress ^
    --hidden-import flask ^
    --hidden-import werkzeug ^
    --hidden-import yaml ^
    --hidden-import pandas ^
    --hidden-import numpy ^
    --hidden-import flask_cors ^
    --add-data "src\gasflux\gasflux_config.yaml;src\gasflux" ^
    --add-data "API_DOCUMENTATION.md;." ^
    --exclude-module matplotlib ^
    --exclude-module tkinter ^
    server_waitress.py

Linux/macOS

Make the build script executable and run it:

chmod +x build_exe.sh
./build_exe.sh

Or manually:

pyinstaller --onefile \
    --name GasFluxAPI \
    --hidden-import waitress \
    --hidden-import flask \
    --hidden-import werkzeug \
    --hidden-import yaml \
    --hidden-import pandas \
    --hidden-import numpy \
    --hidden-import flask_cors \
    --add-data "src/gasflux/gasflux_config.yaml:src/gasflux" \
    --add-data "API_DOCUMENTATION.md:." \
    --exclude-module matplotlib \
    --exclude-module tkinter \
    server_waitress.py

Running the Executable

After successful build, you'll find GasFluxAPI.exe (Windows) or GasFluxAPI (Linux/macOS) in the dist/ directory.

Basic Usage

# Windows
GasFluxAPI.exe

# Linux/macOS
./GasFluxAPI

The server will start on http://localhost:5000 by default.

Command Line Options

Waitress supports various command-line options. You can create a wrapper script to customize:

# Custom port and host
waitress-serve --listen=0.0.0.0:8080 server_waitress:app

# Production settings
waitress-serve --threads=16 --connection-limit=200 server_waitress:app

Deployment Considerations

Directory Structure

When deploying the executable, ensure these directories exist and are writable:

your-deployment-directory/
├── GasFluxAPI(.exe)          # The executable
├── web_api_data/             # Data directory (auto-created)
│   ├── uploads/             # Uploaded files
│   └── outputs/             # Processing results
├── logs/                    # Log files (auto-created)
└── gasflux_config.yaml      # Configuration (optional)

Firewall Configuration

Make sure the server port (default 5000) is open in your firewall.

Production Deployment

For production use:

1. Use a reverse proxy: Place Nginx or Apache in front of the executable
2. SSL/TLS: Configure HTTPS
3. Process management: Use systemd, supervisor, or similar
4. Logging: Configure log rotation

Example systemd Service (Linux)

Create /etc/systemd/system/gasflux-api.service:

[Unit]
Description=GasFlux Web API
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/deployment
ExecStart=/path/to/deployment/GasFluxAPI
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Then:

sudo systemctl daemon-reload
sudo systemctl enable gasflux-api
sudo systemctl start gasflux-api

Troubleshooting

Common Issues

1. "Permission denied": Ensure the executable has execute permissions and data directories are writable

2. "Port already in use": Change the port or stop other services using port 5000

3. "Module not found": Some dependencies might be missing. Try:

   pip install --upgrade pyinstaller
   pip install -r requirements.txt
   

4. Large executable size: The --exclude-module options help reduce size, but some scientific packages are large

Performance Tuning

• Threads: Increase --threads for more concurrent requests
• Connection limit: Adjust --connection-limit based on server capacity
• Memory: Monitor memory usage, especially with large data processing

Logs

Logs are written to:

• Console output (when running interactively)
• logs/gasflux_api.log file

Check logs for startup errors and runtime issues.

API Documentation

Once running, access the API documentation at:

• Web interface: http://your-server:5000
• API docs: See API_DOCUMENTATION.md
• Statistics: GET /stats - Real-time API statistics and monitoring
• Health check: GET /health - System health with performance metrics

Security Notes

• Default configuration listens on all interfaces (0.0.0.0)
• No authentication is configured by default
• Consider adding authentication and SSL for production use
• Regularly update dependencies for security patches