In an active/passive configuration, the replica appliance is a redundant copy of the primary appliance. If the primary appliance fails, high availability mode allows the replica to act as the primary appliance, allowing minimal service disruption.

  1. Set up a new GitHub Enterprise appliance on your desired platform. The replica appliance should mirror the primary appliance's CPU, RAM, and storage settings. We recommend that you install the replica appliance in an independent environment. The underlying hardware, software, and network components should be isolated from those of the primary appliance. If you are a using a cloud provider, use a separate region or zone. For more information, see "Provisioning and installation".
  2. In a browser, navigate to the new replica appliance's IP address and upload your GitHub Enterprise license.
  3. Set an admin password that matches the password on the primary appliance and continue.
  4. Click Configure as Replica. Installation options with link to configure your new instance as a replica
  5. Under "Add new SSH key", type your SSH key. Add SSH key
  6. Click Add key, then click Continue.

  7. Connect to the replica appliance's IP address using SSH:

    ssh -p 122 admin@REPLICA IP
    
  8. To generate a key pair for replication, use the ghe-repl-setup command with the primary appliance's IP address and copy the public key that it returns:

    ghe-repl-setup PRIMARY IP
    
  9. To add the public key to the list of authorized keys on the primary appliance, browse to https://<PRIMARY HOSTNAME>/setup/settings and add the key you copied from the replica to the list.

  10. To verify the connection to the primary and enable replica mode for the new replica, run ghe-repl-setup again.

    ghe-repl-setup PRIMARY IP
    
  11. Use the ghe-repl-start command to start replication of the datastores:

    ghe-repl-start
    

    Warning: ghe-repl-start causes a brief outage on the primary server, during which users may see internal server errors. To provide a friendlier message, run ghe-maintenance -s on the primary node before running ghe-repl-start on the replica node to put the appliance in maintenance mode. Once replication starts, disable maintenance mode with ghe-maintenance -u.

  12. Use the ghe-repl-status command to verify the status of each datastore's replication channel:

    ghe-repl-status
    

Creating Geo-replication replicas

This example configuration uses a primary and two replicas, which are located in three different geographic regions.

  1. Create the first replica the same way you would for a standard two node configuration by running ghe-repl-setup on the first replica:

    (replica1)$ ghe-repl-setup PRIMARY IP
    (replica1)$ ghe-repl-start
    
  2. Create a second replica and use the ghe-repl-setup -a command. The -a flag prevents it from overwriting the existing replication configuration and adds the new replica to the configuration:

    (replica2)$ ghe-repl-setup -a PRIMARY IP
    (replica2)$ ghe-repl-start
    
  3. By default replicas are configured to the same datacenter. Configure the replicas for different datacenters by setting a different value for the datacenter option. The specific values can be anything you would like as long as they are different from each other. Run the ghe-repl-node command on each node and specify the datacenter:

    On the primary:

    (primary)$ /usr/local/share/enterprise/ghe-repl-node --datacenter [PRIMARY DC NAME]
    

    On the first replica:

    (replica1)$ /usr/local/share/enterprise/ghe-repl-node --datacenter [FIRST REPLICA DC NAME]
    

    On the second replica:

    (replica2)$ /usr/local/share/enterprise/ghe-repl-node --datacenter [SECOND REPLICA DC NAME]
    

    Tip: You can set the --datacenter and -a options at the same time.

  4. An active replica node will store copies of the appliance data and service end user requests. An inactive node will store copies of the appliance data but will be unable to service end user requests. Enable active mode using the -a flag or inactive mode using the -i flag.

    On the first replica:

    (replica1)$ /usr/local/share/enterprise/ghe-repl-node -a
    

    On the second replica:

    (replica2)$ /usr/local/share/enterprise/ghe-repl-node -a
    
  5. Use the ghe-config-apply command on the primary to apply the configuration:

    (primary)$ ghe-config-apply
    

Configuring DNS for Geo-replication

Configure Geo DNS using the IP addresses of the primary and replica nodes. You can also create a DNS CNAME for the primary node (e.g. primary.github.example.com) to access the primary node via SSH or to back it up via backup-utils.

For testing, you can add entries to the local workstation's hosts file (e.g. /etc/hosts). These example entries will resolve requests for [HOSTNAME] to replica2. You can target specific hosts by commenting out different lines.

# <primary IP>     [HOSTNAME]
# <replica1 IP>    [HOSTNAME]
<replica2 IP>    [HOSTNAME]

Further reading