175 lines
4.0 KiB
Markdown
175 lines
4.0 KiB
Markdown
# Building GlowPath Backend with PyInstaller
|
|
|
|
This directory contains everything needed to bundle the GlowPath backend into a standalone executable using PyInstaller.
|
|
|
|
## Quick Start
|
|
|
|
The easiest way to build the application is using the provided build script:
|
|
|
|
```bash
|
|
# Install build dependencies and create the executable
|
|
python build.py
|
|
```
|
|
|
|
Or using make:
|
|
|
|
```bash
|
|
make build
|
|
```
|
|
|
|
## Build Requirements
|
|
|
|
- Python 3.12+
|
|
- PyInstaller 6.0+
|
|
- All dependencies from `pyproject.toml`
|
|
|
|
## Build Methods
|
|
|
|
### Method 1: Using the Build Script (Recommended)
|
|
|
|
The `build.py` script handles everything automatically:
|
|
|
|
```bash
|
|
# Standard build
|
|
python build.py
|
|
|
|
# Debug build (includes debug symbols and verbose output)
|
|
python build.py --debug
|
|
|
|
# Skip dependency installation
|
|
python build.py --no-deps
|
|
|
|
# Skip cleaning previous builds
|
|
python build.py --no-clean
|
|
```
|
|
|
|
### Method 2: Using Make
|
|
|
|
```bash
|
|
# Standard build
|
|
make build
|
|
|
|
# Debug build
|
|
make build-debug
|
|
|
|
# Quick build (no cleaning)
|
|
make quick-build
|
|
|
|
# Just clean
|
|
make clean
|
|
```
|
|
|
|
### Method 3: Manual PyInstaller
|
|
|
|
If you prefer to run PyInstaller directly:
|
|
|
|
```bash
|
|
# Install dependencies first
|
|
pip install pyinstaller pyinstaller-hooks-contrib
|
|
|
|
# Run PyInstaller
|
|
pyinstaller --clean --noconfirm glowpath-backend.spec
|
|
```
|
|
|
|
## Output
|
|
|
|
After a successful build, you'll find:
|
|
|
|
- `dist/glowpath-backend` - The standalone executable
|
|
- `dist/glowpath-backend-bundle/` - A complete distribution package with:
|
|
- The executable
|
|
- Startup scripts (`start.sh` or `start.bat`)
|
|
- README.txt with usage instructions
|
|
|
|
## Configuration
|
|
|
|
### PyInstaller Spec File
|
|
|
|
The `glowpath-backend.spec` file contains the PyInstaller configuration. It's configured to:
|
|
|
|
- Include all open-webui dependencies and data files
|
|
- Handle complex packages like bcrypt, cryptography, etc.
|
|
- Include SSL certificates
|
|
- Exclude unnecessary packages (tkinter, matplotlib, etc.)
|
|
- Create a single-file executable
|
|
|
|
### Custom Hooks
|
|
|
|
The `hooks/` directory contains PyInstaller hooks for better package detection:
|
|
|
|
- `hook-open_webui.py` - Ensures all open-webui files are included
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Missing modules**: If you get import errors, add the missing module to `hiddenimports` in the spec file.
|
|
|
|
2. **Missing data files**: If templates or static files are missing, they may need to be added to the `datas` list.
|
|
|
|
3. **SSL certificate errors**: The spec file includes SSL certificates, but you may need to adjust the path based on your system.
|
|
|
|
4. **Large executable size**: The executable includes all dependencies. You can reduce size by:
|
|
- Adding more packages to the `excludes` list
|
|
- Using `--onedir` instead of `--onefile` (modify the spec file)
|
|
|
|
### Debug Mode
|
|
|
|
Build in debug mode to get more information about what's being included:
|
|
|
|
```bash
|
|
python build.py --debug
|
|
```
|
|
|
|
This will:
|
|
- Enable PyInstaller debug output
|
|
- Include debug symbols
|
|
- Show detailed import information
|
|
|
|
### Testing the Build
|
|
|
|
After building, test the executable:
|
|
|
|
```bash
|
|
# Run the executable directly
|
|
./dist/glowpath-backend
|
|
|
|
# Or use the bundle
|
|
cd dist/glowpath-backend-bundle
|
|
./start.sh
|
|
```
|
|
|
|
## Customization
|
|
|
|
### Adding Dependencies
|
|
|
|
To include additional Python packages:
|
|
|
|
1. Add them to the `additional_packages` list in `glowpath-backend.spec`
|
|
2. If they have hidden imports, add them to the `hiddenimports` list
|
|
|
|
### Changing the Executable Name
|
|
|
|
Modify the `name` parameter in the `EXE` section of the spec file.
|
|
|
|
### Creating a GUI Application
|
|
|
|
Change `console=True` to `console=False` in the `EXE` section for a GUI app (no console window).
|
|
|
|
## Performance Notes
|
|
|
|
- First build will be slower as PyInstaller analyzes all dependencies
|
|
- Subsequent builds with `--no-clean` will be faster
|
|
- The executable may take a moment to start as it unpacks dependencies
|
|
|
|
## Distribution
|
|
|
|
The bundled application is self-contained and can be distributed to machines without Python installed. The bundle includes:
|
|
|
|
- All Python dependencies
|
|
- SSL certificates
|
|
- Static files and templates
|
|
- Configuration files
|
|
|
|
Simply copy the entire `dist/glowpath-backend-bundle/` directory to the target machine.
|