203 lines
4.8 KiB
Markdown
203 lines
4.8 KiB
Markdown
# 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 |