Say what the field report changed and what it left open

Three real 0.15.5 -> 0.16.19 migrations by @kaya-eu, at 221 GB and on
arm64, are worth recording — with the qualifications that make them
readable. They ran a commit predating the automated Docker cutover and did
that step by hand, so what those runs exercise is preflight, the dumps,
the conversion and the recovery-mode store migration.

Three new sections for what they found:

The store migration may need one more recovery boot. This is open. Two
failures, never both on one run, each cured by one extra recovery-mode
boot, and Stalwart's own "multi-step process" panic says the store
migration is not finished when the single boot exits. Documented as the
manual step rather than left for the next operator to rediscover, and
documented as unfixed rather than implied away.

A certificate that serves HTTPS may not serve the mail ports.
IMAPS/SMTPS/POP3S keep a self-signed certificate until
SystemSettings.defaultCertificateId is set. Written up beside the ACME
section, which has the same shape: something the converter does not carry
and nothing warns about. This tool should generate it and does not yet.

Do not boot recovery mode again afterwards already landed with the
artifacts it argues for; this links the production paragraph to it.

Two status claims were also stale. §4.5 still said the container path was
not reachable from the CLI, which #9 changed, and both it and §7 said no
real Stalwart image had been met — one has now been inspected, which is
how #11's two bugs were found. What remains untested is everything after
the recreate, and the Docker section now says what cutover carries and
how the config reaches the container.
This commit is contained in:
2026-08-29 17:53:38 -07:00
parent 82ddb027e4
commit d0d2954ad1
2 changed files with 98 additions and 11 deletions
+14 -6
View File
@@ -321,11 +321,15 @@ against an already-migrated store.
the previous container again. The `docker inspect` of the container as it
was is preserved as the `container-definition` artifact before anything
is replaced, for the same reason the unit file is.
- **Status: the container path is implemented and not yet reachable from
the CLI** - `run` does not pass container options, so a container is
still refused there. Wiring it up, and lifting preflight's refusal for
the containers it can now handle, is the remaining work in
[#3](https://github.com/LINUXexpert-org/stalwart-migrator/issues/3).
- **Status: the container path is wired end to end and reachable from the
CLI** behind `--container-path-unproven` ([#9]). What it inspects and
what it assembles have been checked against a real
`stalwartlabs/stalwart` image ([#11]); what has not been checked is
whether the recreated container comes up as the server it was. That is
what would retire the flag.
[#9]: https://github.com/LINUXexpert-org/stalwart-migrator/pull/9
[#11]: https://github.com/LINUXexpert-org/stalwart-migrator/pull/11
- Quota recalculation is the one step allowed to fail without failing the
phase. Stale counters are an accounting problem; a failed cutover is one
an operator has to respond to by restoring a machine that is otherwise
@@ -848,7 +852,11 @@ happens to need them. `preflight.DeploymentKind` is a type alias for
§4.5 lists exactly which two details are inferred. A smoke test against a
real 0.16 instance would settle both, and would let this step be promoted
from "warns on failure" to a hard check.
- **Docker is wired end to end and has never met a real Stalwart image.**
- **Docker is wired end to end and has never completed a migration against
a real Stalwart image.** A real image has now been inspected, which is
how the inherited-versus-overridden confusion above was found, and how it
emerged that cutover was never handing the new container the migrated
config. What remains unverified is everything after the recreate.
Preflight inspects a container and blocks on what stands in the way;
stage pulls and verifies an image; the recovery cycle runs in a throwaway
container against the live data; cutover recreates the container,