README

A composer-installable BookStack package to sync BookStack books, pages, and attachments into OpenWebUI knowledge bases using only BookStack's Laravel runtime.

Install

composer require pronomix-gmbh/bookstack-ai-sync

Run migrations:

php artisan migrate

If auto-discovery is disabled, add the service provider to config/app.php:

Pronomix\BookStackOpenWebUISync\BookStackOpenWebUISyncServiceProvider::class,

Configuration

Copy the env keys you need:

OPENWEBUI_ENABLED=true
OPENWEBUI_INSTANCE_NAME=bookstack
OPENWEBUI_BASE_URL=https://openwebui.example.com
OPENWEBUI_API_KEY=your-api-key
OPENWEBUI_TIMEOUT=30
OPENWEBUI_VERIFY_TLS=true
OPENWEBUI_WORKSPACE_ENABLED=true
OPENWEBUI_WORKSPACE_MODEL_ID=
OPENWEBUI_WORKSPACE_MODEL_NAME=

Scheduler / Queue

This package stores tasks in the database and does not require a queue worker. The cron job is required: without it, tasks never run and no sync happens. To process tasks via cron:

* * * * * php /path/to/bookstack/artisan openwebui:process-queue >> /dev/null 2>&1

If you already run php artisan schedule:run, you can also register that cron and call openwebui:process-queue manually as needed.

Optional queue workers can be enabled by setting:

OPENWEBUI_QUEUE_DISPATCH=true

To prevent overlapping runs (e.g., if a queue run takes longer than a minute), use flock in your cron:

* * * * * flock -n /tmp/openwebui-queue.lock php /path/to/bookstack/artisan openwebui:process-queue >> /dev/null 2>&1

Workspace (model) sync

OpenWebUI does not currently expose a dedicated workspace API, so this package optionally syncs all knowledge bases into a single OpenWebUI model entry. By default the model ID and name are taken from OPENWEBUI_INSTANCE_NAME. You can override with:

OPENWEBUI_WORKSPACE_ENABLED=true
OPENWEBUI_WORKSPACE_MODEL_ID=bookstack
OPENWEBUI_WORKSPACE_MODEL_NAME=BookStack

Commands

openwebui:process-queue - Process pending sync tasks
openwebui:list-queue - List open sync tasks
openwebui:sync-all - Enqueue sync for all books
openwebui:sync-book {bookId?} - Enqueue sync for a single book (prompts when omitted)
openwebui:test-connection - Test OpenWebUI connectivity
openwebui:clear-queue - Clear queued sync tasks (defaults to pending/failed)
openwebui:install - Run only this package's migrations
openwebui:uninstall - Roll back and remove package tables (with safety flags)

Behavior

Each BookStack book becomes an OpenWebUI knowledge base named ${instance}:${bookname}.
Pages and attachments are uploaded as files into the matching knowledge base.
Identity is stable across page renames by using page_id and attachment_id in external keys.
Deletes are propagated to OpenWebUI.
Optional workspace sync attaches all known knowledge bases to a single OpenWebUI model (workspace) and removes stale ones.

Development

Run tests:

vendor/bin/phpunit

pronomix-gmbh / bookstack-ai-sync

Maintainers

Details