Troubleshooting lessons
Problem: Dokploy says the domain resolves to a private address
Symptom:
mail.example.com resolves to 10.x.x.x
Cause:
hostname: mail.example.com
Docker’s internal DNS associated the public name with the container’s private address.
Fix:
# Remove this line
hostname: mail.example.com
Keep the hostname configured inside Stalwart.
Problem: Port 587 is published but refuses connections
Docker shows:
0.0.0.0:587->587/tcp
but the client receives:
Connection refused
Cause: no Stalwart listener exists on port 587.
Fix:
Settings
→ Network
→ Listeners
→ Add SMTP listener
Use:
Bind: [::]:587
Implicit TLS: Disabled
Problem: Outgoing messages remain in the queue
Error:
Cannot assign requested address
os error 99
Cause: the VPS public IP was added to Stalwart’s source-IP list, but the container does not own that IP.
Fix:
Connection strategy:
EHLO hostname: mail.example.com
Source IPs: empty
Let Docker NAT the connection to the public VPS address.
Problem: IPv6 delivery fails
Error:
Network is unreachable
os error 101
Cause: the VPS has IPv6, but the Stalwart Docker network does not.
Fix:
MX route:
IP lookup strategy = v4Only
Configure IPv6 later only after all of these exist:
Docker IPv6 networking
An AAAA record
IPv6 PTR
IPv6 SPF authorization
Correct outbound routing
Problem: Port 25 times out from a home computer
Possible cause: the local internet provider blocks outbound port 25.
Confirm the server using:
Another VPS
A real inbound message
An external SMTP checker
Stalwart logs showing outside connections
Do not assume a residential port-25 test proves the VPS is blocked.
Problem: “No TLS certificates available”
This may appear before the file-backed certificate is loaded.
The authoritative test is:
openssl s_client \
-connect mail.example.com:465 \
-servername mail.example.com
If the correct trusted certificate is presented, SMTP TLS is functioning.
Problem: The RSA DKIM key appears split
Output such as:
"first portion" "second portion"
is normal TXT-record chunking.
It is still one logical DKIM value.