jcoffey-dev
97995fdebb
The README keeps what the tool is, how to install it and the first commands, and points to the guide on docs.ihasmail.org. Everything else moves, whole, into docs/ and CONTRIBUTING.md, where it is organized for readers who want the detail. Where the old README disagreed with the code, the code wins.
4.1 KiB
Troubleshooting and known limits
Problems by the message or symptom you see, what causes each, and what to do; then the limits of what the tool does. Back to the README, or see the guide on docs.ihasmail.org.
Problems
port 443 is already in use on this host
Something else, often an existing web server, holds a port the mail host needs.
Free it, or use a separate host. With --local, move --webmail-bind or
--stalwart-bind instead.
project ihasmail-example-com already exists in Docker
An earlier run left containers or volumes behind. If it's a failed attempt you
want to discard: ihasmail-oneshot destroy --dir ihasmail-example-com --yes,
then deploy again. To keep it and deploy another, pass a different --project
and --dir.
... already has files in it; give --dir a new or empty directory
The tool never writes over an existing deployment. Choose another directory, or
destroy the old deployment first.
A deploy stopped partway.
The error says which step failed and shows the last lines of the relevant
container's log. The stack is left as it was, for you to inspect. To start
again from nothing: ihasmail-oneshot destroy --dir DIR --yes, fix the cause,
and deploy again.
Pool overlaps with other one on this address space
The default private network 172.31.253.0/24 collides with a Docker network you
already have. Destroy the partial deployment and deploy again with, for
example, --subnet 172.31.200.0/24.
Stalwart has no certificate yet
Usually DNS: the mail host or one of the autoconfig, autodiscover,
mta-sts, ua-auto-config names doesn't resolve to this host yet, or port 80
isn't reachable from the internet. Check with dig +short mail.example.com from
somewhere else, fix it, then run ihasmail-oneshot certs --dir DIR. Stalwart's
reasons are in its log:
docker compose logs stalwart | grep -i acme
Caddy has no certificate for webmail.example.com yet
Same causes. Caddy retries by itself with increasing delays. See
docker compose logs caddy | grep -i error.
Mail arrives but sent mail never does.
Outbound port 25 is almost always the cause. Find the mail server of a domain
you send to with dig +short MX example.net, then test from the host with
nc -vz <that mail server> 25. Stalwart's log names each delivery
failure (docker compose logs stalwart). Also check that reverse DNS for the host's address
names the mail host.
Sent mail lands in spam.
Check that the SPF, DKIM and DMARC records from dns-records.zone are
published exactly, and that reverse DNS is set. New addresses need a little time
to build a sending reputation.
The webmail signs everyone out.
Expected after docker compose restart ihasmail, any ihasmail upgrade, or a
reboot: sessions live in memory.
/api/health shows push accounts pending that never become verified.
Stalwart can't reach https://webmail.example.com from inside its container.
Mail still updates in real time over the relay. The usual causes are a host
firewall that drops traffic from Docker's bridge to the host's own public
address, or the webmail name not resolving from the host.
Known limits
- One mail domain per deploy. More can be added afterwards in Stalwart or in ihasmail's Administration. Their certificates and DNS records are then yours to arrange.
- Linux Docker hosts only. The tool drives the local Docker daemon and publishes ports on the host it runs on.
- IPv4 on the private network. Ports are also published on IPv6 wherever Docker does so on the host.
- Fresh deployments only. It doesn't import an existing Stalwart, or adopt a deployment it didn't write.
- Stalwart doesn't retry a failed certificate order by itself, on a
transient CA error either.
certsstarts a new one. - Push by subscription isn't covered by the end-to-end test, whose lab has no public DNS for Stalwart to resolve the webmail's name through. Its fallback, the relay, is what the test exercises.
- Validated against Stalwart 0.16.22. Other Stalwart versions may change the registry objects the setup uses.