James Walker

James Walker

Web Developer

How to set up GitLab with an existing Apache web server

Published on Sunday July 9 2017 at 10:08 in Programming

GitLab is the most popular self-hosted Git server, offering everything you need to run your own web interface into your repositories. When you install GitLab, it includes a bundled Nginx web server that works out of the box. If you already have an Apache server configured on the machine, you'll need to customise GitLab to disable Nginx and route requests through an Apache reverse proxy instead. This tutorial details the changes you'll need to make.


For the remainder of this tutorial, the following assumptions are made:

Step 1 – Disable GitLab's Nginx web server

Open GitLab's configuration file at /etc/gitlab/gitlab.rb. Find the following configuration keys and change their values to those shown. Remember to substitute in your own hostname and port for external_url!

external_url 'http://gitlab:9000'
nginx['enable'] = false
web_server['external_users'] = ['www-data']

#Change GitLab workhorse settings to listen on 8181 instead of 8180
#Not required but recommended if listening on a non-standard Apache port
#If you use a different workhorse port, remember to use it in the following sections too!
gitlab_workhorse['listen_network'] = 'tcp'
gitlab_workhorse['listen_addr'] = ''

Step 2 – Set up your GitLab site in Apache

Create a new VirtualHost in /etc/apache2/sites-available as gitlab.conf. Add the following lines. Note the Listen directive won't be required if you're using a standard port.

Listen 9000

#VirtualHost declaration
ServerName gitlab
ServerSignature off

#Enable reverse proxy (to route to GitLab)
#You can change timeout if required
ProxyPreserveHost On
ProxyTimeout 300
AllowEncodedSlashes NoDecode

#Set up the DocumentRoot, proxy pass to GitLab

Require all granted

ProxyPassReverse http://gitlab/

#RewriteRule - direct all requests to GitLab, via proxy
RewriteEngine On
RewriteRule .*{REQUEST_URI} [P,QSA]

#Enable attachment downloads
DocumentRoot /opt/gitlab/embedded/service/gitlab-rails/public

#Register static error pages - in the event the GitLab backend goes down, Apache can still serve these
ErrorDocument 404 /404.html
ErrorDocument 422 /422.html
ErrorDocument 500 /500.html
ErrorDocument 502 /502.html
ErrorDocument 503 /503.html

#Set up GitLab logs in /var/log/apache2/gitlab/
LogFormat "%{X-Forwarded-For}i %l %u %t \"%r\" %>s %b" common_forwarded
ErrorLog /var/log/apache2/gitlab/gitlab_error.log
CustomLog /var/log/apache2/gitlab/gitlab_forwarded.log common_forwarded
CustomLog /var/log/apache2/gitlab/gitlab_access.log combined env=!dontlog
CustomLog /var/log/apache2/gitlab/gitlab.log combined


Step 3 – Configure and enable the new setup!

Add the Apache www-data user to GitLab's user group:

sudo useradd -G gitlab-www www-data

Enable Apache modules, if not already:

sudo a2enmod proxy
sudo a2enmod proxy_http

Reconfigure GitLab:

sudo gitlab-ctl reconfigure

Enable the Apache site:

sudo a2ensite gitlab
sudo service apache2 restart

Your Apache-powered GitLab site is now ready to use!

More information

For more information, or troubleshooting steps, please refer to the sample Apache documentation in the GitLab Omnibus docs.