GuidesDiscussionChangelogLog In

Backup and Restore

How to backup and restore a Team Server installation

Backing up a Team Server installation will archive essential configuration files and secrets, copy non-LFS git data into a GitLab backup archive, and then take a snapshot of dataset objects, LFS files, and the GitLab archive.

The backup process can be configured to use Local or External (Pro feature) storage. With Local Backups, all files are written to the local filesystem or mounted network attached storage. With External Backups, files are written to an externally managed object store (e.g. AWS S3).

At install time you must configure backup settings in the Settings File.


Configure Backups at Install Time

At install time you must configure backup settings. If you do not configure this properly, default settings may be used for the installation.

Configuring Local Backups

To write backups to a directory on the host filesystem, only configuring backup.directory in the settings file is required. This backup destination path cannot change after install, but it can be located on network attached storage with flexibility to mount and unmount.

admin_email: [email protected]
    directory: "/home/myuser/backups"
  name: My Test Server
  enabled: false

If the backup settings are not set at install, the installation will default to local backups and the backup directory will default to a folder backup inside the gigactl config directory (typically ~/.gigactl/backup). This directory is deleted during an uninstall, so if intending to make backups and use them for future restores, make sure to set the backup directory in the settings file or copy the contents of the default directory elsewhere before uninstalling.

Local backups will include copies of all object storage data in additional to git data. To ensure there is enough space, your system will need at least as much space as the size of object and git data in the backup location to create backups. This includes all Project and Dataset data.

Configuring External Backups

Backups can also be stored in an external object storage service with a Team Server Pro license. This offloads backup data to remote object storage instead of local file storage.

Currently, only AWS S3 storage can be used for external backups, but other object stores will be added in the future. To use an external object storage for backups:

  1. Create a bucket
  2. Create a connection file with credentials that have access to the bucket
# Example configuration of `connection` secret for Rails
# Example for AWS S3
provider: AWS
# Specify the region
region: us-east-1
# Specify access/secret keys
aws_access_key_id: BOGUS_ACCESS_KEY
aws_secret_access_key: BOGUS_SECRET_KEY
  1. Configure your settings.yaml file to enable external backups by providing the connection file path and bucket name
admin_email: [email protected]
    directory: "s3:s3.amazonaws.com/my-backup-bucket"
  service: "s3"
  connection: "/home/myuser/connection_file"
  name: My Test Server
  enabled: true

Connection files should mirror the format required for external storage connections in GitLab. Examples can be found here: (https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/examples/objectstorage). Currently, only AWS S3 storage can be used for external backups.

Creating a Backup

To start the back up process, run the following command:

./gigactl backup [--force-export]

There are no required command-line arguments or flags necessary for backups, but if this is your first time running a backup you will be prompted for the following input:

  • A password to protect snapshots - You must remember this password or you will lose access to the backed up files and be unable to restore. Once you have entered this password once, it is saved in your Team Server for future backups, but you will still need it for a restore.
  • An absolute path to write the configuration archive - A small archive file of sensitive configuration information for your cluster will be written on first backup. You can store this file anywhere after it is written, but you will need it in order to restore from a backup in the future. You should protect this file as if it were a password.

Any future backups will not prompt for the password and archive file path. You may wish to recreate the configuration archive, for example if you have restored from a backup using new settings or license files, or if you have changed the allowlist or redirect URL's, your archive will be out of date with your Team Server install. You can create a new archive by running backup with the --force-export flag and you will be prompted for another absolute path to save the new file.

Restoring a Backup

Restoring from a backup is currently only possible with a fresh installation, so there is no option to restore into an already-running cluster. This means to do a restore on the same server, you typically would ensure you have a completed backup, uninstall your existing cluster, and then do an install from backup.

Before you start a restore, make sure you know the password protecting backups and have the configuration archive available, both specified during the first backup operation. Then install a new Team Server using the following command:

./gigactl install hub --from-backup <absolute path to configuration archive>

If you want to change any of the configuration values in the restored server, you must provide the same command-line arguments used for an install. For example, to change the hostname you can request a new license file and specify this file with the --license-file argument.

Some parameters provided on the command line must always be provided, even during a restore, including any boolean parameters and certificate-related parameters. For example, if the backed-up Team Server was installed used the --ssl-cert and --ssl-cert-key flags and you wish to use them again for the restored installation, you must include the those arguments in the install command. Also keep in mind that using the --self-signed flag for a restore will create a new self-signed certificate.

Before the install begins, you will be prompted for the following inputs:

  • Password for the protected file snapshots - You must provide the correct password (which would have been set during the first backup) or you will be unable to restore these files
  • The snapshot ID for the backup you wish to restore - The available snapshots and the date and time at which they were taken will be displayed for reference.