Note: There is a maximum of 8 high availability replicas (both passive and active/geo replicas) allowed for GitHub Enterprise Server.
Set up a new GitHub Enterprise Server 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 "Setting up a GitHub Enterprise Server instance."
Ensure that the new appliance can communicate with all other appliances in this high availability environment over ports 122/TCP and 1194/UDP. For more information, see "Network ports."
In a browser, navigate to the new replica appliance's IP address and upload your GitHub Enterprise license.
Set an admin password that matches the password on the primary appliance and continue.
Click Configure as Replica.
Under "Add new SSH key", type your SSH key.
Click Add key.
Connect to the replica appliance's IP address using SSH.
ssh -p 122 admin@REPLICA_IP
To generate a key pair for replication, use the
ghe-repl-setupcommand with the primary appliance's IP address and copy the public key that it returns.
To add the public key to the list of authorized keys on the primary appliance, browse to
https://PRIMARY-HOSTNAME/setup/settingsand add the key you copied from the replica to the list.
To verify the connection to the primary and enable replica mode for the new replica, run
To start replication of the datastores, use the
ghe-repl-startcauses a brief outage on the primary server, during which users may see internal server errors. To provide a friendlier message, run
ghe-maintenance -son the primary node before running
ghe-repl-starton the replica node to put the appliance in maintenance mode. Once replication starts, disable maintenance mode with
ghe-maintenance -u. Git replication will not progress while the primary node is in maintenance mode.
To verify the status of each datastore's replication channel, use the
This example configuration uses a primary and two replicas, which are located in three different geographic regions. While the three nodes can be in different networks, all nodes are required to be reachable from all the other nodes. At the minimum, the required administrative ports should be open to all the other nodes. For more information about the port requirements, see "Network ports."
For high availability, the latency between the network with the active nodes and the network with the passive nodes must be less than 70 milliseconds. We don't recommend configuring a firewall between the two networks. If latency is more than 70 milliseconds, we recommend cache replica nodes instead. For more information, see "Configuring a repository cache."
Create the first replica the same way you would for a standard two node configuration by running
ghe-repl-setupon the first replica.
(replica1)$ ghe-repl-setup PRIMARY_IP (replica1)$ ghe-repl-start
Create a second replica and use the
ghe-repl-setup --addcommand. The
--addflag prevents it from overwriting the existing replication configuration and adds the new replica to the configuration.
(replica2)$ ghe-repl-setup --add PRIMARY_IP (replica2)$ ghe-repl-start
By default, replicas are configured to the same datacenter, and will now attempt to seed from an existing node in 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-nodecommand on each node and specify the datacenter.
On the primary:
(primary)$ ghe-repl-node --datacenter [PRIMARY DC NAME]
On the first replica:
(replica1)$ ghe-repl-node --datacenter [FIRST REPLICA DC NAME]
On the second replica:
(replica2)$ ghe-repl-node --datacenter [SECOND REPLICA DC NAME]
Tip: You can set the
--activeoptions at the same time.
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
--activeflag or inactive mode using the
On the first replica:
(replica1)$ ghe-repl-node --active
On the second replica:
(replica2)$ ghe-repl-node --active
To apply the configuration, use the
ghe-config-applycommand on the primary.
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
For testing, you can add entries to the local workstation's
hosts file (for example,
/etc/hosts). These example entries will resolve requests for
replica2. You can target specific hosts by commenting out different lines.
# <primary IP> HOSTNAME # <replica1 IP> HOSTNAME <replica2 IP> HOSTNAME