Moorhold docs

Your server can send email through a mail server you choose, such as your email provider's SMTP service. Moorhold gives the settings to Keycloak, which sends the emails. You set them on the portal's Mail page.

  • You need to be an admin: a member of an approving group, shipboard-admins on a new server. Other members can open the Mail page, but it says "Only admins can change the mail settings."
  • Sign in with your own account. The local admin account can read the page but can't change it.
  • Have your mail server's details: its address and port, the security it uses, the address to send from, and a user name and password if it asks for one.
  1. In the portal, open Mail, under Platform.
  2. Under Mail server, fill in:
    • Server: the mail server's address, such as smtp.example.com.
    • Port: the port it gave you.
    • Connection security: STARTTLS, the usual choice, most often on port 587; TLS from the start, most often on port 465; or None, only for a relay on your own network that asks for no user name.
    • Send from: the address emails come from.
    • Sender name: shown with that address.
    • User name: leave it empty if the server asks for none.
    • Password reference: file:///run/secrets/smtp-password. Choose Use the server's password to fill it in. Leave it empty if the server asks for no user name.
  3. Choose Save.

The page asks you to sign in again before it saves, unless you signed in in the last few minutes, because these settings decide where Moorhold's emails go. It keeps what you typed while you sign in, and then says: "You've signed in again. Your changes aren't saved: check them, then choose Save."

Once saved, the page says: "Saved. Keycloak gets them the next time Moorhold updates the tools."

The Password reference takes only file:///run/secrets/smtp-password, or another file in the same folder whose name starts smtp-. It never takes the password itself.

Moorhold keeps the password on the server, where only root and Moorhold's own services can read it. The Mail page never shows it. Under The mail server's password, the page says whether it's set.

Once the settings have a user name, the page has Set the mail server's password:

  1. Type the password under New password.
  2. Choose Set the password. If you last signed in more than a few minutes ago, the page asks you to sign in again first, and you type the password after that.

Setting it restarts the portal and the part of Moorhold that updates the tools, so the portal is unavailable for a moment. Reload the page when it's back. It then says "The server set the password on" and the time.

If the server doesn't pick the password up within 15 minutes, it deletes it unread, and the page asks you to type it again. On a server that can't take the password from the portal, the page gives the command below instead.

Someone with root can set it from the server's command line instead. The local admin account has to use this way.

Terminal window
sudo moorhold mail password

It asks for the password twice without showing it, then says where it kept the password and which services it restarted to read it. The portal is unavailable until the command finishes.

Once the settings are saved, Send a test email sends one email with them:

  1. Under Send a test email, type an address under Send it to.
  2. Choose Send a test email.

If the settings change after a test, the page says "The settings changed after the last test email. Send another to check them."

Under Remove the mail settings, choose Remove the mail settings. Keycloak loses them too, and the server can't send email until someone saves new ones.

  • "The password isn't set on this server, so Moorhold can't sign in to your mail server." Set it on the page or with sudo moorhold mail password.
  • "These settings don't use the password set on the server." The Password reference names another file. Choose Use the server's password, then Save.
  • "Moorhold isn't using the saved mail settings." The settings were saved with a password reference Moorhold no longer takes. Enter them again with file:///run/secrets/smtp-password and save.
  • "The two passwords don't match, so nothing changed. Run it again." You typed two different passwords at sudo moorhold mail password.
  • "Setting the mail password needs root." Run the command with sudo.