GitLab is, at its core, a tool for centrally managing Git repositories. As one might expect form a platform that provides this service, GitLab provides a robust authentication and authorization mechanism, groups, issue tracking, wiki, and snippets, along with public, internal, and private repositories.
GitLab goes further by including a powerful continuous integration (CI) engine and a Docker container registry, allowing you to go from development to release inside of the same utility. It continues by adding two more powerful open source software utilities: Prometheus for monitoring, and Mattermost for team communication. The platform has a solid API and integrates with existing third-party systems like JIRA, Bugzilla, Pivotal, Slack, HipChat, Bamboo, and more.
All of this begs the question: why use GitLab instead of using SaaS services directly? The answer lies in personal taste. For most people, paying SaaS providers for the services that they provide is an excellent solution. You can focus on building your application and let them worry about maintaining the tools. What if you already have infrastructure with spare capacity? What if you just want private repositories without paying for that privilege? What if you did the math and determined that you can save money by hosting it yourself? What if you just want to own your own data?
Bringing services in-house opens you up to the risk of spending more time managing them and getting them to talk to each other, which is why GitLab truly shines as an option. With one click and a few minutes of configuration, you can be up and running with a complete solution.
The Rancher Catalog contains an entry for GitLab CE that will install the latest version. It assumes that you have a host where you want to directly open 80 and 443 for HTTP/HTTPS and where you’ll open a port to map to 22 inside of the container.
The catalog item sets the environment variable GITLAB_OMNIBUS_CONFIG with the values you provide. GitLab then incorporates these values into its configuration when it launches. For a very basic GitLab deployment the catalog item is sufficient, but I’d like to show you how to do a bit more…
For this tutorial, we’re going to deploy GitLab CE, but we’re not going to open any ports. Host ports are expensive, so we’ll use a load balancer for this later. We’ll configure HTTPS and the Docker Registry and wire it up for use with Rancher.
Before you launch, you have a couple of options for configuring GitLab:
Add all GitLab variables to GITLAB_OMNIBUS_CONFIG
Set all variables later
For the first time through, I recommend, option 2. The default gitlab.rb file that GitLab provides is well documented, and if you haven’t worked with GitLab before, you will learn a lot about its capabilities from going through that file.
Go ahead and click Launch. Rancher will fetch the images and bring them up for you.
Set Up SSL Offloading
While Rancher is fetching the images, let’s add a load balancer with HTTPS. To do this, we’ll first create a LetsEncrypt container, then add it to a load balancer and wait for the certificate to register. Once that completes, we’ll add the configuration for GitLab to the load balancer.
In this example, I’m going to use the domain “example.com” with the hostnames of “git” for GitLab, and “registry” for the Docker registry. Make sure you’ve added the corresponding records to your DNS zone file and pointed them to the host where the balancer will be running before continuing to the next step.
From the Rancher community catalog, choose the LetsEncrypt service. Accept the TOS in the first dropdown, then set the following options for HTTP validation:
Click Launch to launch the container. You now have 120 seconds to complete the next step.
Deploying the Load Balancer
In the gitlab stack, click the dropdown next to Add Service and choose Add Load Balancer. Give it a name and add the following services selectors. Alternatively, if you already have an environment-wide load balancer, edit it to add the services below.
Public / HTTP
Click Edit to save your changes.
Monitor the logs for the LetsEncrypt container and in two minutes you’ll see it report that it has registered the certificates for the two domains. If you see errors reporting status 403 or 503, check your load balancer configuration and make sure that it’s set up correctly. The LetsEncrypt container will restart and continue to try and register the certificates. Once the registration is successful, you’ll find the certificates in the Rancher UI under the Infrastructure tab.
We’re ready to add SSL support to GitLab via the load balancer:
Edit the load balancer
Add the following Service Rules:
Public / HTTP
Public / HTTPS
Public / HTTPS
Public / TCP
Click Edit to save your changes.
GitLab’s configuration is saved in /etc/gitlab/gitlab.rb within the container. When we launched the service, we created a Docker volume to store this data persistently. Within Rancher, find your Gitlab container and log into it with Execute Shell. Change to /etc/gitlab and edit gitlab.rb.
There are many variables within gitlab.rb that you can use to adjust how Gitlab behaves. Each section includes a link to Gitlab’s documentation that describes what that service does and what each variable adjusts.
For this tutorial, find and change or uncomment the following variables:
With these variables changed, you’ll have accomplished the following:
Set the hostname for your git URLs
Configured GitLab to bounce HTTP to HTTPS
Enabled HTTPS gravatar URLs for both HTTP and HTTPs (necessary to avoid mixed-content errors)
Set the reported SSH port to 2222
Activated emails from GitLab
Enabled email delivery through the Postfix sidekick
Activated the nightly backups with a one-week retention period
Enabled the Container Registry
Activated the configuration and required headers for GitLab to understand that it’s behind an SSL load balancer
Save this file, and reconfigure GitLab by typing gitlab-ctl reconfigure and pressing Enter. GitLab will rebuild its configuration files and restart services that need to be restarted.
You’re ready to go! Point your browser at https://git.example.com and you’ll be greeted with a screen that asks you to set a password. This is for the default user, named root, and once you’ve set the password, you’ll be asked to log in again.
Congratulations! You have a running GitLab instance!
There are still some changes that we need to make inside of GitLab to secure it, so keep reading.
Locking it Down
I recommend that you make all the following changes:
Change the Root Username
Logging into anything as root is bad, and that username is a known target. You’re logged in as the only user right now, and the first thing you should do is change your username.
Click the wrench icon in the top right, next to the search bar
Select Administrator in the bottom of the middle column
Select the Edit button in the top right
Change your name, username, and email address
Scroll down and click Save Changes
The Administrator account’s old email address was [email protected], and changing this information just tried to send an email to that account to inform it of the change. I’m sure the people who own example.com are thrilled with the amount of email they get.
Back in Rancher, find your postfix container and Execute Shell
Type mailq and press Enter. You should see a deferred message stuck in the queue. Note its ID
Type postsuper –d <id> and press Enter. This will delete that message from the queue.
Disable Public Sign-up
This next change will keep the Internet from taking over your new Gitlab instance and using it for their nefarious ends.
Click the wrench icon again to return to the Admin dashboard
Click the dropdown next to the gear icon in the top right and choose Settings
You can adjust any of these to suit your needs, but the one you want to disable is the default of Sign-up enabled under Sign-up Restrictions.
Check your ports
In this example we’re using ports 80, 443, and 2222. No other ports on the host are necessary for Gitlab, but 2222 is not a common port. Make sure that you have this open in your firewall.
At this point you have an awesome GitLab installation. You can immediately start using it for your projects. Go crazy! There’s so much to do inside of GitLab.
Add your SSH Key
Although you can work with Gitlab over HTTPS, doing so over SSH is more common. Before you can do this, you need to add your SSH public key to Gitlab so that it knows who you are. If you don’t have an SSH key you can make one (on Linux or Mac) with:
ssh-keygen -b 2048
Always use a passphrase for security – your key might have permission to log in as a privileged user, and if your laptop is ever compromised, you don’t want to give an attacker that level of access. (If you prefer not to use a passphrase or deal with ssh agents, see the excellent Kryptonite project at https://krypt.co.)
Save this with the defaults (or choose a new key name), and then in GitLab:
Click the dropdown next to your avatar in the top right corner and select Settings followed by SSH Keys
Paste your public key (the contents of the file that ends in .pub) into the box on the page that open
Next week, we’ll publish part 2 of this series, where we’ll cover how to use GitLab CI Multi-Runner to build containers, and configuring a project to use GitLab’s container registry. We’ll also cover building containers via GitLab CI and deploying to Rancher. To part 2 >>