Set up mail
On this page
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.
Before you start
Section titled "Before you start"- You need to be an admin: a member of an approving group,
shipboard-adminson 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.
Fill in the mail settings
Section titled "Fill in the mail settings"- In the portal, open Mail, under Platform.
- 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.
- Server: the mail server's address, such as
- 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.
Set the mail server's password
Section titled "Set the mail server's password"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.
On the Mail page
Section titled "On the Mail page"Once the settings have a user name, the page has Set the mail server's password:
- Type the password under New password.
- 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.
On the server
Section titled "On the server"Someone with root can set it from the server's command line instead. The local admin account has to use this way.
sudo moorhold mail passwordIt 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.
Send a test email
Section titled "Send a test email"Once the settings are saved, Send a test email sends one email with them:
- Under Send a test email, type an address under Send it to.
- 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."
Remove the mail settings
Section titled "Remove the mail settings"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.
If something goes wrong
Section titled "If something goes wrong"- "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-passwordand 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.