Apache 2 version
The configuration files in this directory are known to work with GitLab 8.3 and newer versions.
For versions of GitLab 8.2, check the
For versions of GitLab 8.0 and 8.1, check the
For versions of GitLab older than 8.0, check the
Installations from source
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
In the last step you will need to download the config from this repository.
Most of the settings below were tested on CentOS 6, but are probably applicable to other distributions as well.
Puma or unicorn?
By default, Unicorn (i.e.
unicorn.rb) is configured to listen on port
in GitLab's documentation. Therefore, the Apache configuration files do that
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.
should exist and be configured. Two changes must then be made:
- In the Apache conf replace
http://0.0.0.0:9292. Also replace
puma.rb: comment out
bind 'tcp://0.0.0.0:9292'and comment
It is assumed GitLab will be running in a secure production environment.
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.
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.
There are a few places where the Apache configs need to be customized for the GitLab installation.
ServerNameis defined in two VirtualHosts.
ServerNameshould be set to host name of the GitLab installation.
SSLCACertificateFileshould be customized for signed certificates.
ProxyPassReverse http://gitlab.example.com:8080should be customized for public host name of the GitLab installation.
- At the bottom of
gitlab-ssl.conflog 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
SSLCACertificateFile should still be modified.
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
semanage is part of the
Other httpd security considerations
ServerTokens Prod ServerSignature Off TraceEnable Off
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)
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
For Apache httpd 2.2.24 and greater there has been a fix implemented in
Now there's a SSLCompression option available to disable
compression over SSL. Add the following line to
Certain modules should be disabled. Comment out the following modules from
#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
mod_deflate then the CRIME exploit vulnerability will be a
mod_suexec is dangerous if apache directories' permissions are
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.
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.
There have been reports regarding
mod_pagespeed on Apache.
If you ever encounter such an issue, try disabling it.
/etc/apache2/mods-available/pagespeed.conf place the following:
If you don't want to disable it completely, read this article to better understand it.