Commit b67689b5 authored by Nick Gaskill's avatar Nick Gaskill 🛎
Browse files

Merge branch 'docs-aqualls-omnibus-pkgdocs-move' into 'master'

Move package information index page into this repo

See merge request gitlab-org/gitlab!70537
parents d55ece38 76bd1561
......@@ -21,7 +21,7 @@ Before configuring Consul:
1. Review the [reference architecture](reference_architectures/
documentation to determine the number of Consul server nodes you should have.
1. If necessary, ensure the [appropriate ports are open]( in your firewall.
1. If necessary, ensure the [appropriate ports are open](package-information/ in your firewall.
## Configure the Consul nodes
......@@ -138,7 +138,7 @@ The following table lists basic ports that must be open between the **primary**
| 22 | 22 | TCP |
| 5432 | | PostgreSQL |
See the full list of ports used by GitLab in [Package defaults](
See the full list of ports used by GitLab in [Package defaults](../package-information/
[Web terminal](../../ci/environments/ support requires your load balancer to correctly handle WebSocket connections.
stage: Enablement
group: Distribution
info: To determine the technical writer assigned to the Stage/Group associated with this page, see
# Package defaults
Unless configuration is specified in the `/etc/gitlab/gitlab.rb` file,
the package will assume the defaults as noted below.
## Ports
See the table below for the list of ports that the Omnibus GitLab assigns
by default:
| Component | On by default | Communicates via | Alternative | Connection port |
| :----------------------------------------------------: | :------------: | :--------------: | :---------: | :------------------------------------: |
| <a name="gitlab-rails"></a> GitLab Rails | Yes | Port | X | 80 or 443 |
| <a name="gitlab-shell"></a> GitLab Shell | Yes | Port | X | 22 |
| <a name="postgresql"></a> PostgreSQL | Yes | Socket | Port (5432) | X |
| <a name="redis"></a> Redis | Yes | Socket | Port (6379) | X |
| <a name="puma"></a> Puma | Yes | Socket | Port (8080) | X |
| <a name="gitlab-workhorse"></a> GitLab Workhorse | Yes | Socket | Port (8181) | X |
| <a name="nginx-status"></a> NGINX status | Yes | Port | X | 8060 |
| <a name="prometheus"></a> Prometheus | Yes | Port | X | 9090 |
| <a name="node-exporter"></a> Node exporter | Yes | Port | X | 9100 |
| <a name="redis-exporter"></a> Redis exporter | Yes | Port | X | 9121 |
| <a name="postgres-exporter"></a> PostgreSQL exporter | Yes | Port | X | 9187 |
| <a name="pgbouncer-exporter"></a> PgBouncer exporter | No | Port | X | 9188 |
| <a name="gitlab-exporter"></a> GitLab Exporter | Yes | Port | X | 9168 |
| <a name="sidekiq-exporter"></a> Sidekiq exporter | Yes | Port | X | 8082 |
| <a name="puma-exporter"></a> Puma exporter | No | Port | X | 8083 |
| <a name="geo-postgresql"></a> Geo PostgreSQL | No | Socket | Port (5431) | X |
| <a name="redis-sentinel"></a> Redis Sentinel | No | Port | X | 26379 |
| <a name="incoming-email"></a> Incoming email | No | Port | X | 143 |
| <a name="elasticsearch"></a> Elastic search | No | Port | X | 9200 |
| <a name="gitlab-pages"></a> GitLab Pages | No | Port | X | 80 or 443 |
| <a name="gitlab-registry-web"></a> GitLab Registry | No* | Port | X | 80, 443 or 5050 |
| <a name="gitlab-registry"></a> GitLab Registry | No | Port | X | 5000 |
| <a name="ldap"></a> LDAP | No | Port | X | Depends on the component configuration |
| <a name="kerberos"></a> Kerberos | No | Port | X | 8443 or 8088 |
| <a name="omniauth"></a> OmniAuth | Yes | Port | X | Depends on the component configuration |
| <a name="smtp"></a> SMTP | No | Port | X | 465 |
| <a name="remote-syslog"></a> Remote syslog | No | Port | X | 514 |
| <a name="mattermost"></a> Mattermost | No | Port | X | 8065 |
| <a name="mattermost-web"></a> Mattermost | No | Port | X | 80 or 443 |
| <a name="pgbouncer"></a> PgBouncer | No | Port | X | 6432 |
| <a name="consul"></a> Consul | No | Port | X | 8300, 8301(UDP), 8500, 8600[^Consul-notes] |
| <a name="patroni"></a> Patroni | No | Port | X | 8008 |
| <a name="gitlab-kas"></a> GitLab KAS | No | Port | X | 8150 |
| <a name="gitaly"></a> Gitaly | No | Port | X | 8075 |
- `Component` - Name of the component.
- `On by default` - Is the component running by default.
- `Communicates via` - How the component talks with the other components.
- `Alternative` - If it is possible to configure the component to use different type of communication. The type is listed with default port used in that case.
- `Connection port` - Port on which the component communicates.
GitLab also expects a filesystem to be ready for the storage of Git repositories
and various other files.
Note that if you are using NFS (Network File System), files will be carried
over a network which will require, based on implementation, ports `111` and
`2049` to be open.
In some cases, the GitLab Registry will be automatically enabled by default. Please see [our documentation](../packages/ for more details
[^Consul-notes]: If using additional Consul functionality, more ports may need to be opened. See the [official documentation]( for the list.
stage: Enablement
group: Distribution
info: To determine the technical writer assigned to the Stage/Group associated with this page, see
# OS Versions that are no longer supported
GitLab provides omnibus packages for operating systems only until their
EOL (End-Of-Life). After the EOL date of the OS, GitLab will stop releasing
official packages. The list of deprecated operating systems and the final GitLab
release for them can be found below:
| OS Version | End Of Life | Last supported GitLab version |
| --------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Raspbian Wheezy | [May 2015]( | [GitLab CE]( 8.17 |
| OpenSUSE 13.2 | [January 2017]( | [GitLab CE]( / [GitLab EE]( 9.1 |
| Ubuntu 12.04 | [April 2017]( | [GitLab CE]( / [GitLab EE]( 9.1 |
| OpenSUSE 42.1 | [May 2017]( | [GitLab CE]( / [GitLab EE]( 9.3 |
| OpenSUSE 42.2 | [January 2018]( | [GitLab CE]( / [GitLab EE]( 10.4 |
| Debian Wheezy | [May 2018]( | [GitLab CE]( / [GitLab EE]( 11.6 |
| Raspbian Jessie | [May 2017]( | [GitLab CE]( 11.7 |
| Ubuntu 14.04 | [April 2019]( | [GitLab CE]( / [GitLab EE]( 11.10 |
| OpenSUSE 42.3 | [July 2019]( | [GitLab CE]( / [GitLab EE]( 12.1 |
| OpenSUSE 15.0 | [December 2019]( | [GitLab CE]( / [GitLab EE]( 12.5 |
| Raspbian Stretch | [June 2020]( | [GitLab CE]( 13.3 |
| Debian Jessie | [June 2020]( | [GitLab CE]( / [GitLab EE]( 13.3 |
| CentOS 6 | [November 2020]( | [GitLab CE]( / [GitLab EE]( 13.6 |
| OpenSUSE 15.1 | [November 2020]( | [GitLab CE]( / [GitLab EE]( 13.12 |
| Ubuntu 16.04 | [April 2021]( | [GitLab CE]( / [GitLab EE]( 13.12 |
An exception to this deprecation policy is when we are unable to provide
packages for the next version of the operating system. The most common reason
for this our package repository provider, Packagecloud, not supporting newer
versions and hence we can't upload packages to it.
## Update GitLab package sources after upgrading the OS
After upgrading the Operating System (OS) as per its own documentation,
it may be necessary to also update the GitLab package source URL
in your package manager configuration.
If your package manager reports that no further updates are available,
although [new versions have been released](, repeat the
"Add the GitLab package repository" instructions
of the [Linux package install guide](
Future GitLab upgrades will now be fetched according to your upgraded OS.
## Supported Operating Systems
GitLab officially supports LTS versions of operating systems. While OSs like
Ubuntu have a clear distinction between LTS and non-LTS versions, there are
other OSs, openSUSE for example, that don't follow the LTS concept. Hence to
avoid confusion, the official policy is that at any point of time, all the
operating systems supported by GitLab are listed in the [installation
The following lists the currently supported OSs and their possible EOL dates.
| OS Version | First supported GitLab version | Arch | OS EOL | Details |
| ---------------- | ------------------------------ | --------------- | ------------- | ------------------------------------------------------------ |
| CentOS 7 | GitLab CE / GitLab EE 7.10.0 | x86_64 | June 2024 | <> |
| CentOS 8 | GitLab CE / GitLab EE 12.8.1 | x86_64, aarch64 | Dec 2021 | <> |
| Debian 9 | GitLab CE / GitLab EE 9.3.0 | amd64 | 2022 | <> |
| Debian 10 | GitLab CE / GitLab EE 12.2.0 | amd64, arm64 | TBD | <> |
| OpenSUSE 15.2 | GitLab CE / GitLab EE 13.11.0 | x86_64, aarch64 | Dec 2021 | <> |
| SLES 12 | GitLab EE 9.0.0 | x86_64 | Oct 2027 | <> |
| Ubuntu 18.04 | GitLab CE / GitLab EE 10.7.0 | amd64 | April 2023 | <> |
| Ubuntu 20.04 | GitLab CE / GitLab EE 13.2.0 | amd64, arm64 | April 2025 | <> |
| Raspbian Buster | GitLab CE 12.2.0 | armhf | 2022 | <> |
### Packages for ARM64
> [Introduced]( in GitLab 13.4.
GitLab provides arm64/aarch64 packages for some supported operating systems.
You can see if your operating system architecture is supported in the table
There are currently still some [known issues and limitation](
running GitLab on ARM.
stage: Enablement
group: Distribution
info: To determine the technical writer assigned to the Stage/Group associated with this page, see
# Deprecation policy
The Omnibus GitLab packages come with number of different libraries and services which offers users plethora of configuration options.
As libraries and services get updated, their configuration options change
and become obsolete. To increase maintainability and preserve a working
setup, various configuration requires removal.
## Configuration deprecation
### Policy
The Omnibus GitLab package will retain configuration for at least **one major**
version. We cannot guarantee that deprecated configuration
will be available in the next major release. See [example](#example) for more details.
### Notice
If the configuration becomes obsolete, we will announce the deprecation:
- via release blog post on ``. The blog post item
will contain the deprecation notice together with the target removal date.
- via installation/reconfigure output (if applicable).
- via official documentation on ``. The documentation update will contain the corrected syntax (if applicable) or a date of configuration removal.
### Procedure
This section lists steps necessary for deprecating and removing configuration.
We can differentiate two different types of configuration:
- Sensitive: Configuration that can cause major service outage ( Data integrity,
installation integrity, preventing users from reaching the installation, etc.)
- Regular: Configuration that can make a feature unavailable but still makes the installation useable ( Change in default project/group settings, miscommunication with other components and similar )
We also need to differentiate deprecation and removal procedure.
#### Deprecating configuration
Deprecation procedure is similar for both `sensitive` and `regular` configuration. The only difference is in the removal target date.
Common steps:
1. Create an issue at the [Omnibus GitLab issue tracker]( with details on deprecation type and other necessary information. Apply the label `deprecation`.
1. Decide on the removal target for the deprecated configuration
1. Formulate deprecation notice for each item as noted in [Notice section](#notice)
Removal target:
For regular configuration, removal target should always be the date of the **next major** release. If the date is not known, you can reference the next major version.
For sensitive configuration things are a bit more complicated.
We should aim to not remove sensitive configuration in the *next major* release if the next major release is 2 minor releases away (This number is chosen to match our security backport release policy).
See the table below for some examples:
| Config. type | Deprecation announced | Final minor release | Remove |
| -------- | -------- | -------- | -------- |
| Sensitive | 10.1.0 | 10.9.0 | 11.0.0 |
| Sensitive | 10.7.0 | 10.9.0 | 12.0.0 |
| Regular | 10.1.0 | 10.9.0 | 11.0.0 |
| Regular | 10.8.0 | 10.9.0 | 11.0.0 |
#### Removing configuration
When deprecation is announced and removal target set, the milestone for the issue
should be changed to match the removal target version.
The final comment in the issue **has to have**:
1. Text snippet for the release blog post section
1. Documentation MR ( or snippet ) for introducing the change
1. Draft MR removing the configuration OR details on what needs to be done. See [Adding deprecation messages]( for more on this
## Example
User configuration available in `/etc/gitlab/gitlab.rb` was introduced in GitLab version 10.0, `gitlab_rails['configuration'] = true`. In GitLab version 10.4.0, a new change was introduced that requires rename of this configuration option. New configuration option is `gitlab_rails['better_configuration'] = true`. Development team will translate the old configuration into new one
and trigger a deprecation procedure.
This means that these two configuration
options will both be valid through GitLab version 10. In other words,
if you still have `gitlab_rails['configuration'] = true` set in GitLab 10.8.0
the feature will continue working the same way as if you had `gitlab_rails['better_configuration'] = true` set.
However, setting the old version of configuration will print out a deprecation
notice at the end of installation/upgrade/reconfigure run.
With GitLab 11, `gitlab_rails['configuration'] = true` will no longer work and you will have to manually change the configuration in `/etc/gitlab/gitlab.rb` to the new valid config.
**Note** If this configuration option is sensitive and can put integrity of the installation or
data in danger, installation/upgrade will be aborted.
stage: Enablement
group: Distribution
info: To determine the technical writer assigned to the Stage/Group associated with this page, see
# Package information
The Omnibus GitLab package is bundled with all dependencies required for GitLab
to function correctly. More details can be found
at [bundling dependencies document](
## Package Version
The released package versions are in the format `MAJOR.MINOR.PATCH-EDITION.OMNIBUS_RELEASE`
| Component | Meaning | Example |
| --------- | ------- | ------- |
| MAJOR.MINOR.PATCH | The GitLab version this corresponds to | 13.3.0 |
| EDITION | The edition of GitLab this corresponds to | ee |
| OMNIBUS_RELEASE | The omnibus release. Usually, this will be 0. This will be incremented if we need to build a new package without changing the GitLab version. | 0 |
## Licenses
See [licensing](
## Defaults
The Omnibus GitLab package requires various configuration to get the
components in working order.
If the configuration is not provided, the package will use the default
values assumed in the package.
These defaults are noted in the package [defaults document](
## Checking the versions of bundled software
Once the Omnibus GitLab package is installed, all versions of the bundled
libraries are located in `/opt/gitlab/version-manifest.txt`.
If you don't have the package installed, you can always check the Omnibus GitLab
[source repository](, specifically the
[config directory](
For example, if you take a look at the `8-6-stable` branch, you can conclude that
8.6 packages were running [Ruby 2.1.8](
Or, that 8.5 packages were bundled with [NGINX 1.9.0](
## Signatures of GitLab, Inc. provided packages
Documentation on package signatures can be found at [Signed Packages](
## Checking for newer configuration options on upgrade
Configuration file in `/etc/gitlab/gitlab.rb` is created on initial installation
of the Omnibus GitLab package. On subsequent package upgrades, the configuration
file is not updated with new configuration. This is done in order to avoid
accidental overwrite of user configuration provided in `/etc/gitlab/gitlab.rb`.
New configuration options are noted in the
[`gitlab.rb.template` file](
The Omnibus GitLab package also provides convenience command which will
compare the existing user configuration with the latest version of the
template contained in the package.
To view a diff between your configuration file and the latest version, run:
sudo gitlab-ctl diff-config
_**Note:** This command is available from GitLab 8.17_
**Important:** If you are copy-pasting the output of this command into your
`/etc/gitlab/gitlab.rb` configuration file, make sure to omit leading `+` and `-`
on each line.
## Init system detection
Omnibus GitLab will attempt to query the underlaying system in order to
check which init system it uses.
This manifests itself as a `WARNING` during the `sudo gitlab-ctl reconfigure`
Depending on the init system, this `WARNING` can be one of:
/sbin/init: unrecognized option '--version'
when the underlying init system *IS NOT* upstart.
-.mount loaded active mounted /
when the underlying init system *IS* systemd.
These warnings _can be safely ignored_. They are not suppressed because this
allows everyone to debug possible detection issues faster.
stage: Enablement
group: Distribution
info: To determine the technical writer assigned to the Stage/Group associated with this page, see
# Package Licensing
## License
While GitLab itself is MIT, the Omnibus GitLab sources are licensed under the Apache-2.0.
## License file location
Starting with version 8.11, the Omnibus GitLab package contains license
information of all software that is bundled within the package.
After installing the package, licenses for each individual bundled library
can be found in `/opt/gitlab/LICENSES` directory.
There is also one `LICENSE` file which contains all licenses compiled together.
This compiled license can be found in `/opt/gitlab/LICENSE` file.
Starting with version 9.2, the Omnibus GitLab package ships a
`dependency_licenses.json` file containing version and license information of
all bundled software, including software libraries, Ruby gems that the rails
application uses, and JavaScript libraries that is required for the frontend
components. This file, being in JSON format, is easily machine parseable and
can be used for automated checks or validations. The file may be found at
Starting with version 11.3, we have also made the license information available
online, at: <>
## Checking licenses
The Omnibus GitLab package is made up of many pieces of software, comprising code
that is covered by many different licenses. Those licenses are provided and
compiled as stated above.
Starting with version 8.13, GitLab has placed an additional step into
Omnibus GitLab. The `license_check` step calls
`lib/gitlab/tasks/license_check.rake`, which checks the compiled `LICENSE` file
against the current list of approved and questionable licenses as denoted in the
arrays at the top of the script. This script will output one of `Good`,
`Unknown` or `Check` for each piece of software that is a part of the
Omnibus GitLab package.
- `Good`: denotes a license that is approved for all usage types, within GitLab and
Omnibus GitLab.
- `Unknown`: denotes a license that is not recognized in the list of 'good' or 'bad',
which should be immediately reviewed for implications of use.
- `Check`: denotes a license that has the potential be incompatible with GitLab itself,
and thus should be checked for how it is used as a part of the Omnibus GitLab package
to ensure compliance.
This list is currently sourced from the [GitLab development documentation on licensing](
However, due to the nature of the Omnibus GitLab package the licenses may not apply
in the same way. Such as with `git` and `rsync`. See the [GNU License FAQ](
## License acknowledgements
### libjpeg-turbo - BSD 3-clause license
This software is based in part on the work of the Independent JPEG Group.
## Trademark Usage
Within the GitLab documentation, reference to third party technology(ies) and/or trademarks of third party entities, may be made. The inclusion of reference to third party technology and/or entities is solely for the purposes of example(s) of how GitLab software may interact with, or be used in conjunction with, such third party technology.
All trademarks, materials, documentation, and other intellectual property remain the property of any/all such third party.
### Trademark Requirements
Use of GitLab Trademarks must be in compliance with the standards set forth in [our guidelines]( (as updated from time to time).
CHEF® and all Chef marks are owned by Progress Software Corporation and must be used in accordance with the [Progress Software Trademark Usage Policy](
When using a GitLab or 3rd party trademark in documentation, include the (R) symbol in the first instance, for example, "Chef(R) is used for configuring...." You may omit the symbol in subsequent instances.
If a trademark owner requires a particular notice or trademark requirement, such notice or requirement should be stated above.
stage: Enablement
group: Distribution
info: To determine the technical writer assigned to the Stage/Group associated with this page, see
# Omnibus based packages and images
Below you can find some basic information on why GitLab provides packages and
a Docker image that come with bundled dependencies.
These methods are great for physical and virtual machine installations, and simple Docker installations.
## Goals
We have a few core goals with these packages:
1. Extremely easy to install, upgrade, maintain.
1. Support for a wide variety of operating systems
1. Wide support of cloud service providers
## Omnibus GitLab Architecture
GitLab in its core is a Ruby on Rails project. However, GitLab as a whole
application is more complex and has multiple components. If these components are
not present or are incorrectly configured, GitLab will not work or it will work
The [GitLab Architecture Overview](../../development/ shows some of these components and how they
interact. Each of these components needs to be configured and kept up to date.
Most of the components also have external dependencies. For example, the Rails
application depends on a number of [Ruby gems]( Some of these dependencies also
have their own external dependencies which need to be present on the Operating
System in order for them to function correctly.
Furthermore, GitLab has a monthly release cycle requiring frequent maintenance
to stay up to date.
All the things listed above present a challenge for the user maintaining the GitLab
## External Software Dependencies
For applications such as GitLab, external dependencies usually bring the following
- Keeping versions in sync between direct and indirect dependencies
- Availability of a version on a specific Operating System
- Version changes can introduce or remove previously used configuration
- Security implications when library is marked as vulnerable but does not have
a new version released yet
Keep in mind that if a dependency exists on your Operating System, it does not
necessarily exist on other supported OSs.
## Benefits
A few benefits of a package with bundled dependencies:
1. Minimal effort required to install GitLab.
1. Minimum configuration required to get GitLab up and running.
1. Minimum effort required to upgrade between GitLab versions.
1. Multiple platforms supported.
1. Maintenance on older platforms is greatly simplified.
1. Less effort to support potential issues.
## Drawbacks
Some drawbacks of a package with bundled dependencies:
1. Duplication with possibly existing software.
1. Less flexibility in configuration.
## Why would I install an omnibus package when I can use a system package?
The answer can be simplified to: less maintenance required. Instead of handling
multiple packages that *can* break existing functionality if the versions are
not compatible, only handle one.
Multiple packages require correct configuration in multiple locations.
Keeping configuration in sync can be error prone.
If you have the skill set to maintain all current dependencies and enough time
to handle any future dependencies that might get introduced, the above listed
reasons might not be good enough for you to not use the omnibus package.
There are two things to keep in mind before going down this route:
1. Getting support for any problems
you encounter might be more difficult due to the number of possibilities that exist
when using a library version that is not tested by majority of users.
1. Omnibus package also allows shutting off of any services that you do not need,
if you need to run a component independently. For example, you can use a
[non-bundled PostgreSQL database]( with the omnibus package.
Keep in mind that a non-standard solution like the omnibus package
might be a better fit when the application has a number of moving parts.
## Docker image with multiple services
[GitLab Docker image](../../install/ is based on the omnibus package.
Considering that container spawned from this image contains multiple processes,
these types of containers are also referred to as 'fat containers'.
There are reasons for and against an image like this, but they are similar to
what was noted above:
1. Very simple to get started.
1. Upgrading to the latest version is extremely simple.
1. Running separate services in multiple containers and keeping them running
can be more complex and might not be required for a given install.
This method is useful for organizations just getting started with containers and schedulers, and may not be ready for a more complex installation. This method is a great introduction, and will work well for smaller organizations.
stage: Enablement
group: Distribution
info: To determine the technical writer assigned to the Stage/Group associated with this page, see
# PostgreSQL versions shipped with Omnibus GitLab
This table lists only GitLab versions where a significant change happened in the
package regarding PostgreSQL versions, not all.
Usually, PostgreSQL versions change with major or minor GitLab releases. However, patch versions
of Omnibus GitLab sometimes update the patch level of PostgreSQL.
For example:
- Omnibus 12.7.6 shipped with PostgreSQL 9.6.14 and 10.9.
- Omnibus 12.7.7 shipped with PostgreSQL 9.6.17 and 10.12.
[Find out which versions of PostgreSQL (and other components) ship with
each Omnibus GitLab release](
Read more about update policies and warnings in the PostgreSQL
[upgrade docs](