From ec50d20d7ca90acb93ff7bf3dd45478a5b467682 Mon Sep 17 00:00:00 2001 From: john McGehee Date: Wed, 28 Sep 2016 15:45:32 -0700 Subject: Rebase and resolve conflicts in backup doc for !3761 --- doc/raketasks/backup_restore.md | 57 ++++++++++++++++++++++++----------------- 1 file changed, 34 insertions(+), 23 deletions(-) diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index 3f4056dc440..faa7e9eaa44 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -2,34 +2,45 @@ ![backup banner](backup_hrz.png) -## Create a backup of the GitLab system - -A backup creates an archive file that contains the database, all repositories and all attachments. -This archive will be saved in backup_path (see `config/gitlab.yml`). -The filename will be `[TIMESTAMP]_gitlab_backup.tar`. This timestamp can be used to restore an specific backup. -You can only restore a backup to exactly the same version of GitLab that you created it -on, for example 7.2.1. The best way to migrate your repositories from one server to +An application data backup creates an archive file that contains the database, +all repositories and all attachments. +This archive will be saved in `backup_path`, which is specified in the +`config/gitlab.yml` file. +The filename will be `[TIMESTAMP]_gitlab_backup.tar`, where `TIMESTAMP` +identifies the time at which each backup was created. + +You can only restore a backup to exactly the same version of GitLab on which it +was created. The best way to migrate your repositories from one server to another is through backup restore. -You need to keep separate copies of `/etc/gitlab/gitlab-secrets.json` and -`/etc/gitlab/gitlab.rb` (for omnibus packages) or -`/home/git/gitlab/config/secrets.yml` (for installations from source). This file -contains the database encryption keys used for two-factor authentication and CI -secret variables, among other things. If you restore a GitLab backup without -restoring the database encryption key, users who have two-factor authentication -enabled will lose access to your GitLab server. +To restore a backup, you will also need to restore `/etc/gitlab/gitlab-secrets.json` +(for omnibus packages) or `/home/git/gitlab/.secret` (for installations +from source). This file contains the database encryption key used +for two-factor authentication. If you fail to restore this encryption key file +along with the application data backup, users with two-factor +authentication enabled will lose access to your GitLab server. + +## Create a backup of the GitLab system +Use this command if you've installed GitLab with the Omnibus package: ``` -# use this command if you've installed GitLab with the Omnibus package sudo gitlab-rake gitlab:backup:create - -# if you've installed GitLab from source +``` +Use this if you've installed GitLab from source: +``` sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production ``` -Also you can choose what should be backed up by adding environment variable SKIP. Available options: db, -uploads (attachments), repositories, builds(CI build output logs), artifacts (CI build artifacts), lfs (LFS objects). -Use a comma to specify several options at the same time. +You can specify that portions of the application data be skipped using the +environment variable `SKIP`. You can skip: +- `db` +- `uploads` (attachments) +- `repositories` +- `builds` (CI build output logs) +- `artifacts` (CI build artifacts) +- `lfs` (LFS objects) + +Separate multiple data types to skip using a comma. For example: ``` sudo gitlab-rake gitlab:backup:create SKIP=db,uploads @@ -69,7 +80,7 @@ Deleting old backups... [SKIPPING] Starting with GitLab 7.4 you can let the backup script upload the '.tar' file it creates. It uses the [Fog library](http://fog.io/) to perform the upload. In the example below we use Amazon S3 for storage. -But Fog also lets you use [other storage providers](http://fog.io/storage/). +Fog also supports [other storage providers](http://fog.io/storage/). For omnibus packages: @@ -161,7 +172,7 @@ with the name of your bucket: ### Uploading to locally mounted shares You may also send backups to a mounted share (`NFS` / `CIFS` / `SMB` / etc.) by -using the [`Local`](https://github.com/fog/fog-local#usage) storage provider. +using the Fog [`Local`](https://github.com/fog/fog-local#usage) storage provider. The directory pointed to by the `local_root` key **must** be owned by the `git` user **when mounted** (mounting with the `uid=` of the `git` user for `CIFS` and `SMB`) or the user that you are executing the backup tasks under (for omnibus @@ -228,7 +239,7 @@ of using encryption in the first place! If you use an Omnibus package please see the [instructions in the readme to backup your configuration](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md#backup-and-restore-omnibus-gitlab-configuration). If you have a cookbook installation there should be a copy of your configuration in Chef. -If you have an installation from source, please consider backing up your `config/secrets.yml` file, `gitlab.yml` file, any SSL keys and certificates, and your [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). +If you installed from source, please consider backing up your `config/secrets.yml` file, `gitlab.yml` file, any SSL keys and certificates, and your [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). At the very **minimum** you should backup `/etc/gitlab/gitlab.rb` and `/etc/gitlab/gitlab-secrets.json` (Omnibus), or -- cgit v1.2.1 From 069d739efd17d8a6af5f3798a37e8f2cbfb02e5b Mon Sep 17 00:00:00 2001 From: John McGehee Date: Thu, 29 Sep 2016 20:38:43 +0000 Subject: Added "CI secret variables" per @axil. --- doc/raketasks/backup_restore.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index faa7e9eaa44..91c2df7d464 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -15,9 +15,9 @@ another is through backup restore. To restore a backup, you will also need to restore `/etc/gitlab/gitlab-secrets.json` (for omnibus packages) or `/home/git/gitlab/.secret` (for installations -from source). This file contains the database encryption key used -for two-factor authentication. If you fail to restore this encryption key file -along with the application data backup, users with two-factor +from source). This file contains the database encryption key and CI secret +variables used for two-factor authentication. If you fail to restore this +encryption key file along with the application data backup, users with two-factor authentication enabled will lose access to your GitLab server. ## Create a backup of the GitLab system -- cgit v1.2.1 From 7aa9675fbd7ca2e45403adb444fc03680f0e5d7a Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 10 Oct 2016 17:35:57 +0200 Subject: Add registry to skipped data in backup raketask docs [ci skip] --- doc/raketasks/backup_restore.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index 91c2df7d464..26baffdf792 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -32,15 +32,17 @@ sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production ``` You can specify that portions of the application data be skipped using the -environment variable `SKIP`. You can skip: -- `db` +environment variable `SKIP`. You can skip: + +- `db` (database) - `uploads` (attachments) -- `repositories` +- `repositories` (Git repositories data) - `builds` (CI build output logs) - `artifacts` (CI build artifacts) - `lfs` (LFS objects) +- `registry` (Container Registry images) -Separate multiple data types to skip using a comma. For example: +Separate multiple data types to skip using a comma. For example: ``` sudo gitlab-rake gitlab:backup:create SKIP=db,uploads -- cgit v1.2.1