diff --git a/doc/index.md b/doc/index.md index 6b51522be384e4ac9810c2041ea9db7f6764aeee_ZG9jL2luZGV4Lm1k..0b4914967ff17e5311ff0b07ed6f77f2ec82a163_ZG9jL2luZGV4Lm1k 100644 --- a/doc/index.md +++ b/doc/index.md @@ -77,8 +77,12 @@ - [Upgrade from Community Edition to Enterprise Edition](https://docs.gitlab.com/ee/update/package/convert_to_ee.html) - [Upgrade to the latest version](https://docs.gitlab.com/ee/update/package/#upgrade-using-the-official-repositories) - [Downgrade to an earlier version](https://docs.gitlab.com/ee/update/package/downgrade.html) -- [Upgrade from a non-Linux package PostgreSQL to a Linux package installation using a backup](update/convert_to_omnibus.md#upgrading-from-a-non-linux-package-postgresql-to-a-linux-package-installation-using-a-backup) -- [Upgrade from a non-Linux package PostgreSQL to a Linux package installation in-place](update/convert_to_omnibus.md#upgrading-from-a-non-linux-package-postgresql-to-a-linux-package-installation-in-place) + +## Converting + +- [Convert a self-compiled installation to a Linux package installation](update/convert_to_omnibus.md) +- [Convert an external PostgreSQL to a Linux package installation by using a backup](update/convert_to_omnibus.md#convert-an-external-postgresql-to-a-linux-package-installation-by-using-a-backup) +- [Convert an external PostgreSQL to a Linux package installation in-place](update/convert_to_omnibus.md#convert-an-external-postgresql-to-a-linux-package-installation-in-place) ## Troubleshooting diff --git a/doc/update/convert_to_omnibus.md b/doc/update/convert_to_omnibus.md index 6b51522be384e4ac9810c2041ea9db7f6764aeee_ZG9jL3VwZGF0ZS9jb252ZXJ0X3RvX29tbmlidXMubWQ=..0b4914967ff17e5311ff0b07ed6f77f2ec82a163_ZG9jL3VwZGF0ZS9jb252ZXJ0X3RvX29tbmlidXMubWQ= 100644 --- a/doc/update/convert_to_omnibus.md +++ b/doc/update/convert_to_omnibus.md @@ -4,9 +4,9 @@ info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Upgrading from a non-Linux package installation to a Linux package installation +# Convert a self-compiled installation to a Linux package installation DETAILS: **Tier:** Free, Premium, Ultimate **Offering:** Self-managed @@ -8,7 +8,10 @@ DETAILS: **Tier:** Free, Premium, Ultimate **Offering:** Self-managed -Upgrading from non-Linux package installations has not been tested by GitLab. +If you installed GitLab by using the self-compiled installation method, you can convert your instance to a Linux +package instance. + +When converting a self-compiled installation: @@ -14,5 +17,5 @@ -Please be advised that you lose your settings in files such as `gitlab.yml`, -`puma.rb` and `smtp_settings.rb`. You must -[configure those settings in `/etc/gitlab/gitlab.rb`](../index.md#configuring). +- You must convert to the exact same version of GitLab. +- You must [configure settings in `/etc/gitlab/gitlab.rb`](../index.md#configuring) because settings in files such as + `gitlab.yml`, `puma.rb` and `smtp_settings.rb` are lost. @@ -18,4 +21,4 @@ -Before starting the migration, ensure that you are moving to **exactly the same version** of GitLab. -To convert your installation to using the Linux package: +WARNING: +Converting from self-compiled installations has not been tested by GitLab. @@ -21,5 +24,7 @@ -1. Create a backup from your current installation: +To convert your self-compiled installation to a Linux package installation: + +1. Create a backup from your current self-compiled installation: ```shell cd /home/git/gitlab @@ -35,5 +40,5 @@ sudo gitlab-backup restore BACKUP=<FILE_NAME> ``` - The restore takes a few minutes depending on the size of you database and Git data. + The restore takes a few minutes depending on the size of your database and Git data. @@ -39,15 +44,9 @@ -1. Configure the new installation because in Linux package installations, all settings are stored in - `/etc/gitlab/gitlab.rb`. Individual settings need to be manually moved from - files such as `gitlab.yml`, `puma.rb` and `smtp_settings.rb`. See the - [`gitlab.rb` template](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template) - for all available options. -1. To finalize the configuration process, copy the secrets from the old installation - to the new one. GitLab uses secrets to multiple purposes, like database encryption, - session encryption, and so on. In Linux package installations, all secrets are placed in a single - file `/etc/gitlab/gitlab-secrets.json`, whereas in source installations, the - secrets are placed in multiple files: - 1. First, you need to restore secrets related to Rails. Copy the values of - `db_key_base`, `secret_key_base` and `otp_key_base` from +1. Because all settings are stored in `/etc/gitlab/gitlab.rb` in Linux package installations, you must reconfigure + the new installation . Individual settings must be manually moved from self-compiled installation files such as + `gitlab.yml`, `puma.rb`, and `smtp_settings.rb`. For all available options, see the + [`gitlab.rb` template](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template). +1. Copy the secrets from the old self-compiled installation to the new Linux package installation: + 1. Restore secrets related to Rails. Copy the values of `db_key_base`, `secret_key_base` and `otp_key_base` from `/home/git/gitlab/config/secrets.yml` (self-compiled installation) to the equivalent ones in `/etc/gitlab/gitlab-secrets.json` (Linux package installation). @@ -52,8 +51,7 @@ `/home/git/gitlab/config/secrets.yml` (self-compiled installation) to the equivalent ones in `/etc/gitlab/gitlab-secrets.json` (Linux package installation). - 1. Then, copy the contents of `/home/git/gitlab-shell/.gitlab_shell_secret` - (GitLab source) to GitLab Shell's `secret_token` in - `/etc/gitlab/gitlab-secrets.json` (Linux package installation). It will look something like: + 1. Copy the contents of `/home/git/gitlab-shell/.gitlab_shell_secret` (self-compiled installation) to `secret_token` + in `/etc/gitlab/gitlab-secrets.json` (Linux package installation). It looks something like: ```json { @@ -78,9 +76,9 @@ sudo gitlab-ctl reconfigure ``` -1. If you migrated `/home/git/gitlab-shell/.gitlab_shell_secret`, you also [need to restart Gitaly](https://gitlab.com/gitlab-org/gitaly/-/issues/3837): +1. If you migrated `/home/git/gitlab-shell/.gitlab_shell_secret`, you [must restart Gitaly](https://gitlab.com/gitlab-org/gitaly/-/issues/3837): ```shell sudo gitlab-ctl restart gitaly ``` @@ -82,7 +80,7 @@ ```shell sudo gitlab-ctl restart gitaly ``` -## Upgrading from a non-Linux package PostgreSQL to a Linux package installation using a backup +## Convert an external PostgreSQL to a Linux package installation by using a backup @@ -88,7 +86,4 @@ -Upgrade by [creating a backup from the non-Linux package installation](https://docs.gitlab.com/ee/administration/backup_restore/backup_gitlab.html) -and [restoring this in the Linux package installation](https://docs.gitlab.com/ee/administration/backup_restore/restore_gitlab.html#restore-for-linux-package-installations). -Ensure you are using **exactly equal versions** of GitLab (for example 6.7.3) -when you do this. You might have to upgrade your non-Linux package installation before -creating the backup to achieve this. +You can convert an [external PostgreSQL installation](https://docs.gitlab.com/ee/administration/postgresql/external.html) +to a Linux package PostgreSQL installation by using a backup. You must use the same GitLab version when you do this. @@ -94,3 +89,3 @@ -After upgrading make sure that you run the check task: +To convert an external PostgreSQL installation to a Linux package PostgreSQL installation by using a backup: @@ -96,5 +91,5 @@ -```shell -sudo gitlab-rake gitlab:check -``` +1. [Create a backup from the non-Linux package installation](https://docs.gitlab.com/ee/administration/backup_restore/backup_gitlab.html) +1. [Restoring the backup in the Linux package installation](https://docs.gitlab.com/ee/administration/backup_restore/restore_gitlab.html#restore-for-linux-package-installations). +1. Run the `check` task: @@ -100,4 +95,5 @@ -If you receive an error similar to `No such file or directory @ realpath_rec - /home/git`, -run this one liner to fix the Git hooks path: + ```shell + sudo gitlab-rake gitlab:check + ``` @@ -103,7 +99,9 @@ -```shell -find . -lname /home/git/gitlab-shell/hooks -exec sh -c 'ln -snf /opt/gitlab/embedded/service/gitlab-shell/hooks $0' {} \; -``` +1. If you receive an error similar to `No such file or directory @ realpath_rec - /home/git`, run: + + ```shell + find . -lname /home/git/gitlab-shell/hooks -exec sh -c 'ln -snf /opt/gitlab/embedded/service/gitlab-shell/hooks $0' {} \; + ``` This assumes that `gitlab-shell` is located in `/home/git`. @@ -107,5 +105,10 @@ This assumes that `gitlab-shell` is located in `/home/git`. -## Upgrading from a non-Linux package PostgreSQL to a Linux package installation in-place +## Convert an external PostgreSQL to a Linux package installation in-place + +You can convert an [external PostgreSQL installation](https://docs.gitlab.com/ee/administration/postgresql/external.html) +to a Linux package PostgreSQL installation in-place. + +These instructions assume: @@ -111,7 +114,6 @@ -It is also possible to upgrade a self-compiled installation to a Linux package installation -in-place. Below we assume you are using PostgreSQL on Ubuntu, and that you -have an Linux package matching your current GitLab version. We also -assume that your source installation of GitLab uses all the default paths and -users. +- You are using PostgreSQL on Ubuntu. +- You have an Linux package matching your current GitLab version. +- Your self-compiled installation of GitLab uses all the default paths and users. +- The existing home directory of the Git user (`/home/git`) will be changed to `/var/opt/gitlab`. @@ -117,3 +119,3 @@ -First, stop and disable GitLab, Redis and NGINX. +To convert an external PostgreSQL installation to a Linux package PostgreSQL installation in-place: @@ -119,6 +121,3 @@ -```shell -# Ubuntu -sudo service gitlab stop -sudo update-rc.d gitlab disable +1. Stop and disable GitLab, Redis, and NGINX: @@ -124,4 +123,6 @@ -sudo service nginx stop -sudo update-rc.d nginx disable + ```shell + # Ubuntu + sudo service gitlab stop + sudo update-rc.d gitlab disable @@ -127,5 +128,4 @@ -sudo service redis-server stop -sudo update-rc.d redis-server disable -``` + sudo service nginx stop + sudo update-rc.d nginx disable @@ -131,6 +131,5 @@ -If you are using a configuration management system to manage GitLab on your -server, remember to also disable GitLab and its related services there. Also -note that in the following steps, the existing home directory of the Git user -(`/home/git`) will be changed to `/var/opt/gitlab`. + sudo service redis-server stop + sudo update-rc.d redis-server disable + ``` @@ -136,9 +135,5 @@ -Next, create a `gitlab.rb` file for your new setup: - -```shell -sudo mkdir /etc/gitlab -sudo tee -a /etc/gitlab/gitlab.rb <<'EOF' -# Use your own GitLab URL here -external_url 'http://gitlab.example.com' +1. If you are using a configuration management system to manage GitLab on your server, disable GitLab and its + related services there. +1. Create a `gitlab.rb` file for your new setup: @@ -144,4 +139,10 @@ -# We assume your repositories are in /home/git/repositories (default for source installs) -git_data_dirs({ 'default' => { 'path' => '/home/git' } }) + ```shell + sudo mkdir /etc/gitlab + sudo tee -a /etc/gitlab/gitlab.rb <<'EOF' + # Use your own GitLab URL here + external_url 'http://gitlab.example.com' + + # We assume your repositories are in /home/git/repositories (default for source installs) + git_data_dirs({ 'default' => { 'path' => '/home/git' } }) @@ -147,13 +148,11 @@ -# Re-use the PostgreSQL that is already running on your system -postgresql['enable'] = false -# This db_host setting is for Debian PostgreSQL packages -gitlab_rails['db_host'] = '/var/run/postgresql/' -gitlab_rails['db_port'] = 5432 -# We assume you called the GitLab DB user 'git' -gitlab_rails['db_username'] = 'git' -EOF -``` - -Now install the Linux package and reconfigure the installation: + # Re-use the PostgreSQL that is already running on your system + postgresql['enable'] = false + # This db_host setting is for Debian PostgreSQL packages + gitlab_rails['db_host'] = '/var/run/postgresql/' + gitlab_rails['db_port'] = 5432 + # We assume you called the GitLab DB user 'git' + gitlab_rails['db_username'] = 'git' + EOF + ``` @@ -159,5 +158,3 @@ -```shell -sudo gitlab-ctl reconfigure -``` +1. Now install the Linux package and reconfigure the installation: @@ -163,5 +160,8 @@ -You are not done yet! The `gitlab-ctl reconfigure` run has changed the home -directory of the Git user, so OpenSSH can no longer find its authorized_keys -file. Rebuild the keys file with the following command: + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Because the `gitlab-ctl reconfigure` run has changed the home directory of the Git user and OpenSSH can no longer + find its `authorized_keys` file, rebuild the keys file: @@ -167,5 +167,5 @@ -```shell -sudo gitlab-rake gitlab:shell:setup -``` + ```shell + sudo gitlab-rake gitlab:shell:setup + ``` @@ -171,4 +171,3 @@ -You should now have HTTP and SSH access to your GitLab server with the -repositories and users that were there before. + You should now have HTTP and SSH access to your GitLab server with the repositories and users that were there before. @@ -174,6 +173,5 @@ -If you can log into the GitLab web interface, the next step is to reboot your -server to make sure none of the old services interfere with the Linux package installation. - -If you are using special features such as LDAP you will have to put your -settings in `gitlab.rb`, see the [settings documentation](../settings/index.md). +1. If you can log into the GitLab web interface, reboot your server to make sure none of the old services interfere with + the Linux package installation. +1. If you are using special features such as LDAP, you must put your settings in `gitlab.rb`. For more information, + see the [settings documentation](../settings/index.md).