Limelight SMTP Setup Guide

This guide assumes you have completed all the steps in the Installing Limelight tutorial.

Setting up SMTP allows Limelight to send emails to users. This enables you to invite researchers to projects using their email, users to reset forgotten passwords and to receive notifications when their file uploads are complete. Setting up SMTP is not required to run Limelight, but these features will not be available.

1. Acquire SMTP Relay Server Information

This is, potentially the most complex part of enabling SMTP in Limelight. Acquiring SMTP relay server information means finding the host name, port, username, and password to use to send email through an email server. Below we present some options on how to locate or set up SMTP relay server information.

Check With Your Organization

The best place to begin this process is checking with your organization’s IT department or your internet service provider to see if this service is available to you. If it is, it would potentially look something like:

Hypothetical SMTP Relay Server Information

Host Name

smtp.organization.com

Port

587

Username

my_username

Password

my_password

SendGrid

SendGrid is a free service that allows applications like Limelight to send emails through their servers. The free tier allows you to send up to 100 emails per day. Here are the rough steps for setting up email sending capabilities:

  1. Go to https://sendgrid.com/.

  2. Create a free account

  3. Establish a single sender, which is an email address from which you will be allowed to send emails through SendGrid. SendGrid will require that you verify you can receive emails at this address. This does not give SendGrid access to your email. It only allows you to send email from this address using SendGrid’s servers. See SendGrid’s Guide for Single Sender Verification.

  4. Click on the Email API navigation option on the left and choose Integration Guide. Click on the SMTP Relay option that appears on the page.

  5. Follow the directions to acquire your SMTP relay server information.

Your SendGrid SMTP relay server information will look something like:

SendGrid SMTP Relay Server Information

Host Name

smtp.sendgrid.net

Port

587

Username

apikey

Password

YOUR_API_KEY

Google SMTP Relay

Google allows your Google Workspace account to use their servers as a SMTP relay. To enable this, follow Google’s Guide for setting up SMTP relay. In the Authentication section, you want to enable Require SMTP Authentication.

Your Google SMTP relay server information will look something like:

Google SMTP Relay Server Information

Host Name

smtp-relay.gmail.com

Port

587

Username

Google username

Password

Google password

Other Options

There are other service on the internet that provide SMTP relay server information. Any of them should work, so long as you have a host name, port, username, and password.

2. Update Your .env File

The .env file you set up during the Installing Limelight tutorial should contain the following lines (among others):

# Settings for setting up sending of emails by Limelight
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=smtp_username
SMTP_PASSWORD=smtp_password

Open this file using your favorite text editor. On Linux (including Docker on Windows), we’ll assume that is nano. To edit the file, type:

# ensure you are in correct directory. if you followed tutorial type:
cd ~/limelight

# edit the file
nano .env

Update these lines to reflect the SMTP relay server information from part 1. If you used SendGrid for your SMTP relay server, your information would be something close to:

SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USERNAME=apikey
SMTP_PASSWORD=your API KEY goes here

Type Control-o, <ENTER>, and Control-x to save and exit nano.

3. Update Email Address for Sender in Limelight

  1. Log into Limelight and click the ADMIN link in the top right. You must be logged in as an administrator user, such as the initial user created when you followed the Installing Limelight tutorial.

  2. Click the Manage Configuration link.

  3. Edit the field for From Address for emails sent. This is the email address from which emails sent by Limelight will appear to come. You may be restricted by what email address you can use here by the SMTP server you are using. For example, if you set up SMTP relay service with SendGrid, this email must match the verified sender you set up.

  4. Click the Save button to save the changes.

4. Restart Limelight

Limelight must be restarted to use the new configuration settings in the .env file. Type the following into your terminal to restart Limelight:

# ensure you are in correct directory. if you followed tutorial type:
cd ~/limelight

# shutdown Limelight
sudo docker-compose down

# startup Limelight
sudo docker-compose up --detach

5. Investigating Problems

If after following this guide, emails are not being sent, you can view the logs of the SMTP server by typing the following into a terminal:

sudo docker logs limelight-smtp

Carefully read this log and look for error messages, such as an authentication failure or other reasons the message may have been rejected.