First Stalwart update: v0.16.20 → v0.16.23 — is my plan sound?

[cgibson]

Your question

Hi, I’m new to Stalwart. I’ve only been running my server for a couple of weeks. I’m planning my first update. My server is currently running v0.16.20 and I’m going to update it to v0.16.23. I was hoping that if I share my update plan here with the community that others can verify that my plan is solid. Hope that’s OK!

BTW, I need to update to v0.16.23 to resolve this issue:

iPhone Apple Mail POP3 shows HTML/MIME messages as empty

0.16.23 was released on 21 September. The bug was in POP3 TOP, which Apple Mail uses to fetch headers and previews: it counted the requested lines from the first byte of the message, headers included, and reported the full size even for a partial answer. Messages Apple Mail already downloaded in that state may stay empty, so test with new HTML mail after upgrading. If the old ones are still blank, removing and re-adding the account (with mail left on the server) makes it fetch them again.

Stalwart support has confirmed that the bug was fixed in v0.16.23:

“0.16.23 was released on 21 September. The bug was in POP3 TOP, which Apple Mail uses to fetch headers and previews: it counted the requested lines from the first byte of the message, headers included, and reported the full size even for a partial answer. Messages Apple Mail already downloaded in that state may stay empty, so test with new HTML mail after upgrading. If the old ones are still blank, removing and re-adding the account (with mail left on the server) makes it fetch them again.”

My Stalwart server is running on macOS 26.6.2. Not using Docker.

Here’s my plan, please let me know if I’m missing anything. THANKS!

UPDATE STEPS v0.16.20 to v0.16.23

1. Verify the current installation version.

stalwart --version
which stalwart
ps -ef | grep ‘[s]talwart’
sudo launchctl print system/stalwart

2. Create rollback copy of the v0.16.20 binary.

sudo cp -p /usr/local/bin/stalwart /usr/local/bin/stalwart-0.16.20

3. Verify the rollback copy of the binary exists and works.

ls -lh /usr/local/bin/stalwart /usr/local/bin/stalwart-0.16.20
/usr/local/bin/stalwart-0.16.20 --version

;Expected output:
;0.16.20

4. Download the Stalwart v0.16.23 binary.

mkdir -p ~/stalwart-0.16.23
cd ~/stalwart-0.16.23
curl -L -O https://github.com/stalwartlabs/stalwart/releases/download/v0.16.23/stalwart-aarch64-apple-darwin.tar.gz

5. Verify the download was successful.

ls -lh stalwart-aarch64-apple-darwin.tar.gz
shasum -a 256 stalwart-aarch64-apple-darwin.tar.gz

;Expected SHA-256 output:
;ccab39449b63443f62c433af8baf95e8317c9a7dea993d84e588b2900372414e

6. Extract and verify the new Stalwart binary.

tar -xzf stalwart-aarch64-apple-darwin.tar.gz
~/stalwart-0.16.23/stalwart --version
file ~/stalwart-0.16.23/stalwart

;Expected output:
;0.16.23
;Mach-O 64-bit executable arm64

7. Stop the Stalwart server.

sudo launchctl kill SIGTERM system/stalwart
sleep 5

8. Verify Stalwart has stopped.

ps -ef | grep ‘[s]talwart’

;Expected:
;No output.

;IMPORTANT: If a Stalwart process is still running, stop here and investigate before continuing.

9. Replace the old binary with the new binary in /usr/local/bin.

sudo cp ~/stalwart-0.16.23/stalwart /usr/local/bin/stalwart
sudo chown root:wheel /usr/local/bin/stalwart
sudo chmod 755 /usr/local/bin/stalwart

10. Verify the installed version, with the new binary in place.

/usr/local/bin/stalwart --version

;Expected:
;0.16.23

11. Start the Stalwart server.

sudo launchctl kickstart -k system/stalwart
sleep 5

12. Verify Stalwart is running.

ps -ef | grep ‘[s]talwart’

sudo launchctl print system/stalwart

stalwart --version

;Expected:
;0.16.23

13. Check the current active Stalwart log for activity.

sudo tail -50 /var/log/stalwart/stalwart.$(date +%Y-%m-%d)

;Check for any obvious errors, startup failures, configuration errors, database errors, or listener failures.

14. Check the listening ports of the Stalwart server.

sudo lsof -nP -iTCP -sTCP:LISTEN | grep stalwart

15. Perform some basic network port connectivity tests.

nc -vz xxxxxxxxx.net 25
nc -vz xxxxxxxxx.net 587
nc -vz xxxxxxxxx.net 993
nc -vz xxxxxxxxx.net 995

16. Perform mail testing.

• Send an external test email TO a xxxxxxxxx.net account.
• Send an email FROM a xxxxxxxxx.net account to an external address.
• Send a NEW HTML-format test email to the iPhone POP3 account.
• Test POP3 on the iPhone using Apple Mail.
• Verify that the new HTML message displays correctly in Apple Mail.

;IMPORTANT: Messages that Apple Mail downloaded while the POP3 TOP bug was present may remain empty even after upgrading. If previously downloaded messages are still blank, remove and re-add the POP3 account, leaving the mail on the server, so Apple Mail downloads the messages again.

17. Monitor the Stalwart log and mail delivery after the upgrade.

sudo tail -f /var/log/stalwart/stalwart.$(date +%Y-%m-%d)

;IMPORTANT: Pay particular attention to mail delivery and queued messages. I am aware of a community-reported issue involving v0.16.23 where mail delivery can stop while messages remain queued, so I want to monitor the server after the upgrade to make sure this does not occur.

18. Perform another launchd status check after the mail tests.

sudo launchctl print system/stalwart | grep -E ‘state =|pid =|program =’

END OF UPDATE STEPS

ROLLBACK STEPS v0.16.23 to v0.16.20

1. If there are any issues with the new v0.16.23 binary, rollback to the old binary.

2. Stop the Stalwart server.

sudo launchctl kill SIGTERM system/stalwart
sleep 5

3. Verify Stalwart has stopped.

ps -ef | grep ‘[s]talwart’

;Expected:
;No output.

4. Copy the old v0.16.20 binary back to /usr/local/bin/stalwart.

sudo cp -p /usr/local/bin/stalwart-0.16.20 /usr/local/bin/stalwart
sudo chown root:wheel /usr/local/bin/stalwart
sudo chmod 755 /usr/local/bin/stalwart

5. Verify the restored binary version.

/usr/local/bin/stalwart --version

;Expected:
;0.16.20

6. Start the Stalwart server.

sudo launchctl kickstart -k system/stalwart
sleep 5

7. Verify Stalwart is running.

ps -ef | grep ‘[s]talwart’
sudo launchctl print system/stalwart

8. Verify the Stalwart version.

stalwart --version

;Expected:
;0.16.20

END OF ROLLBACK STEPS

[helpbot]

This confirms: within v0.16.x, “replace the binary” is the whole upgrade procedure, no data migration steps required. Let me check the queue-stuck issue mentioned.

I have enough to reply confidently now. Let me check the forum for that queue issue reference the user mentioned.

I have enough to answer now. Let me check the log file naming convention used in step 13 of the plan, and check if there’s community reports about 0.16.23 queue issue to warn about accurately.

I have enough to give a grounded reply now. Let me check the release artifact naming/checksums approach briefly, and also confirm log file naming and CLI usage for stopping/checking service.

I have enough now to give a grounded, useful answer. Let me check if there’s guidance on the install.sh being the recommended upgrade path vs manual binary swap, and whether checksums are published.

Your overall approach (stop service, swap binary, restart, verify, keep a rollback copy) is sound, but there are a couple of things worth correcting based on the actual install layout Stalwart ships:

1. Service name. The macOS launchd service that the official installer writes is labeled stalwart.mail, not stalwart. The property list (stalwart.mail.plist) sets Label to stalwart.mail and runs bin/stalwart --config=.../etc/config.json. So your launchctl commands should target system/stalwart.mail, e.g.:

sudo launchctl kickstart -k system/stalwart.mail

not system/stalwart. If your install actually uses a different label, check with sudo launchctl print system | grep stalwart first to confirm the exact target before running kill/kickstart against a name that doesn’t exist.

2. Patch upgrade is low-risk by design. Per the upgrading guidance, patch releases (the third version number, .20 → .23) are backward-compatible fixes only — safe to apply without reading release notes in full, and a straight binary swap plus restart is the expected upgrade mechanism (there’s no automated upgrade tool yet, so manual replace is correct).

3. Log path assumption. Your log-check command assumes /var/log/stalwart/stalwart.<date>. That’s only correct if your log Tracer’s path is /var/log/stalwart and prefix is stalwart — those are configurable and default to "stalwart" for the prefix, but the path is explicitly set during setup. Confirm your actual Log tracer path/prefix (WebUI: Settings › Telemetry › Tracers, or Log object) before relying on that exact filename.

4. Rollback copy step is good practice and matches the general pattern in Stalwart’s own upgrade docs (keep the old binary until the new one is verified working), though this isn’t an officially documented rollback procedure — it’s just sound sysadmin practice, and your steps look correct for it.

I could not find anything in the current docs, changelog, or source confirming the specific SHA-256 checksum you listed for the v0.16.23 aarch64-apple-darwin tarball, or details about a known “mail delivery stops while messages remain queued” issue in v0.16.23 — you should verify the checksum yourself against the GitHub release page, and treat that queue concern as something to watch for empirically rather than a confirmed bug.

Everything else in your plan (stop → verify stopped → swap binary → verify version → start → verify running → tail logs → port checks → mail tests → monitor) is a reasonable, safe sequence for a patch-level upgrade.

This is an automated reply from the Stalwart Help Bot. Other community members may follow up if this answer is incomplete or wrong.

[cgibson]

Well, my plan worked. I updated to 0.16.23 this morning. All seems to be working fine (and the Apple Mail POP issue is resolved).

I had to make a few adjustments to my plan, but here it is in case someone else needs to do the same:

UPDATE STEPS v0.16.20 to v0.16.23

1. Verify the current installation version.

stalwart --version
which stalwart
ps -ef | grep ‘[s]talwart’
sudo launchctl print system/stalwart

2. Create rollback copy of the v0.16.20 binary.

sudo cp -p /usr/local/bin/stalwart /usr/local/bin/stalwart-0.16.20
ls -lh /usr/local/bin/stalwart /usr/local/bin/stalwart-0.16.20

3. Verify the rollback copy of the binary exists and works.

ls -lh /usr/local/bin/stalwart /usr/local/bin/stalwart-0.16.20
/usr/local/bin/stalwart-0.16.20 --version

;Expected output:
;0.16.20

4. Download the Stalwart v0.16.23 binary.

mkdir -p ~/stalwart-0.16.23
cd ~/stalwart-0.16.23
curl -L -O https://github.com/stalwartlabs/stalwart/releases/download/v0.16.23/stalwart-aarch64-apple-darwin.tar.gz

5. Verify the download was successful.

ls -lh stalwart-aarch64-apple-darwin.tar.gz
shasum -a 256 stalwart-aarch64-apple-darwin.tar.gz

;Expected SHA-256 output:
;ccab39449b63443f62c433af8baf95e8317c9a7dea993d84e588b2900372414e

6. Extract and verify the new Stalwart binary.

tar -xzf stalwart-aarch64-apple-darwin.tar.gz
chmod 755 ~/stalwart-0.16.23/stalwart
~/stalwart-0.16.23/stalwart --version
file ~/stalwart-0.16.23/stalwart

;Expected output:
;0.16.23
;Mach-O 64-bit executable arm64

7. Stop the Stalwart server.

sudo launchctl bootout system /Library/LaunchDaemons/stalwart.plist
sleep 5

8. Verify Stalwart has stopped.

ps -ef | grep ‘[s]talwart’

;Expected:
;No output.

;IMPORTANT: If a Stalwart process is still running, stop here and investigate before continuing.

9. Replace the old binary with the new binary in /usr/local/bin.

sudo cp stalwart /usr/local/bin/stalwart
sudo chown root:wheel /usr/local/bin/stalwart
sudo chmod 755 /usr/local/bin/stalwart

10. Verify the installed version, with the new binary in place.

/usr/local/bin/stalwart --version

;Expected:
;0.16.23

11. Start the Stalwart server.

sudo launchctl bootstrap system /Library/LaunchDaemons/stalwart.plist
sleep 5

12. Verify Stalwart is running.

ps -ef | grep ‘[s]talwart’

sudo launchctl print system/stalwart

stalwart --version

;Expected:
;0.16.23

13. Check the current active Stalwart log for activity.

sudo tail -50 /var/log/stalwart/stalwart.$(date +%Y-%m-%d)

;Check for any obvious errors, startup failures, configuration errors, database errors, or listener failures.

14. Check the listening ports of the Stalwart server.

sudo lsof -nP -iTCP -sTCP:LISTEN | grep stalwart

15. Perform some basic network port connectivity tests.

nc -vz xxxxxxxxx.net 25
nc -vz xxxxxxxxx.net 587
nc -vz xxxxxxxxx.net 993
nc -vz xxxxxxxxx.net 995

16. Perform mail testing.

• Send an external test email TO a xxxxxxxxx.net account.
• Send an email FROM a xxxxxxxxx.net account to an external address.
• Send a NEW HTML-format test email to the iPhone POP3 account.
• Test POP3 on the iPhone using Apple Mail.
• Verify that the new HTML message displays correctly in Apple Mail.

;IMPORTANT: Messages that Apple Mail downloaded while the POP3 TOP bug was present may remain empty even after upgrading. If previously downloaded messages are still blank, remove and re-add the POP3 account, leaving the mail on the server, so Apple Mail downloads the messages again.

17. Monitor the Stalwart log and mail delivery after the upgrade.

sudo tail -f /var/log/stalwart/stalwart.$(date +%Y-%m-%d)

;IMPORTANT: Pay particular attention to mail delivery and queued messages. I am aware of a community-reported issue involving v0.16.23 where mail delivery can stop while messages remain queued, so I want to monitor the server after the upgrade to make sure this does not occur.

18. Perform another launchd status check after the mail tests.

sudo launchctl print system/stalwart | grep -E ‘state =|pid =|program =’

END OF UPDATE STEPS

ROLLBACK STEPS v0.16.23 to v0.16.20

1. If there are any issues with the new v0.16.23 binary, rollback to the old binary.

2. Stop the Stalwart server.

sudo launchctl bootout system /Library/LaunchDaemons/stalwart.plist
sleep 5
sudo launchctl print system/stalwart
;Expected output:
;Could not find service “stalwart” in domain for system

ps -ef | grep ‘[s]talwart’

3. Verify Stalwart has stopped.

ps -ef | grep ‘[s]talwart’

;Expected:
;No output.

4. Copy the old v0.16.20 binary back to /usr/local/bin/stalwart.

sudo cp -p /usr/local/bin/stalwart-0.16.20 /usr/local/bin/stalwart
sudo chown root:wheel /usr/local/bin/stalwart
sudo chmod 755 /usr/local/bin/stalwart

5. Verify the restored binary version.

/usr/local/bin/stalwart --version

;Expected:
;0.16.20

6. Start the Stalwart server.

sudo launchctl bootstrap system /Library/LaunchDaemons/stalwart.plist
sleep 5
ps -ef | grep ‘[s]talwart’

7. Verify Stalwart is running.

ps -ef | grep ‘[s]talwart’
sudo launchctl print system/stalwart

8. Verify the Stalwart version.

stalwart --version

;Expected:
;0.16.20

END OF ROLLBACK STEPS