Upgrade & Recovery procedures

Upgrade procedure

Pin the Stalwart image to a tested version:

image: stalwartlabs/stalwart:v0.16

Do not use latest for an important production server.

Before upgrading:

1. Read the release notes.

2. Review migration instructions.

3. Run an offsite backup.

4. Verify the backup exists.

5. Record the current working image tag.

6. Change the image tag.

7. Redeploy.

8. Inspect startup logs.

9. Test the administration UI.

10. Test port 465.

11. Test port 993.

12. Test incoming delivery.

13. Test outgoing delivery.

14. Keep the old image tag available for rollback.

Never delete the persistent volumes during a normal update.

Disaster-recovery procedure

If the VPS is lost, recreate the server as follows.

Recovery from volume backups

1. Provision a replacement VPS.

2. Install Dokploy.

3. Recreate the Stalwart Compose application.

4. Restore stalwart_config.

5. Restore stalwart_data.

6. Restore or recreate certificate extraction.

7. Point mail.example.com to the replacement VPS.

8. Change the replacement VPS PTR to mail.example.com.

9. Verify ports 25, 465, 587, and 993.

10. Verify the SMTP greeting.

11. Test incoming mail.

12. Test outgoing mail.

13. Verify SPF, DKIM, and DMARC.

If the original Stalwart data is not restored, Stalwart may generate different DKIM keys. The public DKIM DNS records must then be replaced.

Recovery with external PostgreSQL and S3

When structured data and blobs are external, a replacement VPS becomes easier to provision.

The replacement requires:

Stalwart configuration
Database credentials
Object-storage credentials
DNS records
PTR record
TLS certificate integration

The VPS becomes closer to disposable compute, but the external database and storage still require independent backups.