Browse Source

Merge branch 'update/gitlab-migration_doc' into 'master'

Update/gitlab migration doc

See merge request cloudron/docs!28
Girish Ramakrishnan 2 months ago
  1. 1
  2. 165


@ -6,6 +6,7 @@ Live docs site: [](
* mkdocs
* mkdocs-material
* mkdocs-redirects
* redoc-cli
Just run ./ it will install the dependencies


@ -95,3 +95,168 @@ $ bundle exec rails c -e production # (takes about 10 sec to bring up rails term
There are various other settings GitLab supports via `gitlab.rb`. On Cloudron those are specified in `/app/data/gitlab.yml`.
The upstream docs are referring to the key style of `gitlab.rb` and the mapping of keys for the yml file are described [here](
## Migration to Cloudron
This guide aims to assist in migrating an already running Gitlab into the Gitlab Cloudron app.
If you have any problems please do not delay and seek help in the [Forum](
This guide got written for a migration from a Gitlab installation via Omnibus.
!!! warning "Make sure both Gitlab instances are running the same version! Before continuing to the next step!"
The backup Rake task GitLab provides does not store your configuration files. The primary reason for this is that your database contains items including encrypted information for two-factor authentication and the CI/CD secure variables. Storing encrypted information in the same location as its key defeats the purpose of using encryption in the first place.
At the very minimum, you must backup:
For Omnibus:
- `/etc/gitlab/gitlab-secrets.json`
- `/etc/gitlab/gitlab.rb`
For installation from source:
- `/home/git/gitlab/config/secrets.yml`
- `/home/git/gitlab/config/gitlab.yml`
NOTE! Since we are switching from Omnibus TO a source installation (The Cloudron Gitlab app is a source installation) we will need to convert the `gitlab-secrets.json` to `secrets.yml`.
Also in the converted `secrets.yml` you will need to change `gitlab_rails:` to `production:` - otherwise gitlab will generate new secrets for rails.
### Create a backup of your running Gitlab
!!! note "[Gitlab Documentation - Backup and Restore]("
> GitLab 12.2 or later:
> ```bash
> sudo gitlab-backup create
> ```
> GitLab 12.1 and earlier:
> ```bash
> gitlab-rake gitlab:backup:create
> ```
> If you installed GitLab from source, use the following command: (This is how to do it in Cloudron)
> ```bash
> sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
> ```
> For more examples please visit the official [Gitlab Documentation - Backup and Restore](
Save the generated file I.e. `1632462433_2021_09_24_14.2.4_gitlab_backup.tar` on your local computer.
### Change the database owner in the created backup
In the Omnibus version the default user for the database was `gitlab` in my case.
You need to change this into the PostgreSQL user provided by Cloudron.
Go into the [Web terminal](/apps#web-terminal) of your Cloudron Gitlab app to get the username:
# echoing the single variable
# getting all Postgresql variables
printenv | grep -i POSTGRES
The content of the backup looks like this:
├── artifacts.tar.gz
├── backup_information.yml
├── builds.tar.gz
├── db
│   └── database.sql.gz
├── lfs.tar.gz
├── pages.tar.gz
├── repositories
│   └── @hashed
└── uploads.tar.gz
Extract the `database.sql.gz` to edit the `database.sql`.
We will need to replace all `OWNER TO gitlab;` strings to `OWNER TO userd5499e3cf81b43d093724d69fa223688;`.
Save the `database.sql` and `gzip` the file back into the `database.sql.gz`.
Put it back together into the `1632462433_2021_09_24_14.2.4_gitlab_backup.tar`.
Example all done in a terminal:
# Move the created backup into a seperate folder for extraction
# Extract the created tar
tar -xf 1632745419_2021_09_27_14.2.4_gitlab_backup.tar
# decompress the gziped database.sql.gz
gzip -d db/database.sql.gz
# replace all `OWNER TO gitlab;` with `OWNER TO OWNER TO userd5499e3cf81b43d093724d69fa223688;`
sed -e 's/OWNER TO gitlab;/OWNER TO userd5499e3cf81b43d093724d69fa223688;/' -i db/database.sql
# compress the `database.sql`
gzip db/database.sql
# Create the new `1632745419_2021_09_27_14.2.4_gitlab_backup.tar`
# You will get a warning since it wont tar it self
tar -cf 1632745419_2021_09_27_14.2.4_gitlab_backup.tar ./
tar: ./1632745419_2021_09_27_14.2.4_gitlab_backup.tar is the archive; not backed up.
### Restoring the Backup
* Upload the new tar to the Gitlab Cloudron app to `/app/data/backups/1632745419_2021_09_27_14.2.4_gitlab_backup.tar`.
* Upload the converted `secrets.yml` to `/app/data/secrets.yml`
* Create a snapshot of the running Cloudron Gitlab app (this way we can jump back if something does not work, and you won't need to re-upload the backup)
* Open the [Web terminal](/apps#web-terminal) of the Cloudron Gitlab app and run the restore
sudo -u git -H GITLAB_ASSUME_YES=1 bundle exec rake --trace gitlab:backup:restore RAILS_ENV=production
Now the restore should start looking something like this:
`/home/git` is not writable.
Bundler will use `/tmp/bundler20210927-435-134v1je435' as your home directory temporarily.
. . .
2021-09-24 06:22:36 +0000 -- done
2021-09-24 06:22:36 +0000 -- Restoring uploads ...
2021-09-24 06:22:36 +0000 -- done
2021-09-24 06:22:36 +0000 -- Restoring builds ...
2021-09-24 06:22:36 +0000 -- done
2021-09-24 06:22:36 +0000 -- Restoring artifacts ...
2021-09-24 06:22:36 +0000 -- done
2021-09-24 06:22:36 +0000 -- Restoring pages ...
2021-09-24 06:22:36 +0000 -- done
2021-09-24 06:22:36 +0000 -- Restoring lfs objects ...
2021-09-24 06:22:36 +0000 -- done
Now migrate your custom settings from the `gitlab.rb` settings into `/app/data/gitlab.yml` file.
Restart the Cloudron Gitlab app.
Now everything should work as intended.
### Migration of Gitlab Users to Cloudron LDAP Users
You might want to link old Gitlab users to the new Cloudron LDAP Users.
This is rather simple, just make sure the username of the user is the same as in Cloudron.
Gitlab username is `tina.testing` so the Cloudron username should also be `tina.testing`