Setting up Geo
Offering: Self-managed
Prerequisites
- Two (or more) independently working GitLab sites:
- One GitLab site serves as the Geo primary site. Use the GitLab reference architectures documentation to set this up. You can use different reference architecture sizes for each Geo site. If you already have a working GitLab instance that is in-use, it can be used as a primary site.
- The second GitLab site serves as the Geo secondary site. Use the GitLab reference architectures documentation to set this up. It’s a good idea to sign in and test it. However, be aware that all of the data on the secondary are lost as part of the process of replicating from the primary site.
Geo supports multiple secondaries. You can follow the same steps and make any changes accordingly. - Ensure the primary site has a GitLab Premium or Ultimate subscription to unlock Geo. You only need one license for all the sites.
- Confirm the requirements for running Geo are met by all sites. For example, sites must use the same GitLab version, and sites must be able to communicate with each other over certain ports.
- Confirm the primary and secondary site storage configurations match. If the primary Geo site uses object storage, the secondary Geo site must use it too. For more information, see Geo with Object storage.
- Ensure clocks are synchronized between the primary site and the secondary site. Synchronized clocks are required for Geo to function correctly. For example, if the clock drift between the primary and secondary sites exceeds 1 minute, replication fails.
Using Linux package installations
If you installed GitLab using the Linux package (highly recommended), the process for setting up Geo depends on whether you need to set up a single-node Geo site or a multi-node Geo site.
Single-node Geo sites
If both Geo sites are based on the 1K reference architecture, follow Set up Geo for two single-node sites.
If using external PostgreSQL services, for example Amazon RDS, follow Set up Geo for two single-node sites (with external PostgreSQL services).
Depending on your GitLab deployment, additional configuration for LDAP, object storage, and the container registry might be required.
Multi-node Geo sites
If one or more of your sites is using the 40 RPS / 2,000 user reference architecture or larger, see Configure Geo for multiple nodes.
Depending on your GitLab deployment, additional configuration for LDAP, object storage, and the container registry might be required.
General steps for reference
- Set up the database replication based on your choice of PostgreSQL instances (
primary (read-write) <-> secondary (read-only)
topology): - Configure GitLab to set the primary and secondary sites.
- Follow the Using a Geo Site guide.
Depending on your GitLab deployment, additional configuration for LDAP, object storage, and the container registry might be required.
Additional configuration
Depending on how you use GitLab, the following configuration might be required:
- If the primary site uses object storage, configure object storage replication for the secondary sites.
- If you use LDAP, configure a secondary LDAP server for the secondary sites. For more information, see LDAP with Geo.
- If you use the container registry, configure the container registry for replication on the primary and secondary sites.
You should configure unified URLs to use a single, unified URL for all Geo sites.
Using GitLab Charts
Configure the GitLab chart with GitLab Geo.
Geo and self-compiled installations
Geo is not supported when you use a self-compiled GitLab installation.
Post-installation documentation
After installing GitLab on the secondary sites and performing the initial configuration, see the following documentation for post-installation information.