Are you planning to migrate your GitLab instance to another server? Then you’re in the right place.
There are many reasons to switch to a new cloud provider, whether you need better performance, greater security, or improved scalability.
Whatever your reason, understanding how to approach this transfer correctly is crucial to protecting your valuable GitLab data from loss during the process.
This guide will help you confidently navigate your GitLab instance to its new home with step-by-step instructions.
Pre-migration preparation
Before you begin the migration, you’ll need to ensure both the old and new servers are operating the same version of GitLab. This will prevent compatibility issues during the backup and restore processes, reducing the risk of data loss and errors.
Choose your migration path
When it comes to making sure GitLab is operating on the same version, you have 2 options:
- Upgrade GitLab to the latest version on the old server before migration.
- Install your current version of GitLab on the new server.
The second option is considered the safest and simplest method of migration prep for most users.
Migration steps for the old server
1. Shut down services
Stop GitLab-related services like Unicorn and Sidekiq to ensure data integrity during the backup.
2. Backup the GitLab instance
Create a complete backup of your GitLab data using the gitlab-rake command. Execute gitlab-rake gitlab:backup:create to generate a comprehensive backup of your GitLab data.
3. Secure configuration files
Once you’re sure that the backup is complete, it’s time to safeguard your configuration and SSL files. Keeping these files safe is vital as they’re crucial for restoring GitLab if any issues arise.
Copy the following files to a safe location:
- gitlab.rb: This file contains the main configuration settings for GitLab.
- gitlab-secrets.json: This file holds sensitive information like secret keys and tokens.
- SSL certificates: If you use SSL for secure connections, copy the SSL certificate files to ensure secure communication.
Setting up the new GitLab server
1. Install GitLab
Install the same version of GitLab that was running on your old server. You can find the setup guidelines for different versions on the GitLab website or through their documentation.
2. Transfer data
Securely transfer the backup and configuration files from the old server to the new one. To do this, you can use SSH (Secure Shell) or SCP (Secure Copy Protocol):
scp /path/to/backup_file.tar username@new_server_ip:/path/to/destination
scp /path/to/gitlab.rb username@new_server_ip:/etc/gitlab/
scp /path/to/gitlab-secrets.json username@new_server_ip:/etc/gitlab/
scp -r /path/to/ssl_directory username@new_server_ip:/etc/gitlab/ssl/
- Replace /path/to/ with the actual path where your files are located.
- Substitute username with your username on the new server and replace new_server_ip with the IP address or hostname of the new server.
- Switch /path/to/destination with the directory where you want to store the backup file on the new server.
3. Restore GitLab
After transferring the necessary files, you can restore GitLab to the new server using the backup file. Run the following command:
sudo gitlab-rake gitlab:backup:restore BACKUP=backup_file_name
Replace backup_file_name with the name of the backup file you transferred to the new server. This command will restore your GitLab instance to its previous state, including repositories, configurations, and settings.
Post-migration checks
1. Verify the installation
Make sure all the GitLab services are up and running smoothly on the server. This involves checking services like Unicorn, Sidekiq, and the GitLab web interface.
Also, verify that important data like repositories, user accounts, and project settings are all in place and can be accessed without issues.
2. Sanity check
Run the command sudo gitlab-rake gitlab:check SANITIZE=true to confirm GitLab’s complete installation and configuration.
This command will verify various aspects of GitLab’s setup, including database integrity, file permissions, and configuration settings. The SANITIZE=true flag ensures that sensitive information is not displayed in the output.
Common issues and troubleshooting
1. Version incompatibility
As mentioned earlier, both your old and new GitLab server must run the same GitLab version. Incompatibility between versions can lead to errors during the restoration process, potentially causing data loss or corruption.
2. Missing data
If you notice data like Git repository hashes or wiki files aren’t showing up correctly after the transfer, verify the file permissions and ownership on the server. Incorrect permissions or ownership can cause issues with GitLab’s ability to accurately access and display the data.
3. Continuous Integration (CI) failures
After migrating, if GitLab CI jobs start failing unexpectedly, it’s essential to review the configurations of CI runners. Also, make sure that services like Redis or databases are set up correctly and can be accessed by GitLab on the server.
4. Data loss
Data loss is another common issue when migrating GitLab to a new server. Third-party backup solutions can help with data loss and corruption during migration. They automatically backup all your GitLab data regularly, giving you a safety net if anything goes wrong during migration.
This proactive approach prevents potential data disasters and keeps downtime to a minimum. This keeps the DevOps machinery running smoothly for businesses heavily dependent on GitLab.
Backup GitLab with BackupLABS
Designed to protect your GitLab data during server migrations, BackupLABS is your go-to for protecting your vital information.
With GitLab Backup, your team can be confident that crucial project data is shielded from mishaps. And if the worst happens, restoring your lost data is simple and efficient.
Benefits of BackupLABS:
- No code/scripting: Our user-friendly interface allows you to back up and restore your data with simple point-and-click actions. No scripting or coding is needed.
- Ransomware protection: Your GitLab information is protected from malicious attacks, ransomware, and potential security breaches.
- Compliance: Enjoy accurate and easily-accessible records of your data history to ensure compliance with data regulations.
- Daily reporting: You’ll receive daily updates on yourtheir GitLab data backup status for complete transparency and peace of mind.
- Dedicated support 24/7: BackupLABS offers a round-the-clock support team to assist with any issues, day or night.
Discover more about our GitLab backups at BackupLABS.
