openwebui-bootstrap 0.3.4

Open WebUI Bootstrap - A tool to bootstrap Open WebUI deployments by writing configuration directly to the database

Open WebUI Bootstrap

A Python library and command-line tool to bootstrap Open WebUI deployments by writing configuration directly to the Open WebUI database.

Features

• Database Configuration: Write users, groups, models, and connections directly to the Open WebUI SQLite database
• Upsert Functionality: Update existing records or add new ones
• Reset Capability: Clear managed tables before applying new configuration
• Dry Run Mode: Test configuration without making database changes
• Comprehensive Logging: Color-formatted logging with configurable verbosity
• Extensible Design: Abstract database interface for future database support

Installation

uv add openwebui-bootstrap

Usage

Command Line Interface

Basic Usage

openwebui-bootstrap --config config.yaml

Reset Database Before Applying Configuration

openwebui-bootstrap --config config.yaml --reset

Dry Run (Test Without Changes)

openwebui-bootstrap --config config.yaml --dry-run

Set Log Level

openwebui-bootstrap --config config.yaml --log-level debug

Python Library Usage

The package can also be used as a Python library in third-party applications. The public API provides the same functionality as the CLI tool.

Basic Bootstrap

from openwebui_bootstrap import bootstrap_openwebui

# Bootstrap Open WebUI with configuration
bootstrap_openwebui(
    config_path="config.yaml",
    database_path="/path/to/webui.db",  # Optional, defaults to config
    reset=True,                         # Reset database before applying
    dry_run=False,                      # Make actual changes
    log_level="info"                    # Log level
)

Load and Apply Configuration Separately

from openwebui_bootstrap import load_config, apply_config

# Load configuration
config = load_config("config.yaml")

# Apply configuration to database
apply_config(
    config=config,
    database_path="/path/to/webui.db",
    dry_run=False
)

Reset Database Only

from openwebui_bootstrap import reset_database

# Reset database (clear managed tables)
reset_database(
    database_path="/path/to/webui.db",
    dry_run=False
)

Advanced Usage with ConfigManager

from openwebui_bootstrap import ConfigManager, SQLiteDatabase

# Create database interface
database = SQLiteDatabase("/path/to/webui.db")

# Create configuration manager
config_manager = ConfigManager(database)
config_manager.set_dry_run(False)

# Load and apply configuration
config = config_manager.load_config("config.yaml")
config_manager.apply_config(config)

Public API Reference

Functions

• bootstrap_openwebui(config_path, database_path=None, reset=False, dry_run=False, log_level="info")

  • Complete bootstrap operation (load config + apply config + optional reset)
  • Equivalent to CLI command with all options

• load_config(config_path)

  • Load and validate configuration from YAML file
  • Returns OpenWebUIConfig object
  • Raises ConfigurationFileError or ConfigurationValidationError

• apply_config(config, database_path, dry_run=False)

  • Apply configuration to database
  • Raises DatabaseError or DryRunError

• reset_database(database_path, dry_run=False)

  • Clear all managed tables in database
  • Raises DatabaseError or DryRunError

Classes

• ConfigManager(database) - Main configuration manager
• SQLiteDatabase(database_path) - SQLite database interface
• OpenWebUIConfig - Main configuration model
• UserConfig, GroupConfig, ModelConfig, etc. - Configuration sub-models

Exceptions

• OpenWebUIBootstrapError - Base exception
• ConfigurationError - Configuration-related errors
• DatabaseError - Database-related errors
• DryRunError - Dry run mode errors

Public API Design Philosophy

The public API is designed to:

1. Mirror CLI functionality - All CLI operations are available as Python functions
2. Provide flexibility - Functions can be used individually or combined
3. Maintain simplicity - Simple, intuitive function signatures
4. Ensure type safety - Full type hints for IDE support
5. Offer comprehensive error handling - Clear exception hierarchy

The API reuses existing components (ConfigManager, SQLiteDatabase) to ensure consistency and reduce code duplication.

Configuration File

Create a YAML configuration file (see example-config.yaml for reference):

database:
  type: sqlite
  database_location: /path/to/webui.db

users:
  - name: Admin User
    email: [e-mail]
    role: Admin

groups:
  - name: developers
    description: Development team
    permissions:
      - import_models
      - export_models
    members:
      - [e-mail]

connections:
  type: openai
  url: https://api.example.com/v1
  bearer: your-api-key
  model_ids:
    - gpt-4
    - gpt-3.5-turbo

models:
  prompt_path: /path/to/prompts
  icon_path: /path/to/icons

Project Structure

openwebui_bootstrap/
├── cli.py                  # Command-line interface
├── config_manager.py       # Configuration management
├── database/
│   ├── base.py             # Abstract database interface
│   └── sqlite.py           # SQLite implementation
├── exceptions.py           # Custom exceptions
├── logging_config.py       # Logging configuration
├── models.py               # Data models
└── __init__.py

Development

Setup

uv sync --dev

Running Tests

uv run pytest

Running Tests with Coverage

uv run pytest --cov=openwebui_bootstrap --cov-report=term-missing

Code Formatting

uv run ruff format
uv run ruff check

License

MIT