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