Install GitLab with the Linux package

Tier: Free, Premium, Ultimate Offering: Self-managed

Prerequisites

  • Installation Requirements.
  • If you want to access your GitLab instance by using a domain name, like mygitlabinstance.com, make sure the domain correctly points to the IP of the server where GitLab is being installed. You can check this using the command host mygitlabinstance.com.
  • If you want to use HTTPS on your GitLab instance, make sure you have the SSL certificates for the domain ready. (Note that certain components like Container Registry which can have their own subdomains requires certificates for those subdomains also.)
  • If you want to send notification emails, install and configure a mail server (MTA) like Sendmail or Postfix. Alternatively, you can use other third party SMTP servers.

Installation and Configuration

These configuration settings are commonly used when configuring a Linux package installation. For a complete list of settings, see the README file.

Set up the initial account

By default, a Linux package installation automatically generates a password for the initial administrator user account (root) and stores it to /etc/gitlab/initial_root_password for at least 24 hours. For security reasons, after 24 hours, this file is automatically removed by the first gitlab-ctl reconfigure.

The default account is tied to a randomly-generated email address. To override this, pass the GITLAB_ROOT_EMAIL environment variable to the installation command.

note
If GitLab can’t detect a valid hostname for the server during the installation, a reconfigure does not run.

To provide a custom initial root password, you have two options:

  • Pass the GITLAB_ROOT_PASSWORD environment variable to the installation command provided the hostname for the server is set up correctly:

    sudo GITLAB_ROOT_EMAIL="<gitlab_admin@example.com>" GITLAB_ROOT_PASSWORD="<strongpassword>" EXTERNAL_URL="http://gitlab.example.com" apt install gitlab-ee
    

    If during the installation GitLab doesn’t automatically perform a reconfigure, you have to pass the GITLAB_ROOT_PASSWORD or GITLAB_ROOT_EMAIL variable to the first gitlab-ctl reconfigure run.

  • Before the first reconfigure, edit /etc/gitlab/gitlab.rb (create it if it doesn’t exist) and set:

    gitlab_rails['initial_root_password'] = '<my_strong_password>'
    

Both of these methods apply only during the initial database seeding, which happens during the first reconfigure. For subsequent reconfigure runs, neither of the aforementioned methods have any effect. In that case, use the random password in /etc/gitlab/initial_root_password to log in, or reset the root password.

Using Docker image

You can also use the Docker images provided by GitLab to install and configure a GitLab instance. Check the documentation to know more.

Uninstall the Linux package (Omnibus)

To uninstall the Linux package, you can opt to either keep your data (repositories, database, configuration) or remove all of them:

  1. Optional. To remove all users and groups created by the Linux package before removing the package (with apt or yum):

    sudo gitlab-ctl stop && sudo gitlab-ctl remove-accounts
    
    note
    If you have problems removing accounts or groups, run userdel or groupdel manually to delete them. You might also want to manually remove the leftover user home directories from /home/.
  2. Choose whether to keep your data or remove all of them:

    • To preserve your data (repositories, database, configuration), stop GitLab and remove its supervision process:

      sudo systemctl stop gitlab-runsvdir
      sudo systemctl disable gitlab-runsvdir
      sudo rm /usr/lib/systemd/system/gitlab-runsvdir.service
      sudo systemctl daemon-reload
      sudo systemctl reset-failed
      sudo gitlab-ctl uninstall
      
    • To remove all data:

      sudo gitlab-ctl cleanse && sudo rm -r /opt/gitlab
      
  3. Uninstall the package (replace with gitlab-ce if you have GitLab FOSS installed):

    # Debian/Ubuntu
    sudo apt remove gitlab-ee
    
    # RedHat/CentOS
    sudo yum remove gitlab-ee