Gitlab technical install

Brief guide for installing Gitlab-ee and replacing nginx with an apache reverse-proxy. Plus a few tips on overcoming several issues ran into setting up Gitlab.

Following how-to is based off Ubuntu 16.04 server and an apache reverse-proxy setup like outlined here.

Installation

Installing is pretty straight forward. Follow this guide for your system.

I chose not to install postfix as I'll setup my own SMTP mail server after.

Services

Gitlab has several services that you'll likely call frequently during setup.

sudo gitlab-ctl stop
sudo gitlab-ctl start
sudo gitlab-ctl status
sudo gitlab-ctl restart
sudo gitlab-ctl reconfigure

Configuration file

Gitlab uses a configuration file for most the setup that you'll do during a server install. This file, for example is used to change ports that it will listen on, disable nginx (to use apache instead), and setup authentication with Atlassian Crowd:

/etc/gitlab/gitlab.rb

For example, since I run several applications on my server, the default Gitlab listening port of 8080 wouldn't work (since Jira was already listening on that port). I used the above file to change the listening port to something else.

Auto-boot

Gitlab is, by default, set to start on boot. You can toggle this by:

sudo systemctl disable gitlab-runsvdir.service
sudo systemctl enable gitlab-runsvdir.service

Using apache instead of nginx, and all over https

Changes to gitlab.rb to disable nginx

Open gitlab.rb

sudo nano /etc/gitlab/gitlab.rb

and make the following changes

...
external_url 'https://gitlab.example.com'
...
################################################################################
## GitLab Workhorse
##! Docs: https://gitlab.com/gitlab-org/gitlab-workhorse/blob/master/README.md
################################################################################

# gitlab_workhorse['enable'] = true
# gitlab_workhorse['ha'] = false
gitlab_workhorse['listen_network'] = "tcp"
# gitlab_workhorse['listen_umask'] = 000
gitlab_workhorse['listen_addr'] = "127.0.0.1:9000"
gitlab_workhorse['auth_backend'] = "http://127.0.0.1:9080"
...
gitlab_workhorse['auth_socket'] = "/var/opt/gitlab/gitlab-rails/sockets/gitlab.socket"
...
unicorn['port'] = 9080
unicorn['socket'] = '/var/opt/gitlab/gitlab-rails/sockets/gitlab.socket'
...
web_server['external_users'] = ['www-data']
...
nginx['enable'] = false

Note: the above examples assumes workhorse port (which you will apache reverse-proxy to) is 9000 and unicorn is 9080 (this is the port you set the workhorse['auth_backend'] to).

Now, we need to add apache (www-data) to the gitlab user group:

sudo usermod -G gitlab-www www-data

Now, save gitlab.rb and run reconfigure

sudo gitlab-ctl reconfigure

Apache setup

The biggest issue I had was getting this dang thing working with my apache reverse-proxy, and using https (with a 301 redirect if accessed via http).

First, add entries in a proxy.conf file for your gitlab subdomain. Gitlab is a bit different than my other applications and requires a bit of special attention in the virtual-host block of the proxy.conf file. See below for a working example:

/etc/apache2/sites-available/proxy-ssl-host.conf

<VirtualHost *:443>
    Servername gitlab.example.com

	ProxyRequests Off
    ProxyVia Off
    ProxyPreserveHost On

    <Location />
      # New authorization commands for apache 2.4 and up
      # http://httpd.apache.org/docs/2.4/upgrading.html#access

      # Location will override my default proxy defined blacklist. Need to specifically set blacklist here.
      <RequireAll>
          Require all granted
          Include <path/to/ipblacklist.conf> # if you have one
      </RequireAll>

      # For non-relative URL root
      ProxyPassReverse http://127.0.0.1:9000
      ProxyPassReverse https://gitlab.example.com/
    </Location>

    # apache equivalent of nginx try files
    # http://serverfault.com/questions/290784/what-is-apaches-equivalent-of-nginxs-try-files
    # http://stackoverflow.com/questions/10954516/apache2-proxypass-for-rails-app-gitlab
    RewriteEngine on
    RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
    RewriteRule .* http://127.0.0.1:9000%{REQUEST_URI} [P,QSA]
    RequestHeader set X_FORWARDED_PROTO 'https'

    # needed for downloading attachments
    DocumentRoot /opt/gitlab/embedded/service/gitlab-rails/public

    #Set up apache error documents, if back end goes down (i.e. 503 error) then a maintenance/deploy page is thrown up.
    ErrorDocument 404 /404.html
    ErrorDocument 422 /422.html
    ErrorDocument 500 /500.html
    ErrorDocument 503 /deploy.html

    LogFormat "%{X-Forwarded-For}i %l %u %t \"%r\" %>s %b" common_forwarded
    ErrorLog /var/log/apache2/gitlab-ssl_error.log
    CustomLog /var/log/apache2/gitlab-ssl_forwarded.log common_forwarded
    CustomLog /var/log/apache2/gitlab-ssl_access.log combined env=!dontlog
    CustomLog /var/log/apache2/gitlab-ssl.log combined


    SSLEngine On
    SSLCertificateFile <path/to/fullchain.pem>
    SSLCertificateKeyFile <path/to/privkey.pem>
    Include /etc/letsencrypt/options-ssl-apache.conf #if you use certbot-auto
</VirtualHost>

<VirtualHost *:80>
    ServerName gitlab.example.com
    Redirect Permanent / https://gitlab.example.com/
</VirtualHost>

Note1: where <path/to/fullchain.pem> and <path/to/privkey.pem> are the paths to your SSL certificate files.

Note2: You'll note that I <Location /> directive overrides any default apache configuration for <Proxy *> directives. If you've defined an ipblacklist (like here) you'll need to redefine it within this <Location /> directive.

Integrating with Altassian Crowd

I had a few issues implementing Gitlab with Crowd for authentication. Below are settings that finally worked:

Add omniauth_provider to /etc/gitlab/gitlab.rb

Add/modify the following to /etc/gitlab/gitlab.rb

Additions to /etc/gitlab/gitlab.rb

### OmniAuth Settings
###! Docs: https://docs.gitlab.com/ce/integration/omniauth.html
gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_allow_single_sign_on'] = true
# gitlab_rails['omniauth_sync_email_from_provider'] = 'saml'
# gitlab_rails['omniauth_sync_profile_from_provider'] = ['saml']
# gitlab_rails['omniauth_sync_profile_attributes'] = ['email']
# gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml'
gitlab_rails['omniauth_block_auto_created_users'] = true
# gitlab_rails['omniauth_auto_link_ldap_user'] = false
# gitlab_rails['omniauth_auto_link_saml_user'] = false
# gitlab_rails['omniauth_external_providers'] = ['twitter', 'google_oauth2']
# gitlab_rails['omniauth_providers'] = [
#   {
#     "name" => "google_oauth2",
#     "app_id" => "YOUR APP ID",
#     "app_secret" => "YOUR APP SECRET",
#     "args" => { "access_type" => "offline", "approval_prompt" => "" }
#   }
# ]

  gitlab_rails['omniauth_providers'] = [
    {
      "name" => "crowd",
      "args" => {
        "crowd_server_url" => "http://127.0.0.1:8095/crowd",
        "application_name" => "<CROWD-APP-NAME>",
        "application_password" => "<CROWD-APP-PASSWORD>"
      }
    }
  ]

Now save, exit and reconfigure

sudo gitlab-ctl reconfigure

Space shortcuts

Page tree