What happens on upgradeCopy Anchor Link

On every startup the server checks the data layout version (a STORAGE_VERSION file in the data directory; the current layout is version 2, backed by bichon-blob). If it detects data written by an older release, the service does not wipe, modify, or guess. It also does not exit.

Instead the process enters maintenance mode: it keeps running and answers every HTTP request with a 503 Service Unavailable page that explains exactly what to do, step by step. /api/status returns 503 as well, so a Docker healthcheck marks the container unhealthy while it stays fully reachable.

Why the container keeps runningCopy Anchor Link

Exiting would be the worst option under Docker: a stopped container can no longer be docker exec-ed into, yet that is the only practical way to run the interactive bichon-admin migration tool. In maintenance mode the container stays up, so the migration can be performed in place — and the WebUI page tells you the command to run.

The search index has its own versionCopy Anchor Link

Separately from the storage layout, each Tantivy index directory carries an INDEX_FORMAT marker. When a release changes the search index format, the Community build enters the same maintenance mode with a "Search index rebuild required" page. That is not a storage migration: run bichon-admin reindex and follow Rebuild Search Indexes.

Which migration do I need?Copy Anchor Link

Look inside your data directory (/data in the default Docker setup):

Not sure? Just start the new server version — the maintenance page names the problem, and bichon-admin itself verifies the layout and tells you if you picked the wrong option.

Running the migration (summary)Copy Anchor Link

Both migrations are run with the bundled bichon-admin tool, interactively:

Docker — the container is in maintenance mode and still running, so:

docker exec -it <bichon-container> bichon-admin

Other installs — from the install directory:

./bichon-admin

Pick the menu option matching your old version:

Both migration paths are non-destructive: legacy files are read and copied, never modified or deleted. If anything goes wrong, your original data is still intact and you can roll back by running the old version again.

After the migration completes, restart the service:

docker restart <bichon-container>

Third-party forksCopy Anchor Link

The migration paths on this page cover official Bichon editions only. A fork built from the Community codebase is an independent project: it may not understand records that only Pro and Enterprise write — audit chains, legal-hold cases, minimum-retention locks and compliance configuration — and writing that data through it can silently drop it.

Moving an instance between a fork and Pro/Enterprise, in either direction, is unsupported. Take a full backup of the data root (plus the index and blob directories if overridden) before doing so, and confirm compatibility with the fork's maintainers for your exact versions. This is especially important when legal hold or a minimum-retention lock is enabled, because losing or misreading those records can break a compliance obligation.

Upgrading Community → Pro/Enterprise is different: install the Pro/Enterprise binary against the existing data root and upload the license. Because both builds share the same core and data model, it is a binary swap with no data migration. See Editions.

NotesCopy Anchor Link

• The maintenance page is served over plain HTTP even when HTTPS is enabled — TLS is initialized only after the startup checks pass.
• While in maintenance mode, the service logs a reminder of the reason every 10 minutes; docker logs --tail 50 <bichon-container> shows it.
• bichon-admin can also be run non-interactively for disaster recovery: bichon-admin restore --config <restore-config.json> --into <empty-dir> (see Storage & Backup).
• A fresh install never triggers migration — the check only fires when older data is actually present.