Upgrade to v1.5.0

This is a substantial operational upgrade. HAWKI RAG now uses Temporal for ingestion orchestration and PostgreSQL for Laravel and Temporal persistence. Plan a maintenance window for an existing installation.

Important: make up-core creates PostgreSQL and runs Laravel schema migrations automatically. It does not transfer application rows from a previous MariaDB/MySQL database into PostgreSQL.

1. Back up the running installation

Before changing containers or environment variables, back up:

• the current .env;
• the existing application database;
• the shared-storage volume;
• Qdrant collections; and
• Neo4j data.

Keep the old database and volumes until ingestion, retrieval, and document management have been verified on the upgraded stack.

2. Reconcile .env with the new template

Do not overwrite a working .env with .env.example. Preserve existing secrets and add or update the relevant values from the new template.

Area	Values to review	Why
Application database	DB_CONNECTION, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD	Laravel now uses PostgreSQL in the core stack.
Temporal	HAWKI_RAG_TEMPORAL_ENABLED, TEMPORAL_ADDRESS, TEMPORAL_NAMESPACE, task queues and timeouts	These values connect Laravel and the Python workers to the workflow engine.
Shared storage	SHARED_STORAGE_ROOT, HAWKI_RAG_PIPELINE_ROOT, HAWKI_RAG_TEMPORAL_SHARED_ROOT	Every ingestion stage must resolve the same mounted files.
Crawler	CUSTOM_CRAWLER_URL, EXTERNAL_SCRAPER_URL, EXTERNAL_SCRAPER_START_PATH, EXTERNAL_SCRAPER_STATUS_PATH	The supported Crawl4AI contract uses http://crawl4ai-service, /crawl, and /status/{job_id}.
Converter	EXTERNAL_CONVERTER_URL, FILE_CONVERTER_BASE_URL, tokens and endpoint paths	The converter is external to the core Compose stack and must be reachable on the shared network.
Models	Ollama, LiteLLM, embedding, chat, and vision variables	Existing vector data remains compatible only while its embedding model and dimensions remain compatible.

3. Plan the database transition

Fresh installations require no manual database creation. Existing MariaDB/MySQL installations require a deliberate, tested transfer of any application records that must be retained.

HAWKI RAG does not currently provide an automated cross-database data-transfer command. Use a DBA-reviewed migration procedure or begin with a fresh PostgreSQL application database and recreate the required application metadata. Do not delete the previous database or its volume until users, datasets, documents, jobs, and pipeline state have been verified.

4. Start the upgraded stack

From the repository root, use the supported production-shaped startup:

make up-core

This command prepares the required Docker networks, starts PostgreSQL, waits for database health, applies Laravel schema migrations, and then starts writable application and worker services.

The crawler and file converter remain external services. Start them before submitting ingestion work and confirm that they are attached to hawki-network.

5. Decide whether datasets need re-ingestion

Re-ingestion is not required only because orchestration moved to Temporal. Re-ingest affected datasets when:

• the embedding provider, model, or vector dimensions changed;
• existing Qdrant data was not retained;
• graph data needs to be rebuilt under the canonical entity/relation model; or
• the source content itself must be refreshed.

Avoid mixing vectors produced by incompatible embedding models in one collection.

6. Verify before removing old services

Begin with:

make health
make test-services

These commands are baseline checks, not proof of a complete upgrade. Also confirm explicitly that:

• every required Temporal worker, the RAG bridge, and the reranker are running;
• the Laravel UI and /swagger/ load through the intended public path;
• Pipeline Health reports required services without repair warnings;
• a small crawl or upload reaches a terminal successful state;
• fast, mixed, and deep retrieval return the expected dataset-scoped chunks;
• Neo4j graph facts and source provenance are present when graph ingestion is enabled;
• document deletion removes only the intended Qdrant and Neo4j records; and
• the new backups can be restored successfully.

Only after these checks pass should the previous database or superseded application containers and volumes be retired.

For the complete environment reference and startup modes, see the installation guide and Run HAWKI RAG.