-[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)
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
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)