Upgrade from 0.4 to 0.5

Use this guide when upgrading an existing Fluxmail 0.4.x installation to 0.5.0. New installations do not need these steps.

Before upgrading

Back up the complete Fluxmail data directory before installing 0.5.0. The default directory is ~/.fluxmail for a local installation and /data in the Docker image.

The upgrade performs a breaking SQLite migration. An older Fluxmail binary cannot use the migrated database, so the backup is required if you need to roll back.

What the migration keeps

Fluxmail preserves member IDs and roles, mailbox messages and provider state, encrypted provider credentials, existing mailbox owners, selected member grants, and share-with-all behavior.

The old sharing modes map to the current fields as follows:

Mailboxes without a real owner remain unavailable to authenticated clients until the local administrator claim. The claim assigns those mailboxes to the chosen administrator. Mailboxes already owned by another member keep that owner.

What the migration changes

All existing members become pending because old member records do not have password credentials. Every legacy API key is revoked. Fluxmail does not convert memberless or implicitly trusted credentials.

Authenticated MCP and REST access remains blocked until one existing administrator claims the instance. Health checks and the server process remain available during this step. FLUXMAIL_AUTH=none is no longer supported.

Claim the instance

Run setup on the instance host:

fluxmail setup --existing-admin <id-or-email> --email admin@example.com

Use an existing administrator ID or email. Supply --email when the legacy record has no login email. Fluxmail asks for a new password, activates that administrator, assigns ownerless mailboxes, creates the local CLI profile, and logs it in.

If you do not know the administrator ID, run fluxmail setup once. The error lists the existing administrators that can be claimed. It does not modify the database.

Enroll the remaining members

The claimed administrator issues new enrollment codes:

fluxmail members list
fluxmail members invite <member>

Each member enrolls from their own CLI:

fluxmail --instance work login --server https://mail.example.com --enroll

Enrollment codes last seven days and work once. Members use their email and password for later logins.

Replace API keys

Create new keys after the owner has enrolled:

fluxmail apikey create --name agent --profile read-only

Each key now has an explicit member owner and capability policy. An optional mailbox allowlist can only narrow the owner's current mailbox access. Recreate administrative keys with the specific admin.* capabilities they need.

Verify the upgrade

Confirm that the administrator can log in, each mailbox has the intended owner and grants, and newly created API keys can reach only their allowed mailboxes. Keep the backup until these checks pass.

Recovery and rollback

Use fluxmail auth recover-admin <id-or-email> on the instance host if the claimed administrator loses access. The command resets that administrator's password and revokes their sessions.

To return to Fluxmail 0.4.x, stop Fluxmail and restore the complete data-directory backup. Do not open the migrated database with an older binary.