Omnibus Docker

A backup of an instance in a container is created by the same commands as on a host installation, run through docker exec. The archive is written to the data volume, so it lands on the host under the data directory. What the archive holds and what stays outside it is described in Overview.

Creating a backup

Run the backup in the running container:

docker exec -t code gitlab-backup create

The archive appears in /var/opt/gitlab/backups inside the container, which is /srv/code/data/backups on the host with the volumes from the quick start. Copy it off the host together with the archive of the configuration and the secrets.

For a schedule, run the same command from the host cron:

echo '0 2 * * * root /usr/bin/docker exec -t code gitlab-backup create CRON=1' \
  | sudo tee /etc/cron.d/deckhouse-code-backup

How long archives are kept is set by gitlab_rails['backup_keep_time'] in the configuration; its value and behaviour are described in Linux package.

Configuration and secrets

The archive of the instance data holds no configuration and no encryption keys. Archive them separately:

docker exec -t code gitlab-ctl backup-etc

The command writes /etc/gitlab/config_backup/gitlab_config_<TIMESTAMP>_<DATE>.tar with the content of /etc/gitlab: gitlab.rb, gitlab-secrets.json and the TLS certificates. The directory is on the configuration volume, /srv/code/config/config_backup on the host.

Restoring from a backup

The restore replaces the data of the instance with the content of the archive. Before you start, check that:

• the container runs the image tag of the version the backup was taken on;
• gitlab.rb, gitlab-secrets.json and the certificates of the source instance are on the configuration volume;
• the data volume has enough free space for the unpacked archive.

Restore the instance:

1. Copy the archive into the backup directory on the data volume and give it the owner the instance uses:

   sudo cp <BACKUP_NAME>_gitlab_backup.tar /srv/code/data/backups/
   docker exec code chown git:git /var/opt/gitlab/backups/<BACKUP_NAME>_gitlab_backup.tar

2. Stop the services that write to the database:

   docker exec code gitlab-ctl stop puma
   docker exec code gitlab-ctl stop sidekiq

3. Start the restore. The command asks for confirmation twice, before the authorized_keys file is rebuilt and before the current database tables are dropped; answer yes both times:

   docker exec -it code gitlab-backup restore BACKUP=<BACKUP_NAME>

4. Apply the configuration and restart the container:

   docker exec code gitlab-ctl reconfigure
   docker restart code

5. Check the instance:

   docker exec code gitlab-ctl status
   docker exec code gitlab-rake gitlab:check SANITIZE=true

<BACKUP_NAME> is the file name without the _gitlab_backup.tar suffix: for 1784800000_2026_07_23_19.1.2_gitlab_backup.tar it is 1784800000_2026_07_23_19.1.2.

After the restore, sign in to the web interface and clone a repository to check that the instance works with its own data.

Additional resources

• Overview
• Omnibus Docker