This is the first part in a series of system administration and management posts.

It used to be that if you wanted to run your own SCM system or VCS, you needed years of experience and a grey beard. However much has changed in the past few years.

We at OpenConcept switched from bare Git to GitLab about a year ago. The driving factor behind our change was to simplify the management of repositories and give our clients the option to gain direct access to them. We also picked up a bunch of useful functionality at the same time; things like pull requests, issue links, and teams.

If you don’t know about GitLab, it is a Git server system. It includes the components to host repositories, as well as a web interface and a ton of sugar. It implements permissions on top of Git, which allows us to restrict our clients’ access to only the repositories that concern them.

It used to be that you had to install a good number of packages and configure them in a specific way for GitLab to work. However, they recently started using a technology called omnibus. Omnibus allows the software to be packaged with all of its dependencies and provides a bit of tooling to ensure that it gets configured flawlessly. In their case, the tooling consists of a few scripts and a bunch of Chef recipes. Think of it as containerization, minus the containers.

To install, we just need to download the appropriate package to the server (as our servers are Ubuntu installs, we chose the .deb file) and run the command to install it. Now before we do just that, we’re going to setup mandrill (we use mandrill, but SES or any other transactional-mail-as-a-service provider with an SMTP endpoint would work).

First up, sign up for an account at mandrill.com. The great thing is that Mandrill doesn’t require any credit card details until you bust through the free tier-limit, and even then, it will simply stop sending your emails until you pay or the month finishes. Once that is done, navigate to the “Settings” section and, in the first tab, setup an API key. It’ll be used as the SMTP password, so keep it secret! Once you have that, switch to the domains tab and add all the domains you wish to send mail from. Mandrill will refuse to attempt delivery of any mail sent from an address whose domain is not in the list of domains on your account, so don’t skip this step. You are not required to actually verify your access to the domain or setup DKIM and SPF. However, verification prevents people without access to the domain from adding it to their account (once the domain has been verified using one account, any other account that wants to add the domain needs to verify that the user has access to it), DKIM and SPF allows recipients to authenticate that you really sent that email, so I strongly recommend that you do verify and setup DKIM/SPF.

After you’ve configured your SMTP service, get back to the server. Next, create a text file, gitlab.rb, in /etc/gitlab. Edit the file and mirror the content displayed here. If your SMTP provider has different values for some of the settings, use those instead.

# SMTP settings
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = 'smtp.mandrillapp.com'
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = 'ACCOUNT USERNAME'
gitlab_rails['smtp_password'] = 'API KEY'
gitlab_rails['smtp_domain'] = 'YOUR DOMAIN'
gitlab_rails['smtp_authentication'] = 'login'
gitlab_rails['smtp_enable_starttls_auto'] = true

You can also customize the email address used to send the message with the gitlab_email_from setting:

# Email settings
gitlab_rails['gitlab_email_from'] = 'git@YOUR DOMAIN'

There are many other settings that you can specify in this configuration file, including some undocumented ones, but the scheme is properly explained in the omnibus-gitlab repository.

Once you’ve finished editing the configuration file, simply download the package (https://about.gitlab.com/downloads/) and run the install. You don’t need to install postfix or any other mail gateway.

After installation, run sudo gitlab-ctl reconfigure. It will take your configuration from /etc/gitlab/gitlab.rb, use it to generate the configuration files for the various components of gitlab, and initialize them with the correct parameters.

Congratulations, you've just installed GitLab and setup Mandrill as your SMTP gateway!