Dockerized Gitlab - Configure SMTP

Related Posts

• GitLab Documentation Index

Steps

Use the following command to edit your gitlab configuration file from within the container:

sudo docker exec -it gitlab vi /etc/gitlab/gitlab.rb

If your container isn't running or you cant run it, you can use sudo vim gitlab/config/gitlab.rb.

You will find a commented out section as shown below:

...
################################
# GitLab email server settings #
################################
# see https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/settings/smtp.md#smtp-settings
# Use smtp instead of sendmail/postfix.

# gitlab_rails['smtp_enable'] = true
# gitlab_rails['smtp_address'] = "smtp.server"
# gitlab_rails['smtp_port'] = 465
# gitlab_rails['smtp_user_name'] = "smtp user"
# gitlab_rails['smtp_password'] = "smtp password"
# gitlab_rails['smtp_domain'] = "example.com"
# gitlab_rails['smtp_authentication'] = "login"
# gitlab_rails['smtp_enable_starttls_auto'] = true
# gitlab_rails['smtp_tls'] = false
# gitlab_rails['smtp_openssl_verify_mode'] = 'none' # Can be: 'none', 'peer', 'client_once', 'fail_if_no_peer_cert', see http://api.rubyonrails.org/classes/ActionMailer/Base.html
# gitlab_rails['smtp_ca_path'] = "/etc/ssl/certs"
# gitlab_rails['smtp_ca_file'] = "/etc/ssl/certs/ca-certificates.crt"

...

Uncomment them and fill in the values.

Examples For Different Providers

You might find it easier just to copy/paste in from the online examples. I found that when configuring it for AWS SES, I needed to just paste in the following:

SES

For AWS SES, you want the following:

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "email-smtp.eu-west-1.amazonaws.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "XXXXXXXXXXXXXXX"
gitlab_rails['smtp_password'] = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
gitlab_rails['smtp_domain'] = "email-smtp.eu-west-1.amazonaws.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true

# If your SMTP server does not like the default 'From: gitlab@localhost' you
# can change the 'From' with this setting.
gitlab_rails['gitlab_email_from'] = 'support@mycompanydomain.org'
gitlab_rails['gitlab_email_reply_to'] = 'noreply@mycompanydomain.org'

Gmail

For gmail, you want to create an app specific password and use it in the chunk below:

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.gmail.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "xxxxxxxx@gmail.com"
gitlab_rails['smtp_password'] = "xxxxxxxxxxxxxxxxx"
gitlab_rails['smtp_domain'] = "smtp.gmail.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_tls'] = false
gitlab_rails['smtp_pool'] = false

SendGrid

For sengrid, you want create an API key that can send emails:

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.sendgrid.net"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "apikey"
gitlab_rails['smtp_password'] = "SG.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
gitlab_rails['smtp_domain'] = "your-domain.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_tls'] = false
gitlab_rails['smtp_pool'] = false

Mailcow

For mailcow, you want to create an app specific password and use it in the chunk below:

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "mail.mydomain.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "gitlab@mydomain.com"
gitlab_rails['smtp_password'] = "xxxxxxxxxxxxxxxxx"
gitlab_rails['smtp_domain'] = "mail.mydomain.com"
gitlab_rails['smtp_authentication'] = "plain"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_tls'] = false
gitlab_rails['smtp_openssl_verify_mode'] = 'peer'

This is assuming your mailcow server was set up at mail.mydomain.com, and that you created an inbox with username "gitlab" on the domain "mydomain.com" to create the inbox "gitlab@mydomain.com". Adjust these values according to whatever your domain actually is.

The mailcow documentation states to use the "plain" password setting as the authentication mechanism. Contrary to what the name implies, the password will not be transferred to the server in plain text as no authentication is allowed to take place without TLS.

I also found that I had to configure extra email settings to not be their defaults.

Extra Email Settings

For getting mailcow to work, I also found that I had to manually uncomment and set the following settings:

gitlab_rails['gitlab_email_enabled'] = true
gitlab_rails['gitlab_email_from'] = 'gitlab@mydomain.com'
gitlab_rails['gitlab_email_display_name'] = 'noreply'
gitlab_rails['gitlab_email_reply_to'] = 'gitlab@mydomain.com'

Without this, my mailcow server was complaining that Gitlab was trying to send as a different user/domain for some reason.

Restart the Container

Now restart the docker container and gitlab will reconfigure iteself

The instructions say to use:

docker restart gitlab

However I found that I had to basically stop/remove and then use my start-gitlab script.

References

• GitLab Docs - Docker images
• GitLab Docs - SMTP settings