Step by step upgrade from v0.15.x to v0.16.x

mailcowboy · June 21, 2026, 9:10pm

Helpbot please give me step by step instructions to upgrade from v0.15 to v0.16 without backup. I am using Debian 13.

I have the binary in opt/stalwart-mail/install

ideer2 · June 21, 2026, 10:16pm

UPGRADING/v0_16.md

main

# Upgrading from `v0.15.x` to `v0.16.x`

Stalwart `v0.16.x` introduces **significant breaking changes** that make its configuration and management layer **completely incompatible** with every previous release. The database layout used to store user data (emails, calendars, contacts, files, blobs, search indexes) is **not** affected by this change, so message bodies, mailboxes, calendar events, and shared files remain on disk unchanged. What does change is **how the server is configured and managed**, and because those records live inside the same database, a multi-step migration is required.

Before continuing, please read this document in full. Skipping steps will leave the server in an unrecoverable state and will require restoring from a backup.

If any step below raises questions, a dedicated discussion thread for the `v0.16` upgrade is open at https://support.stalw.art. The earlier design discussion that led to these changes is also public at https://github.com/stalwartlabs/stalwart/discussions/2892 and describes the user-reported problems that motivated each breaking change.

## A note on downtime

Email is a critical service, and we understand that a forced maintenance window is disruptive:  in some environments it is simply not an option. The breaking changes in `v0.16` are not cosmetic. Stalwart has been under continuous development for close to five years; in that time the feature set and the user base have both grown well beyond what the original configuration and management layer was designed for. The gap between what users need and what the old architecture can cleanly support has widened to the point where a redesign was unavoidable:  and the redesign itself unlocks a long list of frequently-requested features that were simply not implementable under the previous model. The storage layer is untouched by all of this: emails, calendars, contacts, files, and every other piece of user data stay exactly where they are. The migration is about configuration, not about data.

Operators who cannot accept downtime should **wait**. In the next two to three weeks we plan to release two tools that work together:

- A **zero-downtime migration utility** that moves data (accounts, mailboxes, calendars, contacts, files) from an existing (`v0.15.x` or below) deployment to a freshly-installed `v0.16.x` deployment one account at a time, while both servers are running.
- A **proxy** that sits in front of both deployments and routes each incoming connection to the server that currently owns that account. As accounts are migrated one by one, the proxy transparently shifts their traffic from the old deployment to the new one, so end users never notice a cutover.

Together, these let operators migrate a live production deployment on an account-by-account basis with no scheduled maintenance window. When those tools are available, the instructions in this document will be superseded for most deployments. Everyone else can follow the manual steps below during a scheduled maintenance window.

## What has changed

This file has been truncated. show original

mailcowboy · June 23, 2026, 3:33am

Thank you ideer2 for the link to the update and for trying to help.

I read those instructions multiple times but there is so much info that it is a bit confusing to me. I was looking for straight forward directions with binary not docker. And I don’t need a backup because I take a snapshot of the server and can go back to previous time no problem.

I was hoping for the bot to reply to my question.

Or perhaps someone would like to help by replying with instructions on how to update step by step in Debian 13 binary from v0.15 to v0.16. No need for backup.

mailcowboy · June 23, 2026, 3:06pm

Please can someone confirm I have these steps correct for upgrading my mail server:

Download the script from the Stalwart repository:

$ curl -fLO raw.githubusercontentDOTcom/stalwartlabs/stalwart/refs/heads/main/resources/scripts/migrate_v016.py

Create a Python virtual environment

$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ pip install requests urllib3

Dump the live v0.15.x settings

(.venv) $ python migrate_v016.py dump
–url mail.exampleDOTcom
–username admin
–password adminPassword
–settings settings.json
–principals principals.json

Convert the dump to the new format

(.venv) $ python migrate_v016.py convert
–settings settings.json
–principals principals.json
–config config.json
–output export.json

I WILL SKIP THE BACKUP OF THE DATABASE
Perform the migration

6a. Download the v0.16 binary. Grab the release matching the target platform from githubDOTcom/stalwartlabs/stalwart/releases/latest. Do not replace the running binary yet.

6b. Stop the old service.

$ sudo systemctl stop stalwart

Back up the old binary and install the new one

$ sudo mv /usr/local/bin/stalwart /usr/local/bin/stalwart.v015
$ sudo mv /path/to/downloaded/stalwart /usr/local/bin/stalwart
$ sudo chmod 0755 /usr/local/bin/stalwart
$ sudo chown root:root /usr/local/bin/stalwart

Install the new config.json

$ sudo mv /path/to/config.json /etc/stalwart/config.json
$ sudo chown stalwart:stalwart /etc/stalwart/config.json
$ sudo chmod 0640 /etc/stalwart/config.json

Start the new binary in recovery mode from the foreground

$ sudo -u stalwart env
STALWART_RECOVERY_MODE=1
STALWART_RECOVERY_ADMIN=admin:someTemporaryPassword
/usr/local/bin/stalwart --config=/etc/stalwart/config.json

Apply the exported snapshot (this section I am confused)

10a. Install new CLI

curl --proto ‘=https’ --tlsv1.2 -LsSf
githubDOTcom/stalwartlabs/cli/releases/latest/download/stalwart-cli-installer.sh | sh

10b. apply snapshot

$ export STALWART_URL=://127.0.0.1:8080
$ export STALWART_USER=admin
$ export STALWART_PASSWORD=someTemporaryPassword
$ stalwart-cli apply --file /path/to/export.json

Reconfigure the service manager

11a. For systemd (typically /etc/systemd/system/stalwart.service), locate the ExecStart= line and change the --config= argument:

ExecStart=/usr/local/bin/stalwart --config=/etc/stalwart/config.json

11b. Then reload the unit:

$ sudo systemctl daemon-reload

Start the service.

$ sudo systemctl start stalwart

Post-migration tasks

13a. Log in to the admin panel

mail.example.org/admin

Recalculate disk quotas
Create a permanent administrator

Create a real administrator account through Management → Accounts, verify the new account can log in, and then remove STALWART_RECOVERY_ADMIN from:

the systemd environment file (for example /etc/stalwart/stalwart.env) and restart the service, or
the init.d defaults file, and restart the service

DONE

Can someone please confirm these are the right steps for me to upgrade from v0.15 to v.016 with Debian 13 with the binary (not docker). Am I missing any steps here?

I know I can test it but I just want to get some guidance from more experienced forum friends before I do this at 2 am on a weekend. I only have 6 email accounts and one domain. I have this mail server for my family.

I deleted the https from the post because it will only allow 2 links.

Thanks.

stalwart · June 24, 2026, 2:04pm

The canonical procedure is UPGRADING/v0_16.md in the repo, and it has an “Option A: Binary deployments (systemd/init.d)” section that’s exactly your case. Condensed, for a Debian binary install already on 0.15.x:

With 0.15 still running, grab resources/scripts/migrate_v016.py, make a venv, pip install requests urllib3, then run it in dump mode (your URL, admin user/pass) to produce settings.json and principals.json, then convert mode to produce config.json and export.json.
First, one important point: the 0.16 first-start irreversibly wipes the old config and directory records and resets quotas. Your data on disk survives, but you do need a rollback point. Your server snapshot counts as that backup, so you’re fine as long as you can roll back to it if needed; don’t skip that.
Stop the 0.15 service (systemctl stop stalwart), keep the old binary, install the 0.16 binary into your /opt path, and put the generated config.json where the old config lived.
Start once in the foreground in recovery mode as the stalwart user: STALWART_RECOVERY_MODE=1 STALWART_RECOVERY_ADMIN=admin:tempPass /opt/…/stalwart --config=/etc/stalwart/config.json. It wipes the incompatible subspaces, migrates the spam model, and listens only on 8080.
From another terminal, with stalwart-cli 1.0.2+ and STALWART_URL=http://127.0.0.1:8080, run stalwart-cli apply --file export.json.
Ctrl+C the foreground server, update your systemd unit’s --config to the new config.json, remove the recovery env vars, and systemctl start stalwart. Then recalc disk quotas from the WebUI.

I’d genuinely recommend dry-running this on a throwaway 0.16 first, because the config model changed completely (no TOML, accounts must be user@domain, the old /api is replaced by JMAP). Full doc: stalwart/UPGRADING/v0_16.md at main · stalwartlabs/stalwart · GitHub.

mailcowboy · June 24, 2026, 10:47pm

As always, thank you Stalwart Team for taking the time to reply to my question and for numbering the steps I am to follow. I will definitely try these instructions to update to v0.16 this weekend. Per your recommendation, I will dry-run this on a throwaway 0.16 first.

mailcowboy · June 27, 2026, 10:40am

Tried to upgrade but failed. I was able to do step 1-3 but I could not do step 4.

Start once in the foreground in recovery mode as the stalwart user: STALWART_RECOVERY_MODE=1 STALWART_RECOVERY_ADMIN=admin:tempPass /opt/…/stalwart --config=/etc/stalwart/config.json..

I kept getting a message “sudo -u stalwart env does not exist or command not found”

My v0.15 installation is in:

/opt/stalwart-mail/bin ../data ../etc ../logs

and my binary name is: stalwart-mail (not stalwart).

Perhaps it is better for me to do a full reinstallation of Stalwart v0.16 since I only have a few email accounts and one domain. I don’t mind starting from 0 by completely uninstalling v0.15 from my linux server and running the installation script again as I don’t need the emails in the current installation. Before I do I want to ask this question: Is there a way to keep the same dkim in the new installation from a previous installation?

I can recreate the domain and emails in the new installation but would like to keep the same dkim settings so I don’t have to update the DNS records. The reason I want to keep the same dkim record is because all my emails are successfully arriving in the inbox of all the major email providers. Perhaps getting a new dkim has not impact but I just want to check first.

Thanks!

mailcowboy · July 4, 2026, 12:01am

4th of July weekend and with good luck I was able to upgrade my v0.15.5 to v0.16.11. I followed the instructions from Stalwart and I used an AI platform (not going to name here) and it gave me many instructions. It took me 2 hours of tinkering here and there and restoring a couple of snapshots and I finally got it working. Version 0.16.x is really nice.

LOVE STALWART MAIL!!!

Topic		Replies	Views
Allow using IP and http for admin webui Issues	3	59	June 15, 2026
Database migration Questions	10	156	May 28, 2026
All email lost after upgrading to stalwart 0.16 Issues	9	336	May 25, 2026
Upgrade to 0.16 Questions	4	64	June 16, 2026
Upgrading from last 0.15 to 0.16 questions Questions	1	39	June 25, 2026

Step by step upgrade from v0.15.x to v0.16.x

Related topics