Create and restore application backups

Create a backup of omnibus-gitlab configuration

To prevent possible issues it is strongly recommended to keep a copy of the /etc/gitlab directory in a safe place. It is very important that you have, at least, a copy of these files:

• /etc/gitlab/gitlab.rb: contains the configuration parameters of the application.

• /etc/gitlab/gitlab-secrets.json: contains the database encryption keys to protect sensitive data in the SQL database.

  NOTE: It is very important to store the files above in different places. Separating the configuration backup from the application backup reduces the chance of losing or having stolen both your encrypted application data and the keys needed to decrypt it.

• To backup the configuration, you need to backup the /etc/gitlab directory:

    $ sudo sh -c 'umask 0077; tar -cf $(date "+etc-gitlab-%s.tar") -C / etc/gitlab'
  

Create a GitLab system backup

To create a backup of a GitLab installation with the Omnibus package, run the following command:

$ sudo gitlab-rake gitlab:backup:create

This command will create a backup stored in the /var/opt/gitlab/backups directory.

Find more information about how to create a backup of GitLab in the official documentation.

Create a daily backup

(Optional): you also can create a daily application backup following the steps above:

• Edit the “cron table” for user root:

    $ sudo crontab -e -u root
  

• Add a script similar to the following:

    15 04 * * 3-7  umask 0077; tar cfz /secret/gitlab/backups/$(date "+etc-gitlab-\%s.tgz") -C / etc/gitlab
  

  This will create a compressed .tgz file of the /etc/gitlab directory from Wednesday [day 3] to Sunday [day 7]) every week.

Restore a backup of GitLab

Restore the Omnibus-GitLab configuration backup

Extract the .tar file you have obtained in the backup process as follows:

• Rename the existing /etc/gitlab directory (in case it exists):

    $ sudo mv /etc/gitlab /etc/gitlab.$(date +%s)
  

• Extract the files (the TIMESTAMP_NUMBER is a placeholder, your configuration backup file has its own timestamp number):

    $ sudo tar -xf etc-gitlab-TIMESTAMP_NUMBER.tar -C /
  

• Run the following command to restore the configuration backup:

    $ sudo gitlab-ctl reconfigure
  

  NOTE: Your machine’s SSH host keys are stored in a separate location at /etc/ssh/. Check these instructions to backup and restore those keys.

Restore the GitLab system backup

NOTE: You can only restore a backup to exactly the same version of GitLab that you created it on (e.g.: 8.10).

These instructions assume that:

• You have installed the same version of GitLab Omnibus as that used in your backup.

• GitLab is running. If not, start it running the following command:

    $ sudo gitlab-ctl start
  

To restore the application backup follow the steps below:

• Run the gitlab-ctl reconfigure command at least once, if you haven’t done before:

    $ sudo gitlab-ctl reconfigure
  

• Make sure that the backup .tgz or .tar file is in the backup directory. To find it, you can check in the /etc/gitlab/gitlab.rb file the following line gitlab_rails[‘backup_path’].

  It is located by default at /var/opt/gitlab/backups, if not, copy it into the default directory:

    $ sudo cp TIMESTAMP_NUMBER_gitlab_backup.tar /var/opt/gitlab/backups/
  

  Remember that TIMESTAMP_NUMBER is a placeholder. Your backup file should be like this: 1393513121_2017_02_04_gitlab_backup.tar

• Stop only those processes that are connected to the database. Leave the rest running:

    $ sudo gitlab-ctl stop unicorn
    $ sudo gitlab-ctl stop sidekiq
  

• Verify the status of those processes:

    $ sudo gitlab-ctl status
  

• Restore the backup. You need to specify the timestamp of the backup you want to restore:

    $ sudo gitlab-rake gitlab:backup:restore BACKUP=TIMESTAMP_NUMBER
  

• Restart and check GitLab:

    $ sudo gitlab-ctl start
    $ sudo gitlab-rake gitlab:check SANITIZE=true