Merge branch 'geo-docs-overview-refactor' into 'master'

Moved main Geo page and setup instructions

Closes #243513

See merge request gitlab-org/gitlab!40964

doc/administration/geo/disaster_recovery/bring_primary_back.md

@@ -21,7 +21,7 @@ If you have any doubts about the consistency of the data on this node, we recomm
 Since the former **primary** node will be out of sync with the current **primary** node, the first step is to bring the former **primary** node up to date. Note, deletion of data stored on disk like
 repositories and uploads will not be replayed when bringing the former **primary** node back
 into sync, which may result in increased disk usage.
-Alternatively, you can [set up a new **secondary** GitLab instance](../replication/index.md#setup-instructions) to avoid this.
+Alternatively, you can [set up a new **secondary** GitLab instance](../setup/index.md) to avoid this.
 
 To bring the former **primary** node up to date:
 
@@ -37,7 +37,7 @@ To bring the former **primary** node up to date:
    you need to undo those steps now. For Debian/Ubuntu you just need to run
    `sudo systemctl enable gitlab-runsvdir`. For CentOS 6, you need to install
    the GitLab instance from scratch and set it up as a **secondary** node by
-   following [Setup instructions](../replication/index.md#setup-instructions). In this case, you don't need to follow the next step.
+   following [Setup instructions](../setup/index.md). In this case, you don't need to follow the next step.
 
    NOTE: **Note:**
    If you [changed the DNS records](index.md#step-4-optional-updating-the-primary-domain-dns-record)
@@ -50,7 +50,7 @@ To bring the former **primary** node up to date:
    former **primary** node.
 
 If you have lost your original **primary** node, follow the
-[setup instructions](../replication/index.md#setup-instructions) to set up a new **secondary** node.
+[setup instructions](../setup/index.md) to set up a new **secondary** node.
 
 ## Promote the **secondary** node to **primary** node
 

doc/administration/geo/disaster_recovery/index.md

@@ -11,7 +11,7 @@ Geo replicates your database, your Git repositories, and few other assets.
 We will support and replicate more data in the future, that will enable you to
 failover with minimal effort, in a disaster situation.
 
-See [Geo current limitations](../replication/index.md#current-limitations) for more information.
+See [Geo current limitations](../index.md#current-limitations) for more information.
 
 CAUTION: **Warning:**
 Disaster recovery for multi-secondary configurations is in **Alpha**.
@@ -330,7 +330,7 @@ secondary domain, like changing Git remotes and API URLs.
 Promoting a **secondary** node to **primary** node using the process above does not enable
 Geo on the new **primary** node.
 
-To bring a new **secondary** node online, follow the [Geo setup instructions](../replication/index.md#setup-instructions).
+To bring a new **secondary** node online, follow the [Geo setup instructions](../index.md#setup-instructions).
 
 ### Step 6. (Optional) Removing the secondary's tracking database
 
@@ -437,7 +437,7 @@ section to resolve the error. Otherwise, the secret is lost and you'll need to
 
 ### While Promoting the secondary, I got an error `ActiveRecord::RecordInvalid`
 
-If you disabled a secondary node, either with the [replication pause task](../replication/index.md#pausing-and-resuming-replication)
+If you disabled a secondary node, either with the [replication pause task](../index.md#pausing-and-resuming-replication)
 (13.2) or via the UI (13.1 and earlier), you must first re-enable the
 node before you can continue. This is fixed in 13.4.
 

doc/administration/geo/disaster_recovery/planned_failover.md

@@ -27,7 +27,7 @@ have a high degree of confidence in being able to perform them accurately.
 
 ## Not all data is automatically replicated
 
-If you are using any GitLab features that Geo [doesn't support](../replication/index.md#current-limitations),
+If you are using any GitLab features that Geo [doesn't support](../index.md#current-limitations),
 you must make separate provisions to ensure that the **secondary** node has an
 up-to-date copy of any data associated with that feature. This may extend the
 required scheduled maintenance period significantly.

doc/administration/geo/replication/configuration.md

@@ -12,7 +12,7 @@ type: howto
 NOTE: **Note:**
 This is the final step in setting up a **secondary** Geo node. Stages of the
 setup process must be completed in the documented order.
-Before attempting the steps in this stage, [complete all prior stages](index.md#using-omnibus-gitlab).
+Before attempting the steps in this stage, [complete all prior stages](../setup/index.md#using-omnibus-gitlab).
 
 The basic steps of configuring a **secondary** node are to:
 

doc/administration/geo/replication/database.md

@@ -15,7 +15,7 @@ configuration steps. In this case,
 
 NOTE: **Note:**
 The stages of the setup process must be completed in the documented order.
-Before attempting the steps in this stage, [complete all prior stages](index.md#using-omnibus-gitlab).
+Before attempting the steps in this stage, [complete all prior stages](../setup/index.md#using-omnibus-gitlab).
 
 This document describes the minimal steps you have to take in order to
 replicate your **primary** GitLab database to a **secondary** node's database. You may

doc/administration/geo/replication/external_database.md

@@ -135,7 +135,7 @@ has three main functions:
 
 1. Configure the replica database.
 1. Configure the tracking database.
-1. Enable the [Geo Log Cursor](index.md#geo-log-cursor) (not covered in this section).
+1. Enable the [Geo Log Cursor](../index.md#geo-log-cursor) (not covered in this section).
 
 To configure the connection to the external read-replica database and enable Log Cursor:
 

doc/administration/geo/replication/faq.md

@@ -9,7 +9,7 @@ type: howto
 
 ## What are the minimum requirements to run Geo?
 
-The requirements are listed [on the index page](index.md#requirements-for-running-geo)
+The requirements are listed [on the index page](../index.md#requirements-for-running-geo)
 
 ## How does Geo know which projects to sync?
 

doc/administration/geo/replication/location_aware_git_url.md

@@ -44,7 +44,7 @@ In any case, you require:
 - A Route53 Hosted Zone managing your domain.
 
 If you have not yet setup a Geo **primary** node and **secondary** node, please consult
-[the Geo setup instructions](index.md#setup-instructions).
+[the Geo setup instructions](../index.md#setup-instructions).
 
 ## Create a traffic policy
 

doc/administration/geo/replication/security_review.md

@@ -123,7 +123,7 @@ from [owasp.org](https://owasp.org/).
 
 - Geo imposes no additional restrictions on operating system (see the
   [GitLab installation](https://about.gitlab.com/install/) page for more
-  details), however we recommend using the operating systems listed in the [Geo documentation](index.md#requirements-for-running-geo).
+  details), however we recommend using the operating systems listed in the [Geo documentation](../index.md#requirements-for-running-geo).
 
 ### What details regarding required OS components and lock‐down needs have been defined?
 

doc/administration/geo/replication/updating_the_geo_nodes.md

@@ -24,12 +24,12 @@ These general update steps are not intended for [high-availability deployments](
 To update the Geo nodes when a new GitLab version is released, update **primary**
 and all **secondary** nodes:
 
-1. **Optional:** [Pause replication on each **secondary** node.](./index.md#pausing-and-resuming-replication)
+1. **Optional:** [Pause replication on each **secondary** node.](../index.md#pausing-and-resuming-replication)
 1. Log into the **primary** node.
 1. [Update GitLab on the **primary** node using Omnibus](https://docs.gitlab.com/omnibus/update/README.html).
 1. Log into each **secondary** node.
 1. [Update GitLab on each **secondary** node using Omnibus](https://docs.gitlab.com/omnibus/update/README.html).
-1. If you paused replication in step 1, [resume replication on each **secondary**](./index.md#pausing-and-resuming-replication)
+1. If you paused replication in step 1, [resume replication on each **secondary**](../index.md#pausing-and-resuming-replication)
 1. [Test](#check-status-after-updating) **primary** and **secondary** nodes, and check version in each.
 
 ### Check status after updating

doc/administration/geo/replication/using_a_geo_server.md

@@ -9,7 +9,7 @@ type: howto
 
 # Using a Geo Server **(PREMIUM ONLY)**
 
-After you set up the [database replication and configure the Geo nodes](index.md#setup-instructions), use your closest GitLab node as you would a normal standalone GitLab instance.
+After you set up the [database replication and configure the Geo nodes](../index.md#setup-instructions), use your closest GitLab node as you would a normal standalone GitLab instance.
 
 Pushing directly to a **secondary** node (for both HTTP, SSH including Git LFS) was [introduced](https://about.gitlab.com/releases/2018/09/22/gitlab-11-3-released/) in [GitLab Premium](https://about.gitlab.com/pricing/#self-managed) 11.3.
 

doc/administration/geo/setup/index.md

+---
+stage: Enablement
+group: Geo
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+type: howto
+---
+
+# Setting up Geo
+
+These instructions assume you have a working instance of GitLab. They guide you through:
+
+1. Making your existing instance the **primary** node.
+1. Adding **secondary** nodes.
+
+CAUTION: **Caution:**
+The steps below should be followed in the order they appear. **Make sure the GitLab version is the same on all nodes.**
+
+## Using Omnibus GitLab
+
+If you installed GitLab using the Omnibus packages (highly recommended):
+
+1. [Install GitLab Enterprise Edition](https://about.gitlab.com/install/) on the server that will serve as the **secondary** node. Do not create an account or log in to the new **secondary** node.
+1. [Upload the GitLab License](../../../user/admin_area/license.md) on the **primary** node to unlock Geo. The license must be for [GitLab Premium](https://about.gitlab.com/pricing/) or higher.
+1. [Set up the database replication](../replication/database.md) (`primary (read-write) <-> secondary (read-only)` topology).
+1. [Configure fast lookup of authorized SSH keys in the database](../../operations/fast_ssh_key_lookup.md). This step is required and needs to be done on **both** the **primary** and **secondary** nodes.
+1. [Configure GitLab](../replication/configuration.md) to set the **primary** and **secondary** nodes.
+1. Optional: [Configure a secondary LDAP server](../../auth/ldap/index.md) for the **secondary** node. See [notes on LDAP](../index.md#ldap).
+1. [Follow the "Using a Geo Server" guide](../replication/using_a_geo_server.md).
+
+## Post-installation documentation
+
+After installing GitLab on the **secondary** nodes and performing the initial configuration, see the [following documentation for post-installation information](../index.md#post-installation-documentation).

doc/administration/gitaly/praefect.md

@@ -171,7 +171,7 @@ We will note in the instructions below where these secrets are required.
 NOTE: **Note:**
 Do not store the GitLab application database and the Praefect
 database on the same PostgreSQL server if using
-[Geo](../geo/replication/index.md). The replication state is internal to each instance
+[Geo](../geo/index.md). The replication state is internal to each instance
 of GitLab and should not be replicated.
 
 These instructions help set up a single PostgreSQL database, which creates a single point of

doc/administration/index.md

@@ -36,7 +36,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
   - [Omnibus support for log forwarding](https://docs.gitlab.com/omnibus/settings/logs.html#udp-log-shipping-gitlab-enterprise-edition-only) **(STARTER ONLY)**
 - [Reference architectures](reference_architectures/index.md): Add additional resources to support more users.
   - [Installing GitLab on Amazon Web Services (AWS)](../install/aws/index.md): Set up GitLab on Amazon AWS.
-- [Geo](geo/replication/index.md): Replicate your GitLab instance to other geographic locations as a read-only fully operational version. **(PREMIUM ONLY)**
+- [Geo](geo/index.md): Replicate your GitLab instance to other geographic locations as a read-only fully operational version. **(PREMIUM ONLY)**
 - [Disaster Recovery](geo/disaster_recovery/index.md): Quickly fail-over to a different site with minimal effort in a disaster situation. **(PREMIUM ONLY)**
 - [Pivotal Tile](../install/pivotal/index.md): Deploy GitLab as a preconfigured appliance using Ops Manager (BOSH) for Pivotal Cloud Foundry. **(PREMIUM ONLY)**
 - [Add License](../user/admin_area/license.md): Upload a license at install time to unlock features that are in paid tiers of GitLab. **(STARTER ONLY)**

doc/administration/operations/fast_ssh_key_lookup.md

@@ -32,10 +32,10 @@ feature for CentOS 6, follow [the instructions on how to build and install a cus
 
 By default, GitLab manages an `authorized_keys` file, which contains all the
 public SSH keys for users allowed to access GitLab. However, to maintain a
-single source of truth, [Geo](../geo/replication/index.md) needs to be configured to perform SSH fingerprint
+single source of truth, [Geo](../geo/index.md) needs to be configured to perform SSH fingerprint
 lookups via database lookup.
 
-As part of [setting up Geo](../geo/replication/index.md#setup-instructions),
+As part of [setting up Geo](../geo/index.md#setup-instructions),
 you will be required to follow the steps outlined below for both the primary and
 secondary nodes, but note that the `Write to "authorized keys" file` checkbox
 only needs to be unchecked on the primary node since it will be reflected

doc/administration/raketasks/geo.md

 # Geo Rake Tasks **(PREMIUM ONLY)**
 
-The following Rake tasks are for [Geo installations](../geo/replication/index.md).
+The following Rake tasks are for [Geo installations](../geo/index.md).
 
 ## Git housekeeping
 

doc/administration/raketasks/storage.md

@@ -110,7 +110,7 @@ If you find it necessary, you can run this migration script again to schedule mi
 Any error or warning will be logged in Sidekiq's log file.
 
 NOTE: **Note:**
-If [Geo](../geo/replication/index.md) is enabled, each project that is successfully migrated
+If [Geo](../geo/index.md) is enabled, each project that is successfully migrated
 generates an event to replicate the changes on any **secondary** nodes.
 
 You only need the `gitlab:storage:migrate_to_hashed` Rake task to migrate your repositories, but we have additional

doc/administration/reference_architectures/index.md

@@ -147,7 +147,7 @@ is recommended.
 > - Required domain knowledge: Storage replication
 > - Supported tiers: [GitLab Premium and Ultimate](https://about.gitlab.com/pricing/)
 
-[GitLab Geo](../geo/replication/index.md) allows you to replicate your GitLab
+[GitLab Geo](../geo/index.md) allows you to replicate your GitLab
 instance to other geographical locations as a read-only fully operational instance
 that can also be promoted in case of disaster.
 

doc/administration/server_hooks.md

@@ -37,7 +37,7 @@ Note the following about server hooks:
   - [GitLab CI/CD](../ci/README.md).
   - [Push Rules](../push_rules/push_rules.md), for a user-configurable Git hook
     interface. **(STARTER)**
-- Server hooks aren't replicated to [Geo](geo/replication/index.md) secondary nodes.
+- Server hooks aren't replicated to [Geo](geo/index.md) secondary nodes.
 
 ## Create a server hook for a repository
 

doc/development/architecture.md

@@ -304,7 +304,7 @@ repository updates to secondary nodes.
 #### GitLab Geo
 
 - Configuration:
-  - [Omnibus](../administration/geo/replication/index.md#setup-instructions)
+  - [Omnibus](../administration/geo/setup/index.md)
   - [Charts](https://docs.gitlab.com/charts/advanced/geo/)
   - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/geo.md)
 - Layer: Core Service (Processor)

doc/development/documentation/structure.md

@@ -91,7 +91,7 @@ Examples of use cases on feature pages:
 
 - CE and EE: [Issues](../../user/project/issues/index.md#use-cases)
 - CE and EE: [Merge Requests](../../user/project/merge_requests/index.md)
-- EE-only: [Geo](../../administration/geo/replication/index.md)
+- EE-only: [Geo](../../administration/geo/index.md)
 - EE-only: [Jenkins integration](../../integration/jenkins.md)
 
 ## Prerequisites

doc/development/licensed_feature_availability.md

@@ -22,7 +22,7 @@ project.feature_available?(:feature_symbol)
 
 ## Restricting global features (instance)
 
-However, for features such as [Geo](../administration/geo/replication/index.md) and
+However, for features such as [Geo](../administration/geo/index.md) and
 [Load balancing](../administration/database_load_balancing.md), which cannot be restricted
 to only a subset of projects or namespaces, the check will be made directly in
 the instance license.

doc/gitlab-geo/README.md

 ---
-redirect_to: '../administration/geo/replication/index.md'
+redirect_to: '../administration/geo/index.md'
 ---
 
-This document was moved to [another location](../administration/geo/replication/index.md).
+This document was moved to [another location](../administration/geo/index.md).

doc/install/aws/index.md

@@ -799,7 +799,7 @@ to request additional material:
 
 - [Scaling GitLab](../../administration/reference_architectures/index.md):
   GitLab supports several different types of clustering.
-- [Geo replication](../../administration/geo/replication/index.md):
+- [Geo replication](../../administration/geo/index.md):
   Geo is the solution for widely distributed development teams.
 - [Omnibus GitLab](https://docs.gitlab.com/omnibus/) - Everything you need to know
   about administering your GitLab instance.

doc/install/requirements.md

@@ -151,7 +151,7 @@ Support for [PostgreSQL 9.6 and 10 has been removed in GitLab 13.0](https://abou
 
 #### Additional requirements for GitLab Geo
 
-If you're using [GitLab Geo](../administration/geo/replication/index.md):
+If you're using [GitLab Geo](../administration/geo/index.md):
 
 - We strongly recommend running Omnibus-managed instances as they are actively
   developed and tested. We aim to be compatible with most external (not managed

doc/raketasks/README.md

@@ -24,7 +24,7 @@ The following are available Rake tasks:
 | [Elasticsearch](../integration/elasticsearch.md#gitlab-elasticsearch-rake-tasks) **(STARTER ONLY)** | Maintain Elasticsearch in a GitLab instance.                                              |
 | [Enable namespaces](features.md)                                                                    | Enable usernames and namespaces for user projects.                                        |
 | [General maintenance](../administration/raketasks/maintenance.md)                                   | General maintenance and self-check tasks.                                                 |
-| [Geo maintenance](../administration/raketasks/geo.md) **(PREMIUM ONLY)**                            | [Geo](../administration/geo/replication/index.md)-related maintenance.                    |
+| [Geo maintenance](../administration/raketasks/geo.md) **(PREMIUM ONLY)**                            | [Geo](../administration/geo/index.md)-related maintenance.                    |
 | [GitHub import](../administration/raketasks/github_import.md)                                       | Retrieve and import repositories from GitHub.                                             |
 | [Import repositories](import.md)                                                                    | Import bare repositories into your GitLab instance.                                       |
 | [Import large project exports](../development/import_project.md#importing-via-a-rake-task)          | Import large GitLab [project exports](../user/project/settings/import_export.md).         |

doc/user/admin_area/geo_nodes.md

@@ -8,7 +8,7 @@ type: howto
 # Geo nodes Admin Area **(PREMIUM ONLY)**
 
 You can configure various settings for GitLab Geo nodes. For more information, see
-[Geo documentation](../../administration/geo/replication/index.md).
+[Geo documentation](../../administration/geo/index.md).
 
 On the primary node, go to **Admin Area > Geo**. On secondary nodes, go to **Admin Area > Geo > Nodes**.
 

ee/app/views/admin/geo/nodes/index.html.haml

@@ -11,7 +11,7 @@
     = link_to s_("GeoNodes|New node"), new_admin_geo_node_path, class: 'btn btn-success ml-auto qa-new-node-link'
 
 %p.page-subtitle.light
-  = s_('GeoNodes|With %{geo} you can install a special read-only and replicated instance anywhere. Before you add nodes, follow the %{instructions} in the exact order they appear.').html_safe % { geo: link_to('GitLab Geo', help_page_path('administration/geo/replication/index.md'), target: '_blank'), instructions: link_to('setup instructions', help_page_path('administration/geo/replication/index.md', anchor: 'setup-instructions'), target: '_blank') }
+  = s_('GeoNodes|With %{geo} you can install a special read-only and replicated instance anywhere. Before you add nodes, follow the %{instructions} in the exact order they appear.').html_safe % { geo: link_to('GitLab Geo', help_page_path('administration/geo/index.md'), target: '_blank'), instructions: link_to('setup instructions', help_page_path('administration/geo/setup/index.md'), target: '_blank') }
 
 - if @nodes.any?
   #js-geo-nodes{ data: node_vue_list_properties }