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

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

# Install build tools
pip install pyinstaller waitress
```

## Building the Executable

### Windows

Run the build script:

```cmd
build_exe.bat
```

Or manually:

```cmd
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:

```bash
chmod +x build_exe.sh
./build_exe.sh
```

Or manually:

```bash
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

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

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

```ini
[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:

```bash
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:
   ```bash
   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