Installation from source

Consider the Omnibus package installation

Since an installation from source is a lot of work and error prone we strongly recommend the fast and reliable Omnibus package installation (deb/rpm).

One reason the Omnibus package is more reliable is its use of Runit to restart any of the GitLab processes in case one crashes.
On heavily used GitLab instances the memory usage of the Sidekiq background worker will grow over time.

Omnibus packages solve this by letting the Sidekiq terminate gracefully if it uses too much memory.
After this termination Runit will detect Sidekiq is not running and will start it.
Since installations from source don't use Runit for process supervision, Sidekiq
can't be terminated and its memory usage will grow over time.

Select Version to Install

Make sure you view this installation guide from the branch (version) of GitLab you would like to install (e.g., 11-7-stable).
You can select the branch in the version dropdown in the top left corner of GitLab (below the menu bar).

If the highest number stable branch is unclear, check the GitLab blog for installation guide links by version.

Important Notes

This installation guide was created for and tested on Debian/Ubuntu operating systems. Read requirements.md for hardware and operating system requirements. If you want to install on RHEL/CentOS, we recommend using the Omnibus packages.

This is the official installation guide to set up a production server. To set up a development installation or for many other installation options, see the installation section of the README.

The following steps have been known to work. Use caution when you deviate from this guide. Make sure you don't violate any assumptions GitLab makes about its environment. For example, many people run into permission problems because they changed the location of directories or run services as the wrong user.

If you find a bug/error in this guide, submit a merge request
following the
contributing guide.

Overview

The GitLab installation consists of setting up the following components:

1. Packages and dependencies

NOTE: Note:
During this installation, some files will need to be edited manually. If you are familiar with vim, set it as default editor with the commands below. If you are not familiar with vim, skip this and keep using the default editor.

Note: In order to receive mail notifications, make sure to install a mail server. By default, Debian is shipped with exim4 but this has problems while Ubuntu does not ship with one. The recommended mail server is postfix and you can install it with:

sudo apt-get install-y postfix

Then select 'Internet Site' and press enter to confirm the hostname.

2. Ruby

The Ruby interpreter is required to run GitLab.

Note: The current supported Ruby (MRI) version is 2.5.x. GitLab 11.6
dropped support for Ruby 2.4.x.

The use of Ruby version managers such as RVM, rbenv or chruby with GitLab
in production, frequently leads to hard to diagnose problems. For example,
GitLab Shell is called from OpenSSH, and having a version manager can prevent
pushing and pulling over SSH. Version managers are not supported and we strongly
advise everyone to follow the instructions below to use a system Ruby.

Linux distributions generally have older versions of Ruby available, so these
instructions are designed to install Ruby from the official source code.

3. Go

Since GitLab 8.0, GitLab has several daemons written in Go. To install
GitLab we need a Go compiler. The instructions below assume you use 64-bit
Linux. You can find downloads for other platforms at the Go download
page.

CAUTION: Caution:
Make sure to edit both gitlab.yml and unicorn.rb to match your setup.

NOTE: Note:
If you want to use HTTPS, see Using HTTPS for the additional steps.

Configure GitLab DB Settings

# PostgreSQL only:sudo-u git cp config/database.yml.postgresql config/database.yml# MySQL only:sudo-u git cp config/database.yml.mysql config/database.yml# MySQL and remote PostgreSQL only:# Update username/password in config/database.yml.# You only need to adapt the production settings (first part).# If you followed the database guide then please do as follows:# Change 'secure password' with the value you have given to $password# You can keep the double quotes around the passwordsudo-u git -H editor config/database.yml# PostgreSQL and MySQL:# Make config/database.yml readable to git onlysudo-u git -Hchmod o-rwx config/database.yml

Install Gems

NOTE: Note:
As of Bundler 1.5.2, you can invoke bundle install -jN (where N is the number of your processor cores) and enjoy parallel gems installation with measurable difference in completion time (~60% faster). Check the number of your cores with nproc. For more information, see this post.

NOTE: Note:
If you want to use HTTPS, see Using HTTPS for the additional steps.

NOTE: Note:
Make sure your hostname can be resolved on the machine itself by either a proper DNS record or an additional line in /etc/hosts ("127.0.0.1 hostname"). This might be necessary, for example, if you set up GitLab behind a reverse proxy. If the hostname cannot be resolved, the final installation check will fail with "Check GitLab API access: FAILED. code: 401" and pushing commits will be rejected with "[remote rejected] master -> master (hook declined)".

NOTE: Note:
GitLab Shell application startup time can be greatly reduced by disabling RubyGems. This can be done in several ways:

Export RUBYOPT=--disable-gems environment variable for the processes.

Compile Ruby with configure --disable-rubygems to disable RubyGems by default. Not recommended for system-wide Ruby.

Install GitLab Pages

GitLab Pages uses GNU Make. This step is optional and only needed if you wish to host static sites from within GitLab. The following commands will install GitLab Pages in /home/git/gitlab-pages. For additional setup steps, consult the administration guide for your version of GitLab as the GitLab Pages daemon can be run several different ways.

NOTE: Note:
You can set the Administrator/root password and e-mail by supplying them in environmental variables, GITLAB_ROOT_PASSWORD and GITLAB_ROOT_EMAIL respectively, as seen below. If you don't set the password (and it is set to the default one), wait to expose GitLab to the public internet until the installation is done and you've logged into the server the first time. During the first login, you'll be forced to change the default password.

Secure secrets.yml

The secrets.yml file stores encryption keys for sessions and secure variables.
Backup secrets.yml someplace safe, but don't store it in the same place as your database backups.
Otherwise your secrets are exposed if one of your backups is compromised.

Install Init Script

Download the init script (will be /etc/init.d/gitlab):

sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab

And if you are installing with a non-default folder or user copy and edit the defaults file:

sudo cp lib/support/init.d/gitlab.default.example /etc/default/gitlab

If you installed GitLab in another directory or as a user other than the default, you should change these settings in /etc/default/gitlab. Do not edit /etc/init.d/gitlab as it will be changed on upgrade.

Site Configuration

Make sure to edit the config file to match your setup. Also, ensure that you match your paths to GitLab, especially if installing for a user other than the git user:

# Change YOUR_SERVER_FQDN to the fully-qualified# domain name of your host serving GitLab.## Remember to match your paths to GitLab, especially# if installing for a user other than 'git'.## If using Ubuntu default nginx install:# either remove the default_server from the listen line# or else sudo rm -f /etc/nginx/sites-enabled/defaultsudo editor /etc/nginx/sites-available/gitlab

If you intend to enable GitLab pages, there is a separate Nginx config you need
to use. Read all about the needed configuration at the
GitLab Pages administration guide.

Note: If you want to use HTTPS, replace the gitlab Nginx config with gitlab-ssl. See Using HTTPS for HTTPS configuration details.

Test Configuration

Validate your gitlab or gitlab-ssl Nginx config file with the following command:

sudo nginx -t

You should receive syntax is okay and test is successful messages. If you receive errors check your gitlab or gitlab-ssl Nginx config file for typos, etc. as indicated in the error message given.

Restart

Done!

Double-check Application Status

If all items are green, congratulations on successfully installing GitLab!

NOTE: Supply SANITIZE=true environment variable to gitlab:check to omit project names from the output of the check command.

Initial Login

Visit YOUR_SERVER in your web browser for your first GitLab login.

If you didn't provide a root password during setup,
you'll be redirected to a password reset screen to provide the password for the
initial administrator account. Enter your desired password and you'll be
redirected back to the login screen.

The default account's username is root. Provide the password you created
earlier and login. After login you can change the username if you wish.

Enjoy!

You can use sudo service gitlab start and sudo service gitlab stop to start and stop GitLab.

You also need to change the corresponding options (e.g. ssh_user, ssh_host, admin_uri) in the config\gitlab.yml file.

Additional Markup Styles

Apart from the always supported markdown style, there are other rich text files that GitLab can display. But you might have to install a dependency to do so. See the github-markup gem README for more information.

Troubleshooting

"You appear to have cloned an empty repository."

If you see this message when attempting to clone a repository hosted by GitLab,
this is likely due to an outdated Nginx or Apache configuration, or a missing or
misconfigured gitlab-workhorse instance. Double-check that you've
installed Go, installed gitlab-workhorse,
and correctly configured Nginx.