diff options
Diffstat (limited to 'doc/update/package')
-rw-r--r-- | doc/update/package/convert_to_ee.md | 118 | ||||
-rw-r--r-- | doc/update/package/downgrade.md | 83 | ||||
-rw-r--r-- | doc/update/package/index.md | 278 |
3 files changed, 479 insertions, 0 deletions
diff --git a/doc/update/package/convert_to_ee.md b/doc/update/package/convert_to_ee.md new file mode 100644 index 00000000000..2cc54e2c8cf --- /dev/null +++ b/doc/update/package/convert_to_ee.md @@ -0,0 +1,118 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Convert Community Edition to Enterprise Edition **(FREE SELF)** + +To convert an existing GitLab Community Edition (CE) server installed using the Omnibus GitLab +packages to GitLab [Enterprise Edition](https://about.gitlab.com/pricing/) (EE), you install the EE +package on top of CE. + +Converting from the same version of CE to EE is not explicitly necessary, and any standard upgrade +(for example, CE 12.0 to EE 12.1) should work. However, in the following steps we assume that +you are upgrading the same version (for example, CE 12.1 to EE 12.1), which is **recommended**. + +WARNING: +When updating to EE from CE, avoid reverting back to CE if you plan on going to EE again in the +future. Reverting back to CE can cause +[database issues](index.md#500-error-when-accessing-project--settings--repository) +that may require Support intervention. + +The steps can be summed up to: + +1. Find the currently installed GitLab version: + + **For Debian/Ubuntu** + + ```shell + sudo apt-cache policy gitlab-ce | grep Installed + ``` + + The output should be similar to: `Installed: 13.0.4-ce.0`. In that case, + the equivalent Enterprise Edition version will be: `13.0.4-ee.0`. Write this + value down. + + **For CentOS/RHEL** + + ```shell + sudo rpm -q gitlab-ce + ``` + + The output should be similar to: `gitlab-ce-13.0.4-ce.0.el8.x86_64`. In that + case, the equivalent Enterprise Edition version will be: + `gitlab-ee-13.0.4-ee.0.el8.x86_64`. Write this value down. + +1. Add the `gitlab-ee` [Apt or Yum repository](https://packages.gitlab.com/gitlab/gitlab-ee/install): + + **For Debian/Ubuntu** + + ```shell + curl --silent "https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh" | sudo bash + ``` + + **For CentOS/RHEL** + + ```shell + curl --silent "https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.rpm.sh" | sudo bash + ``` + + The above command will find your OS version and automatically set up the + repository. If you are not comfortable installing the repository through a + piped script, you can first + [check its contents](https://packages.gitlab.com/gitlab/gitlab-ee/install). + +1. Next, install the `gitlab-ee` package. Note that this will automatically + uninstall the `gitlab-ce` package on your GitLab server. `reconfigure` + Omnibus right after the `gitlab-ee` package is installed. **Make sure that you + install the exact same GitLab version**: + + **For Debian/Ubuntu** + + ```shell + ## Make sure the repositories are up-to-date + sudo apt-get update + + ## Install the package using the version you wrote down from step 1 + sudo apt-get install gitlab-ee=13.0.4-ee.0 + + ## Reconfigure GitLab + sudo gitlab-ctl reconfigure + ``` + + **For CentOS/RHEL** + + ```shell + ## Install the package using the version you wrote down from step 1 + sudo yum install gitlab-ee-13.0.4-ee.0.el8.x86_64 + + ## Reconfigure GitLab + sudo gitlab-ctl reconfigure + ``` + +1. Now go to the GitLab admin panel of your server (`/admin/license/new`) and + upload your license file. + +1. After you confirm that GitLab is working as expected, you may remove the old + Community Edition repository: + + **For Debian/Ubuntu** + + ```shell + sudo rm /etc/apt/sources.list.d/gitlab_gitlab-ce.list + ``` + + **For CentOS/RHEL** + + ```shell + sudo rm /etc/yum.repos.d/gitlab_gitlab-ce.repo + ``` + +That's it! You can now use GitLab Enterprise Edition! To update to a newer +version, follow [Update using the official repositories](index.md#upgrade-using-the-official-repositories). + +NOTE: +If you want to use `dpkg`/`rpm` instead of `apt-get`/`yum`, go through the first +step to find the current GitLab version and then follow +[Update using a manually-downloaded package](index.md#upgrade-using-a-manually-downloaded-package). diff --git a/doc/update/package/downgrade.md b/doc/update/package/downgrade.md new file mode 100644 index 00000000000..9a528f5ee44 --- /dev/null +++ b/doc/update/package/downgrade.md @@ -0,0 +1,83 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Downgrade **(FREE SELF)** + +This section contains general information on how to revert to an earlier version +of a package. + +WARNING: +You must at least have a database backup created under the version you are +downgrading to. Ideally, you should have a +[full backup archive](../../raketasks/backup_restore.md#back-up-gitlab) +on hand. + +The example below demonstrates the downgrade procedure when downgrading between minor +and patch versions (for example, from 13.0.6 to 13.0.5). + +When downgrading between major versions, take into account the +[specific version changes](index.md#version-specific-changes) that occurred when you upgraded +to the major version you are downgrading from. + +These steps consist of: + +- Stopping GitLab +- Removing the current package +- Installing the old package +- Reconfiguring GitLab +- Restoring the backup +- Starting GitLab + +Steps: + +1. Stop GitLab and remove the current package: + + ```shell + # If running Puma + sudo gitlab-ctl stop puma + + # Stop sidekiq + sudo gitlab-ctl stop sidekiq + + # If on Ubuntu: remove the current package + sudo dpkg -r gitlab-ee + + # If on Centos: remove the current package + sudo yum remove gitlab-ee + ``` + +1. Identify the GitLab version you want to downgrade to: + + ```shell + # (Replace with gitlab-ce if you have GitLab FOSS installed) + + # Ubuntu + sudo apt-cache madison gitlab-ee + + # CentOS: + sudo yum --showduplicates list gitlab-ee + ``` + +1. Downgrade GitLab to the desired version (for example, to GitLab 13.0.5): + + ```shell + # (Replace with gitlab-ce if you have GitLab FOSS installed) + + # Ubuntu + sudo apt install gitlab-ee=13.0.5-ee.0 + + # CentOS: + sudo yum install gitlab-ee-13.0.5-ee.0.el8 + ``` + +1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. [Restore GitLab](../../raketasks/backup_restore.md#restore-for-omnibus-gitlab-installations) + to complete the downgrade. diff --git a/doc/update/package/index.md b/doc/update/package/index.md new file mode 100644 index 00000000000..44be79f22fb --- /dev/null +++ b/doc/update/package/index.md @@ -0,0 +1,278 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Upgrade GitLab using the GitLab Package **(FREE SELF)** + +This section describes how to upgrade GitLab to a new version using the +GitLab package. + +We recommend performing upgrades between major and minor releases no more than once per +week, to allow time for background migrations to finish. Decrease the time required to +complete these migrations by increasing the number of +[Sidekiq workers](../../administration/operations/extra_sidekiq_processes.md) +that can process jobs in the `background_migration` queue. + +If you don't follow the steps in [zero downtime upgrades](../zero_downtime.md), +your GitLab application will not be available to users while an upgrade is in progress. +They either see a "Deploy in progress" message or a "502" error in their web browser. + +Prerequisites: + +- [Supported upgrade paths](../index.md#upgrade-paths) + has suggestions on when to upgrade. Upgrade paths are enforced for version upgrades by + default. This restricts performing direct upgrades that skip major versions (for + example 10.3 to 12.7 in one jump) that **can break GitLab + installations** due to multiple reasons like deprecated or removed configuration + settings, upgrade of internal tools and libraries, and so on. +- If you are upgrading from a non-Package installation to a GitLab Package installation, see + [Upgrading from a non-Package installation to a GitLab Package installation](https://docs.gitlab.com/omnibus/convert_to_omnibus.html). +- It's important to ensure that any + [background migrations](../index.md#checking-for-background-migrations-before-upgrading) + have been fully completed before upgrading to a new major version. Upgrading + before background migrations have finished may lead to data corruption. +- Gitaly servers must be upgraded to the newer version prior to upgrading the application server. + This prevents the gRPC client on the application server from sending RPCs that the old Gitaly version + does not support. + +You can upgrade the GitLab Package using one of the following methods: + +- [Using the official repositories](#upgrade-using-the-official-repositories). +- [Using a manually-downloaded package](#upgrade-using-a-manually-downloaded-package). + +Both automatically back up the GitLab database before installing a newer +GitLab version. You may skip this automatic database backup by creating an empty file +at `/etc/gitlab/skip-auto-backup`: + +```shell +sudo touch /etc/gitlab/skip-auto-backup +``` + +For safety reasons, you should maintain an up-to-date backup on your own if you plan to use this flag. + +## Version-specific changes + +Updating to major versions might need some manual intervention. For more information, +check the version your are upgrading to: + +- [GitLab 14](https://docs.gitlab.com/omnibus/gitlab_14_changes.html) +- [GitLab 13](https://docs.gitlab.com/omnibus/gitlab_13_changes.html) +- [GitLab 12](https://docs.gitlab.com/omnibus/gitlab_12_changes.html) +- [GitLab 11](https://docs.gitlab.com/omnibus/gitlab_11_changes.html) + +## Upgrade using the official repositories + +All GitLab packages are posted to the GitLab [package server](https://packages.gitlab.com/gitlab/). +Five repositories are maintained: + +- [GitLab EE](https://packages.gitlab.com/gitlab/gitlab-ee): for official + [Enterprise Edition](https://about.gitlab.com/pricing/) releases. +- [GitLab CE](https://packages.gitlab.com/gitlab/gitlab-ce): for official Community Edition releases. +- [Unstable](https://packages.gitlab.com/gitlab/unstable): for release candidates and other unstable versions. +- [Nighty Builds](https://packages.gitlab.com/gitlab/nightly-builds): for nightly builds. +- [Raspberry Pi](https://packages.gitlab.com/gitlab/raspberry-pi2): for official Community Edition releases built for [Raspberry Pi](https://www.raspberrypi.org) packages. + +If you have installed Omnibus GitLab [Community Edition](https://about.gitlab.com/install/?version=ce) +or [Enterprise Edition](https://about.gitlab.com/install/), then the +official GitLab repository should have already been set up for you. + +To upgrade to the newest GitLab version, run: + +- For GitLab [Enterprise Edition](https://about.gitlab.com/pricing/): + + ```shell + # Debian/Ubuntu + sudo apt-get update + sudo apt-get install gitlab-ee + + # Centos/RHEL + sudo yum install gitlab-ee + ``` + +- For GitLab Community Edition: + + ```shell + # Debian/Ubuntu + sudo apt-get update + sudo apt-get install gitlab-ce + + # Centos/RHEL + sudo yum install gitlab-ce + ``` + +### Upgrade to a specific version using the official repositories + +Linux package managers default to installing the latest available version of a +package for installation and upgrades. Upgrading directly to the latest major +version can be problematic for older GitLab versions that require a multi-stage +[upgrade path](../index.md#upgrade-paths). An upgrade path can span multiple +versions, so you must specify the specific GitLab package with each upgrade. + +To specify the intended GitLab version number in your package manager's install +or upgrade command: + +1. First, identify the GitLab version number in your package manager: + + ```shell + # Ubuntu/Debian + sudo apt-cache madison gitlab-ee + # RHEL/CentOS 6 and 7 + yum --showduplicates list gitlab-ee + # RHEL/CentOS 8 + dnf search gitlab-ee* + ``` + +1. Then install the specific GitLab package: + + ```shell + # Ubuntu/Debian + sudo apt install gitlab-ee=12.0.12-ee.0 + # RHEL/CentOS 6 and 7 + yum install gitlab-ee-12.0.12-ee.0.el7 + # RHEL/CentOS 8 + dnf install gitlab-ee-12.0.12-ee.0.el8 + # SUSE + zypper install gitlab-ee=12.0.12-ee.0 + ``` + +## Upgrade using a manually-downloaded package + +NOTE: +The [package repository](#upgrade-using-the-official-repositories) is recommended over +a manual installation. + +If for some reason you don't use the official repositories, you can +download the package and install it manually. This method can be used to either +install GitLab for the first time or update it. + +To download and install GitLab: + +1. Visit the [official repository](#upgrade-using-the-official-repositories) of your package. +1. Browse to the repository for the type of package you would like to see the + list of packages that are available. Multiple packages exist for a + single version, one for each supported distribution type. Next to the filename + is a label indicating the distribution, as the file names may be the same. +1. Find the package version you wish to install and click on it. +1. Click the **Download** button in the upper right corner to download the package. +1. After the GitLab package is downloaded, install it using the following commands: + + - For GitLab [Enterprise Edition](https://about.gitlab.com/pricing/): + + ```shell + # Debian/Ubuntu + dpkg -i gitlab-ee-<version>.deb + + # CentOS/RHEL + rpm -Uvh gitlab-ee-<version>.rpm + ``` + + - For GitLab Community Edition: + + ```shell + # GitLab Community Edition + # Debian/Ubuntu + dpkg -i gitlab-ce-<version>.deb + + # CentOS/RHEL + rpm -Uvh gitlab-ce-<version>.rpm + ``` + +## Troubleshooting + +### GitLab 13.7 and later unavailable on Amazon Linux 2 + +Amazon Linux 2 is not an [officially supported operating system](../../administration/package_information/deprecated_os.md#supported-operating-systems). +However, in past the [official package installation script](https://packages.gitlab.com/gitlab/gitlab-ee/install) +installed the `el/6` package repository if run on Amazon Linux. From GitLab 13.7, we no longer +provide `el/6` packages so administrators must run the [installation script](https://packages.gitlab.com/gitlab/gitlab-ee/install) +again to update the repository to `el/7`: + +```shell +curl --silent "https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.rpm.sh" | sudo bash +``` + +See the [epic on support for GitLab on Amazon Linux 2](https://gitlab.com/groups/gitlab-org/-/epics/2195) for the latest details on official Amazon Linux 2 support. + +### Get the status of a GitLab installation + +```shell +sudo gitlab-ctl status +sudo gitlab-rake gitlab:check SANITIZE=true +``` + +- Information on using `gitlab-ctl` to perform [maintenance tasks](https://docs.gitlab.com/omnibus/maintenance/index.html). +- Information on using `gitlab-rake` to [check the configuration](../../administration/raketasks/maintenance.md#check-gitlab-configuration). + +### RPM 'package is already installed' error + +If you are using RPM and you are upgrading from GitLab Community Edition to GitLab Enterprise Edition you may get an error like this: + +```shell +package gitlab-7.5.2_omnibus.5.2.1.ci-1.el7.x86_64 (which is newer than gitlab-7.5.2_ee.omnibus.5.2.1.ci-1.el7.x86_64) is already installed +``` + +You can override this version check with the `--oldpackage` option: + +```shell +sudo rpm -Uvh --oldpackage gitlab-7.5.2_ee.omnibus.5.2.1.ci-1.el7.x86_64.rpm +``` + +### Package obsoleted by installed package + +CE and EE packages are marked as obsoleting and replacing each other so that both aren't installed and running at the same time. + +If you are using local RPM files to switch from CE to EE or vice versa, use `rpm` for installing the package rather than `yum`. If you try to use yum, then you may get an error like this: + +```plaintext +Cannot install package gitlab-ee-11.8.3-ee.0.el6.x86_64. It is obsoleted by installed package gitlab-ce-11.8.3-ce.0.el6.x86_64 +``` + +To avoid this issue, either: + +- Use the same instructions provided in the + [Upgrade using a manually-downloaded package](#upgrade-using-a-manually-downloaded-package) section. +- Temporarily disable this checking in yum by adding `--setopt=obsoletes=0` to the options given to the command. + +### 500 error when accessing Project > Settings > Repository + +When GitLab is migrated from CE > EE > CE, and then back to EE, you +might get the following error when viewing a project's repository settings: + +```shell +Processing by Projects::Settings::RepositoryController#show as HTML + Parameters: {"namespace_id"=>"<namespace_id>", "project_id"=>"<project_id>"} +Completed 500 Internal Server Error in 62ms (ActiveRecord: 4.7ms | Elasticsearch: 0.0ms | Allocations: 14583) + +NoMethodError (undefined method `commit_message_negative_regex' for #<PushRule:0x00007fbddf4229b8> +Did you mean? commit_message_regex_change): +``` + +This error is caused by an EE feature being added to a CE instance on the initial move to EE. +After the instance is moved back to CE and then is upgraded to EE again, the +`push_rules` table already exists in the database. Therefore, a migration is +unable to add the `commit_message_regex_change` column. + +This results in the [backport migration of EE tables](https://gitlab.com/gitlab-org/gitlab/-/blob/cf00e431024018ddd82158f8a9210f113d0f4dbc/db/migrate/20190402150158_backport_enterprise_schema.rb#L1619) not working correctly. +The backport migration assumes that certain tables in the database do not exist when running CE. + +To fix this issue, manually add the missing `commit_message_negative_regex` column and restart GitLab: + +```shell +# Access psql +sudo gitlab-rails dbconsole + +# Add the missing column +ALTER TABLE push_rules ADD COLUMN commit_message_negative_regex VARCHAR; + +# Exit psql +\q + +# Restart GitLab +sudo gitlab-ctl restart +``` + +### Error `Failed to connect to the internal GitLab API` on a separate GitLab Pages server + +Please see [GitLab Pages troubleshooting](../../administration/pages/index.md#failed-to-connect-to-the-internal-gitlab-api). |