Sovrain
  1. Documentation
  2. Self-hosting

How-to guide

Configure outgoing mail

Connect Sovrain to your SMTP relay so that invitations, verification and password reset emails go out.

This guide connects a Sovrain node to an SMTP relay. Sovrain sends all its emails, such as invitations, email verification and password resets, as plain text through this one relay. The prod profile does not start without it.

Before you start

You need an account at an SMTP relay that:

  • requires a user name and password. Sovrain always logs in and cannot send through a relay without authentication;
  • accepts implicit TLS (SMTPS), usually on port 465. Sovrain does not support STARTTLS, so a relay that offers only port 587 with STARTTLS does not work;
  • lets that account send from the address you want as the sender.

Connect the relay

  1. Add the relay to the node’s environment file:

    IDP_SMTP_HOST=smtp.example.com
    IDP_SMTP_USERNAME=sovrain@example.com
    IDP_SMTP_PASSWORD=<relay password>
    

    The port defaults to 465 and implicit TLS is on. If your relay uses implicit TLS on another port, add IDP_SMTP_PORT=<port>.

  2. Choose the sender. By default the From address is IDP_SMTP_USERNAME, because some relays refuse any other sender. To use another address, add it, and make sure the relay lets your account send as it:

    IDP_MAIL_FROM=no-reply@example.com
    
  3. Set up SPF, DKIM and DMARC for the sender’s domain as your relay describes, so that the emails are not marked as spam.

  4. Recreate the container so it reads the new environment file: docker stop --time 60 sovrain && docker rm sovrain, then run the same docker run command as in Run Sovrain with Docker. docker restart keeps the old values.

  5. Send yourself an email: sign in to an organization, open your profile and add or change your email address, then watch the log:

    docker logs -f sovrain 2>&1 | grep -i mail
    

    A line with Mail sent means the relay accepted it. Mail delivery failed gives the relay’s reason.

If you want plain SMTP

IDP_SMTP_SSL=false turns encryption off completely: Sovrain then talks plain SMTP without STARTTLS, and the password and every email cross the network unencrypted. Use it only for a relay on the same host or on a private network you trust. The relay must still offer AUTH PLAIN or AUTH LOGIN on the plain connection, because Sovrain always signs in. Inside the container localhost is the container itself, not the server.

IDP_SMTP_SSL=false
IDP_SMTP_PORT=25

If an email does not arrive

Look for its line in the log. Mail delivery failed gives the relay’s reason. A failed email does not undo the action that caused it: an invitation, for example, is still created, and the admin can send it again once the relay works. After the relay could not be reached, emails fail at once for 30 seconds, so wait that long before you try again.

Timeouts and the pause: Mail. Which emails Sovrain sends, to which addresses and how many an hour: Emails.