glowpath/backend/BUILD.md

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:

# Install build dependencies and create the executable
python build.py

Or using make:

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:

# 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

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

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

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:

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