For versions of GitLab 8.2, check the 8-2-stable branch. For versions of GitLab 8.0 and 8.1, check the 8-1-stable branch. For versions of GitLab older than 8.0, check the apache-old branch.

Installations from source

If you are using Apache version 2.4 or above, please use files gitlab-apache24.conf or gitlab-ssl-apache24.conf for the HTTP and HTTPS versions of the vhost repectively.

If you are using Apache version 2.2, please use files gitlab-apache22.conf or gitlab-ssl-apache22.conf for the HTTP and HTTPS versions of the vhost repectively.

To allow gitlab-workhorse to listen on port 8181, edit or create /etc/default/gitlab and change or add the following:

gitlab_workhorse_options="-listenUmask 0 -listenNetwork tcp -listenAddr 127.0.0.1:8181 -authBackend http://127.0.0.1:8080"

Installations unsing the Omnibus packages

Omnibus packages use their own bundled Nginx server. If you want to use your own external Apache server, follow the steps to configure GitLab.

In the last step you will need to download the config from this repository.

RHEL6/CentOS6 recommendations

Most of the settings below were tested on CentOS 6, but are probably applicable to other distributions as well.

Puma or unicorn?

unicorn

By default, Unicorn (i.e. unicorn.rb) is configured to listen on port 8080 in GitLab's documentation. Therefore, the Apache configuration files do that by default.

puma

Info taken from PR #87.

As apache's mod_proxy doesn't support sockets, the proxy URL must be configured to use tcp instead of unix sockets. /home/git/gitlab/config/puma.rb should exist and be configured. Two changes must then be made:

In the Apache conf replace http://127.0.0.1:8080 with http://0.0.0.0:9292. Also replace ProxyPassreverse http://gitlab.example.com:9292
Edit puma.rb: comment out bind 'tcp://0.0.0.0:9292' and comment bind "unix://#{application_path}/tmp/sockets/gitlab.socket"

Assumptions

It is assumed GitLab will be running in a secure production environment. This Apache httpd configuration is hardened for that purpose. By default this configuration only allows strong SSL and HTTP is redirected to HTTPS. If self signed certificates are preferred then see below in this document on managing SSL certificates. Also see additional security recommendations located at the bottom of this document for httpd. Managing GitLab with plain text HTTP only is not recommended however the config files have been provided for that purpose.

Encryption assumptions

Only security ciphers TLSv1.0+ and SSLv3+ are used in Apache ssl configs. Only strong ciphers 128-bit or higher. Ciphers with known weaknesses (i.e. MD5 hashed and RC4 based ciphers) have been purposefully excluded.

Run GitLab insecure with HTTP only

Utilize the configs without ssl in their names to run GitLab without https. Running a production GitLab instance over plain text HTTP is NOT recommended.

Customize gitlab-ssl-*.conf

There are a few places where the Apache configs need to be customized for the GitLab installation.

ServerName is defined in two VirtualHosts. ServerName should be set to host name of the GitLab installation.
SSLCertificateFile, SSLCertificateKeyFile, and SSLCACertificateFile should be customized for signed certificates.
ProxyPassReverse http://gitlab.example.com:8080 should be customized for public host name of the GitLab installation.
At the bottom of gitlab-ssl.conf log file names contain gitlab.example.com. The log file names should reflect the GitLab installation host name.

A quicker method is to use sed to modify the file.

sed -i 's/gitlab.example.com/yourhost.com/g' gitlab-ssl-*.conf

Even with the quicker method SSLCertificateFile, SSLCertificateKeyFile, and SSLCACertificateFile should still be modified.

SELinux modifications

In a RHEL6 production environment it is assumed SELinux is enabled. SELinux must be configured with the following:

setsebool -P httpd_can_network_connect on
setsebool -P httpd_can_network_relay on
setsebool -P httpd_read_user_content on
semanage -i - <<EOF
fcontext -a -t user_home_dir_t '/home/git(/.*)?'
fcontext -a -t ssh_home_t '/home/git/.ssh(/.*)?'
fcontext -a -t httpd_sys_content_t '/home/git/gitlab/public(/.*)?'
fcontext -a -t httpd_sys_content_t '/home/git/repositories(/.*)?'
EOF
restorecon -R /home/git

Note: semanage is part of the policycoreutils-python package.

Other httpd security considerations

In /etc/httpd/conf/httpd.conf it is recommended to add/modify the following values. For more information see ServerTokens, ServerSignature and TraceEnable.

ServerTokens Prod
ServerSignature Off
TraceEnable Off

ServerTokens and ServerSignature prevent the Apache httpd version being broadcast in HTTP RESPONSE headers. TraceEnable disables HTTP tracing which is a HTTP debugging feature and is commonly used in cross-site scripting (XSS) attacks.

There is a vulnerability in compression over SSL and the exploit is called CRIME. To mitigate this vulnerability it is recommended to disable compression in httpd. In RHEL Apache httpd 2.2.15 (official release), mod_ssl enables compression over SSL by default. The only way to mitigate that is by implementing an RHN solution. Basically add the following line to /etc/sysconfig/httpd.

export OPENSSL_NO_DEFAULT_ZLIB=1

For Apache httpd 2.2.24 and greater there has been a fix implemented in mod_ssl. Now there's a SSLCompression option available to disable compression over SSL. Add the following line to httpd.conf.

SSLCompression Off

Certain modules should be disabled. Comment out the following modules from httpd.conf.

#LoadModule deflate_module modules/mod_deflate.so
#LoadModule suexec_module modules/mod_suexec.so

mod_deflate is potentially used by HTTP. If VirtualHosts are configured to use mod_deflate then the CRIME exploit vulnerability will be a concern. mod_suexec is dangerous if apache directories' permissions are improperly configured. mod_suexec can be exploited to write to the document root which gives a remote attacker the ability to possibly execute a local exploit to escalate privileges. GitLab does not require mod_suexec so it is better to remain disabled.

How to self manage a Certificate Authority to sign SSL certificates

Using self signed certificates is always a bad idea. It's far more secure to self manage a certificate authority than it is to use self signed certificates. Running a certificate authority is easy. There are three recommended options for managing a certificate authority for signing certificates.

The xca project provides a graphical front end to certificate authority management in openssl. It is available for Windows, Linux, and Mac OS.
The OpenVPN project provides a nice set of scripts for managing a certificate authority as well. Eventually the GitLab project may include these scripts for their own purpose but for now SSL certificate management is outside of their scope.
Be your own CA tutorial provides a more manual method of certificate authority management outside of scripts or UI. It provides openssl commands for certificate authority management.

Once a certificate authority is self managed simply add the CA certificate to all browsers and mobile devices. Enjoy secure and validated certificates everywhere. If a GitLab service is designated for public access then self managing a certificate authority may not be the best option. Signed certificates should still be the preferred method to secure GitLab. The StartCom SSL Certificate Authority provides a free service to sign Class 1 SSL certificates.

Ubuntu notes

In Ubuntu httpd is called Apache2 and apache logs are located under /var/log/apache2. Log path names in the GitLab Apache configuration file should reflect this. Ubuntu runs AppArmor instead of SELinux and by default doesn't affect GitLab operation.

General notes

mod_pagespeed

There have been reports regarding mod_pagespeed on Apache. If you ever encounter such an issue, try disabling it. In /etc/apache2/mods-available/pagespeed.conf place the following:

ModPagespeed off

If you don't want to disable it completely, read this article to better understand it.