Upgrading

Version 1.4.0: Required manual changes

Update the checkout and Haraka image to enable automatic certificate renewal and DKIM signing for custom domains.

Keep your existing DKIM key and shroudemail selector in haraka/haraka_config/config/dkim/<EMAIL_DOMAIN>/. The matching TXT record at shroudemail._domainkey.<EMAIL_DOMAIN> must be present. Do not regenerate a working key.

Run from hosting/ during a maintenance window. Stop Haraka before updating so it cannot load the certificate configuration before the bundle is ready:

docker compose stop haraka &&
git pull --ff-only &&
docker compose pull haraka &&
docker compose up -d --build cron &&
docker compose exec cron /etc/periodic/daily/bundle_certs &&
docker compose up -d --no-deps --force-recreate haraka

If a command fails, keep Haraka stopped until fixed. Check startup logs with docker compose logs --tail=100 haraka.

Test a forwarded message and an alias reply from a custom domain at an external inbox. Check for d=<custom-domain>; s=shroudemail in DKIM-Signature and dkim=pass in Authentication-Results. Existing DKIM CNAMEs need no changes.

Certificate renewals and custom-domain signing are automatic after this upgrade.

Version 1.0 breaking changes

On 2023-03-11, we released Shroud.email version 1.0.0. This version contains a potentially-breaking change that may break if you have several aliases with the same address, but different cases – e.g. alias@example.com and ALIAS@example.com. We include a command to automatically merge aliases like this. This command needs to be run before you upgrade.

To deploy this version, follow these steps:

1. Update to version 0.2.4. Do this by changing the version in your docker-compose.yml to ghcr.io/shroud-email/shroud.email:0.2.4 and then running

docker compose pull web && docker compose up --force-recreate -d

2. Once that is running, execute the following command:

docker compose exec web /home/elixir/app/bin/shroud rpc Shroud.Release.make_emails_case_insensitive

3. Update to version 1.0.0 by changing the version in your docker-compose.yml to ghcr.io/shroud-email/shroud.email:1, and re-running

docker compose pull web && docker compose up --force-recreate -d