GitLab CE with HTTPS Using Docker

15. January 2017 Docker 0

Introduction

Lately you could say that I’ve been going all out on Docker. I recently built a new server which runs Ubuntu with Docker and Docker Compose installed doing some heavy lifting for me. It makes perfect sense for my given situation which involves navigating several tools I’m leveraging to build software.

For those who are unfamiliar with Docker, it’s an amazing tool that takes virtualization to the next level using containers. It’s very resource efficient and easy to use (after a little learning). Best of all, it runs on Windows, Mac, and Linux. This software is so amazing that many companies (including the one I work for) are adopting it as part of their overall IT strategy; it’s great for Dev Ops.

Due to my recent embrace of Docker, I had the need to transition from TFS (Team Foundation Server) to GitLab CE since the latter plays nice on Linux. Granted, that’s not to say that TFS isn’t a good piece of software (it’s awesome and can stand on its own) but my investment in Docker required something Linux friendly.

Using GitLab CE with Docker

It’s easy to find a starting point for using GitLab CE with Docker. The official Docker image for it is awesome. However, what wasn’t so straight forward was setting up HTTPS using a self-signed certificate or setting up some common configuration options such as SMTP for email notifications, backup frequency, etc.

If you are wanting to get GitLab CE up and running on Docker with HTTPS using a self-signed certificate, then this article is for you. I’ve done all the heavy lifting for you and shared the work on this GitHub repository. Just follow the instructions found there and you should be good to go.

Diving into the README.md

I spent some time creating the README.md which is included with the GitHub repository. This section will list that file in its entirety (as of version 1.0.1). It provides all the relevant information needed to understand how it works and the benefits provided.

README.md

GitLab CE with HTTPS on Docker

This repository contains custom Docker files for GitLab CE. Everything is setup to run on HTTPS using a self-signed certificate (this needs to be created) and includes commonly used features specified as environment variables in the included Docker Compose file.

Be sure to see the change log if interested in tracking changes leading to the current release.

Getting Started

  1. Ensure Docker Compose is installed along with Docker Engine.
  2. Clone this repository into the desired location.
  3. Modify the GitLab CE settings to meet the needs of the particular context. These settings are found in the docker-compose.yml file. Information on these settings are found below.
  4. Generate a self-signed certificate to use with the GitLab CE instance.
  5. Run the following command (geared toward Linux):MARKDOWN_HASH48d64b2ef14fa03f06a2279f42fb321aMARKDOWN_HASH

Please read the rest of the content found within in order to understand additional configuration options.

Settings Specified in Docker Compose File

Below is a list of the settings that are specified in docker-compose.yml. Some of these settings will need to be changed in order to meet specific goals. Additional settings can be added here or existing settings removed. For more information on available configuration options, go here. In addition, for more information on the logrotate settings, go here.

  1. external_url – This is the URL used to access the GitLab CE instance externally. Links in emails will use this URL along with certain uploaded assets (e.g. images specified for groups, etc.). Be sure to specify the port used externally to access the GitLab CE instance from Docker (e.g. port 9150 which maps to the internal Docker port of 443).
  2. gitlab_rails[‘time_zone’] – Specifies the desired timezone in order for the correct time to show up in the logs, amongst other things.
  3. gitlab_rails[‘smtp_enable’] – Enables SMTP so emails can be sent out on certain events (e.g. new user registrations, etc.).
  4. gitlab_rails[‘smtp_address’] – The SMTP server address used for sending emails.
  5. gitlab_rails[‘smtp_port’] – The port used for SMTP (e.g. port 587 for TLS to ensure emails are sent securely).
  6. gitlab_rails[‘smtp_user_name’] – The username used for sending emails via SMTP (e.g. user@example.com).
  7. gitlab_rails[‘smtp_password’] – The password used for the SMTP email account.
  8. gitlab_rails[‘smtp_domain’] – The domain used for sending emails via SMTP (e.g. example.com).
  9. gitlab_rails[‘smtp_authentication’] – Specifies the SMTP authentication mode.
  10. gitlab_rails[‘smtp_enable_starttls_auto’] – Enables TLS to ensure the transfer of secure email messages.
  11. gitlab_rails[‘gitlab_email_from’] – Specifies the from email address shown in the sent email.
  12. gitlab_rails[‘backup_keep_time’] – Specifies how long in seconds to keep each backup (e.g. 14515200 for roughly 6 months).
  13. logging[‘logrotate_frequency’] and nginx[‘logrotate_frequency’] – Specifies how often logs should be rotated for GitLab CE or NGINX (e.g. daily, weekly, etc.).
  14. logging[‘logrotate_rotate’] and nginx[‘logrotate_rotate’] – Specifies the the value used by the frequency setting above (e.g. if frequency is weekly and rotate interval is set to 7, logs will rotate every 7 weeks) for GitLab CE or NGINX.
  15. logging[‘logrotate_compress’] and nginx[‘logrotate_compress’] – Specifies whether logs should be compressed when rotated for GitLab CE or NGINX.
  16. logging[‘logrotate_method’] and nginx[‘logrotate_method’] – Specifies the method used when logs are rotated (e.g. copytruncate) for GitLab CE or NGINX.
  17. logging[‘logrotate_delaycompress’] and nginx[‘logrotate_delaycompress’] – Specifies whether compression should be delayed when rotating logs for GitLab CE or NGINX.
  18. nginx[‘listen_port’] – Specifies the port (e.g. port 443 used internally by container) used to force NGINX to listen on. This should be specified if supplying a port to the external_url setting. This is because if a port is detected in the external URL, GitLab CE will instruct NGINX to listen on that port unless specifying this setting which acts as an override.
  19. nginx[‘redirect_http_to_https’] – Redirects HTTP requests to HTTPS, preventing the use of insecure communications.
  20. nginx[‘ssl_certificate’] – Specifies which SSL certificate to use via a file path. This is an internal container path.
  21. nginx[‘ssl_certificate_key’] – Specifies which SSL certificate key to use via a file path. This is an internal container path.

Generating a Self-Signed Certificate

In order to generate a self-signed certificate (using OpenSSL) to secure all HTTP traffic, follow these instructions (geared toward Linux).

  1. Run the command MARKDOWN_HASH901a31c32ff8e5038e1f01f4941d79d0MARKDOWN_HASH which will generate a secure server key.
  2. Run the command MARKDOWN_HASH99e669afeb2f82d4e3dcb284cd8cd2c9MARKDOWN_HASH which will generate the certificate signing request.
  3. The above command will request input in the following areas shown below.

    It’s important that for Common Name (e.g. server FQDN or YOUR name) to enter the URL that GitLab CE will use (e.g. the value specified for external URL in docker-compose.yml without the port).

  4. Run the command MARKDOWN_HASHb0f5c7582a19a115bc8b139e6bc18ac0MARKDOWN_HASH to create the signed certificate. The certificate will be valid for one year unless the value used for days is different.
  5. Copy both server.crt and server.key into MARKDOWN_HASH9aed7e7218fd3febdf92e9393d960d67MARKDOWN_HASH (part of this repository) and overwrite the dummy files. These files will be copied into the container and used to secure the GitLab CE instance.
  6. Delete the leftover certificate signing request file: MARKDOWN_HASH03651b764697f1adfb2970f508e2c32fMARKDOWN_HASH.

Container Network

The network specified (can be changed to the desired value) by this Docker container is named MARKDOWN_HASH759b74ce43947f5f4c91aeddc3e5bad3MARKDOWN_HASH. It is assumed that this network has already been created prior to using the included Docker Compose file. The reason for this is to avoid generating a default network so that other Docker containers can access the GitLab CE instance (e.g. Jenkins for CICD, etc.) using the Docker embedded DNS server.

If no network has been created, run the following Docker command (geared toward Linux): MARKDOWN_HASHdf4eaaed7eb896804642d08149975b84MARKDOWN_HASH. Be sure to replace network-name with the name of the desired network. For more information on this command, go here.

Port Mapping

The external ports used to map to the internal ports that GitLab CE uses are 9150 (maps to 443 for HTTPS) and 9151 (maps to 22 for SSH). These ports can certainly be changed but please be mindful of the effects. Changing the port mapped to HTTPS will require changing it on the external_url setting found in the Docker Compose file.

However, if the external port for HTTPS is set to the same port used internally (e.g. 443), then the port can be omitted from the external_url setting and the nginx[‘listen_port’] setting can be omitted as it will no longer be required.

Data Volumes

It is possible to change the data volume folders mapped to the container to something other than MARKDOWN_HASH57cb06f64cc81a7bcc2bb1124c00df18MARKDOWN_HASH if desired. It is recommended to choose a naming scheme that is easy to recognize.

Configuring Git to Work with a Self-Signed Certificate

For Git to work with a self-signed certificate, a few configuration options need to be specified. There are two ways to do this explained here and one may be better suited to the given situation than the other. Read through the options and pick the best one for the given circumstances.

Option 1 – Modify the Global Git Configuration

To configure Git to always use the self-signed certificate for all HTTPS transactions, modify the Git configuration (global .gitconfig file) and add the following (geared toward Windows). This file is usually found at MARKDOWN_HASH25764fbb76f43ead3fd2852674aef070MARKDOWN_HASH and be sure to replace the user folder MARKDOWN_HASH39ce7e2a8573b41ce73b5ba41617f8f7MARKDOWN_HASH with the correct one suited to the given context.

This assumes the certificate has been copied into a different directory (e.g. c:\Users\jsmith\certificates) and then referenced in the global Git configuration file. This directory can be changed to something else if desired.

Option 2 – Specify the Self-Signed Certificate Upon Git Clone Operation

This option, while being more manual in nature, specifies the self-signed certificate to use when performing a Git Clone operation. Once the repository has been cloned, additional transactions made against it will use this certificate. One benefit to this approach is having the ability to interact with other repositories that do not use a self-signed certificate (e.g. public GitHub repos). For most people, this will be the best option.

Run the following command to clone a repository and specify the self-signed certificate to use for it (geared toward Windows):

MARKDOWN_HASH5101bcfb3921e0202c7d7e32ce62396cMARKDOWN_HASH

Please see Option 1 above for more details on the path used with this command. This path will be different depending upon the context.

Further Reading

For information making this change on platforms other than Windows or for extra details, please go here.

Conclusion

Getting GitLab CE working with HTTPS using a self-signed certificate isn’t always a straight forward process. Certainly there are a few examples that exist in the wild but I could never find anything that worked perfectly for me. This is why I created my own and shared it with the world. My hope is you find this useful for your current needs. Feel free to ask any questions or submit pull requests to improve what I’ve shared and good luck with your future endeavors.

Daniel Eagle

Currently residing in the Austin area, Daniel Eagle is an avid gamer, writer, technology/science enthusiast, software developer, and educator. He takes great pride in spreading knowledge and helping others.

More Posts - Website

Follow Me:
TwitterLinkedInYouTube