GitLab Geo configuration
- Setting up GitLab
- Next steps
- Selective replication
- Replicating wikis and repositories over SSH
Note: This is the documentation for the Omnibus GitLab packages. For installations from source, follow the GitLab Geo nodes configuration for installations from source guide.
Note: Stages of the setup process must be completed in the documented order. Before attempting the steps in this stage, complete all prior stages.
This is the final step you need to follow in order to setup a Geo node.
You are encouraged to first read through all the steps before executing them in your testing/production environment.
- Do not setup any custom authentication in the secondary nodes, this will be handled by the primary node.
- Do not add anything in the secondaries Geo nodes admin area (Admin Area ➔ Geo Nodes). This is handled solely by the primary node.
After having installed GitLab Enterprise Edition in the instance that will serve as a Geo node and set up the database replication, the next steps can be summed up to:
- Replicate some required configurations between the primary and the secondaries
- Configure a second, tracking database on each secondary
- Start GitLab on the secondary node's machine
This is the last step of configuring a Geo secondary node. Make sure you have followed the first two steps of the Setup instructions:
- You have already installed on the secondary server the same version of GitLab Enterprise Edition that is present on the primary server.
- You have set up the database replication.
- Your secondary node is allowed to communicate via HTTP/HTTPS with your primary node (make sure your firewall is not blocking that).
- Your nodes must have an NTP service running to synchronize the clocks. You can use different timezones, but the hour relative to UTC can't be more than 60 seconds off from each node.
GitLab stores a unique encryption key in disk that we use to safely store
sensitive data in the database. Any secondary node must have the
exact same value for
db_key_base as defined in the primary one.
SSH into the primary node and login as root:
Execute the command below to display the current encryption key and copy it:
SSH into the secondary node and login as root:
Add the following to
encryption-keywith the output of the previous command:
gitlab_rails['db_key_base'] = 'encryption-key'
Reconfigure the secondary node for the change to take effect:
Once reconfigured, the secondary will start automatically replicating missing data from the primary in a process known as backfill. Meanwhile, the primary node will start to notify changes to the secondary, which will act on those notifications immediately. Make sure the secondary instance is running and accessible.
Warning Hashed storage is in Beta. It is considered experimental and not production-ready. For the latest updates, check issue. Hashed Storage is not required to run GitLab Geo, but in some edge cases race conditions can lead to errors and Geo to break. Known issues are renaming a project multiple times in short succession, deleting a project and recreating with the same name very quickly.
Using hashed storage significantly improves Geo replication - project and group renames no longer require synchronization between nodes.
- Visit the primary node's Admin Area ➔ Settings
/admin/application_settings) in your browser
Repository Storagessection, check
Create new projects using hashed storage paths:
You can safely skip this step if your primary uses a CA-issued HTTPS certificate.
If your primary is using a self-signed certificate for HTTPS support, you will need to add that certificate to the secondary's trust store. Retrieve the certificate from the primary and follow these instructions on the secondary.
You can monitor the status of the syncing process on a secondary node
by visiting the primary node's Admin Area ➔ Geo Nodes (
in your browser.
Please note that if
git_data_dirs is customized on the primary for multiple
repository shards you must duplicate the same configuration on the secondary.
Disabling a secondary node stops the syncing process.
The two most obvious issues that replication can have here are:
- Database replication not working well
- Instance to instance notification not working. In that case, it can be
something of the following:
- You are using a custom certificate or custom CA (see the Troubleshooting section)
- Instance is firewalled (check your firewall rules)
Currently, this is what is synced:
- Git repositories
- LFS objects
- Issue, merge request, snippet and comment attachments
- User, group, and project avatars
Your nodes should now be ready to use. You can login to the secondary node
with the same credentials as used in the primary. Visit the secondary node's
Admin Area ➔ Geo Nodes (
/admin/geo_nodes) in your browser to check if it's
correctly identified as a secondary Geo node and if Geo is enabled.
If your installation isn't working properly, check the troubleshooting section.
Point your users to the "Using a Geo Server" guide.
With GitLab 9.5, GitLab Geo now supports the first iteration of selective replication, which allows admins to choose which groups should be replicated by secondary nodes.
It is important to notice that selective replication:
- Does not restrict permissions from secondary nodes.
- Does not hide projects metadata from secondary nodes. Since Geo currently relies on PostgreSQL replication, all project metadata gets replicated to secondary nodes, but repositories that have not been selected will be empty.
- Secondary nodes won't pull repositories that do not belong to the selected groups to be replicated.
Warning: In GitLab 10.2, replicating repositories and wikis over SSH was deprecated. Support for SSH replication will be removed in 10.3. These instructions should only be used if you need to add a new secondary in the short term.
SSH into the secondary node and login as root:
Add the primary's SSH key fingerprint to the
sudo -u git -H ssh git@<primary-node-url>
<primary-node-url>with the FQDN of the primary node. You should manually check the displayed fingerprint against a trusted record of the expected value before accepting it!
Generate a passphraseless SSH keypair for the
gituser, and capture the public component:
test -e ~git/.ssh/id_rsa || sudo -u git -H ssh-keygen -q -t rsa -b 4096 -f ~git/.ssh/id_rsa cat ~git/.ssh/id_rsa.pub
Follow the steps above to set up the new Geo node. When you reach
Step 4: Enabling the secondary GitLab node
select "SSH (deprecated)" instead of "HTTP/HTTPS", and populate the "Public Key"
with the output of the previous command (beginning
See the updating the Geo nodes document.
See the troubleshooting document.