1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
---
stage: Systems
group: Distribution
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
---
# Upgrade
DETAILS:
**Tier:** Free, Premium, Ultimate
**Offering:** Self-managed
In most cases, upgrading GitLab is as easy as downloading the newest Docker
image tag.
## Upgrade GitLab using Docker Engine
To upgrade a GitLab instance that was [installed using Docker Engine](installation.md#install-gitlab-by-using-docker-engine):
1. Create a [backup](backup.md). As a minimum, back up [the database](backup.md#create-a-database-backup) and
the GitLab secrets file.
1. Stop the running container:
```shell
sudo docker stop gitlab
```
1. Remove the existing container:
```shell
sudo docker rm gitlab
```
1. Pull the new image:
```shell
sudo docker pull gitlab/gitlab-ee:<version>-ee.0
```
1. Ensure that the `GITLAB_HOME` environment variable is [defined](installation.md#create-a-directory-for-the-volumes):
```shell
echo $GITLAB_HOME
```
1. Create the container again with the
[previously specified](installation.md#install-gitlab-by-using-docker-engine) options:
```shell
sudo docker run --detach \
--hostname gitlab.example.com \
--publish 443:443 --publish 80:80 --publish 22:22 \
--name gitlab \
--restart always \
--volume $GITLAB_HOME/config:/etc/gitlab \
--volume $GITLAB_HOME/logs:/var/log/gitlab \
--volume $GITLAB_HOME/data:/var/opt/gitlab \
--shm-size 256m \
gitlab/gitlab-ee:<version>-ee.0
```
On the first run, GitLab reconfigures and upgrades itself.
Refer to the GitLab [Upgrade recommendations](../../policy/maintenance.md#upgrade-recommendations)
when upgrading to different versions.
## Upgrade GitLab using Docker compose
To upgrade a GitLab instance that was [installed using Docker Compose](installation.md#install-gitlab-by-using-docker-compose):
1. Take a [backup](backup.md). As a minimum, back up [the database](backup.md#create-a-database-backup) and
the GitLab secrets file.
1. Edit `docker-compose.yml` and change the version to pull.
1. Download the newest release and upgrade your GitLab instance:
```shell
docker compose pull
docker compose up -d
```
## Convert Community Edition to Enterprise Edition
You can convert an existing GitLab Community Edition (CE) container for Docker
to a GitLab [Enterprise Edition](https://about.gitlab.com/pricing/) (EE) container
using the same approach as [upgrading the version](upgrade.md).
We recommend you convert from the same version of CE to EE (for example, CE 14.1 to EE 14.1).
However, this is not required. Any standard upgrade (for example, CE 14.0 to EE 14.1) should work.
The following steps assume that you are converting to the same version.
1. Take a [backup](backup.md). At minimum, back up [the database](backup.md#create-a-database-backup) and
the GitLab secrets file.
1. Stop the current CE container, and remove or rename it.
1. To create a new container with GitLab EE,
replace `ce` with `ee` in your `docker run` command or `docker-compose.yml` file.
Reuse the CE container name, port mappings, file mappings, and version.
## Downgrade GitLab
The restore overwrites all newer GitLab database content with the older state.
A downgrade is only recommended where necessary. For example, if post-upgrade tests reveal problems that cannot be resolved quickly.
WARNING:
You must have at least a database backup created with the exact same version and edition you are downgrading to.
The backup is required to revert the schema changes (migrations) made during the upgrade.
To downgrade GitLab shortly after an upgrade:
1. Follow the upgrade procedure, by [specifying an earlier version](installation.md#find-the-gitlab-version-and-edition-to-use)
than you have installed.
1. Restore the [database backup you made](backup.md#create-a-database-backup) before the upgrade.
- [Follow the restore steps for Docker images](../../administration/backup_restore/restore_gitlab.md#restore-for-docker-image-and-gitlab-helm-chart-installations), including
stopping Puma and Sidekiq. Only the database must be restored, so add
`SKIP=artifacts,repositories,registry,uploads,builds,pages,lfs,packages,terraform_state`
to the `gitlab-backup restore` command line arguments.
|
