Installation Guide

This guide describes how to install Git MultiSite (GitMS):

• Pre-installation requirements
• A standard installation
• Node configuration

1. Before you install

Before installing GitMS, make sure that you have sufficient hardware and that all required software is configured appropriately.

1.1 Skills requirements

This section describes the knowledge and technical requirements for deployment and operation of the WANdisco software. Make sure that you can meet the requirements before you begin the deployment.

If you would like help assessing your requirements, request a supported installation from WANdisco.

One administrator can manage all the systems running MultiSite. However, we recommend that you someone at each site who is familiar with MultiSite Basics.

1.2 Deployment overview

We recommend that you follow a well-defined plan for your WANdisco GitMS deployment. This helps you keep control, understand the product, and find and fix any issues before production. We recommend that you include the following steps:

1. Pre-deployment planning: Identify the requirements, people, and skills needed for deployment and operation. Agree a schedule and milestones. Highlight any assumptions, constraints, dependencies, and risks to a successful deployment.

2. Deployment preparation: Prepare and identify server specifications, locations, node configuration, repository set-up, replication architecture, and the server and software configurations.

3. Testing phase: Actions for an initial installation and testing in a non-production environment, executing test cases, and verifying deployment readiness.

4. Production deployment: Actions to install, configure, test, and deploy the production environment.

5. Post-deployment operations and maintenance: Actions including environment monitoring, system maintenance, training, and in-life technical support.

1.3 System requirements

This section describes how to prepare your Git servers for replication. You need to ensure that you've got a suitable platform, with sufficient hardware and compatible versions of the required software that is configured appropriately. Use this information as a guide, not as a fixed set of requirements.

1.3.1 Hardware recommendations

* For small deployments it should be possible to run with 8GB of system memory. However, if you are going to run additional services such as Gerrit on the same server then 16GB is the minimum system memory requirement. For GitMS/Gerrit deployments with large numbers (i.e. more than hundreds) of users, you should increase the minimum memory requirement to 32GB or 48GB.

1.3.2 Storage tips

• Use separate physical disks for Git and GitMS.
• Use the fastest possible disks for storage. Disk IO is the critical path to improve repository responsiveness.
• We recommend that you use RAID-1 or RAID-2 solutions. We do not recommend RAID-0.
  Knowledgebase
  For more information about calculating storage capacity requirements, read the Knowledgebase article, Hardware Sizing Guide.

1.3.3 Processor tips

• GitMS can run on a single 2GHz CPU, but for production you should run fast multi-core CPUs and scale the number of physical processors based on your peak concurrent usage.
• Aim to have no more than 15 concurrent Git users per CPU and 7 concurrent users per CPU core.
  Example 1: A server with 4 physical single core processors is expected to support (15x1x4) = 60 concurrent users.
  Example 2: A server with 4 physical processors, each being a quad core is expected to support (7x4x4) = 112 concurrent users.

1.4 Setup requirements

This is a summary of requirements. You must also check the more detailed Installation checklist.

1.4.1 MultiSite servers

This section summarises requirements:

• The same operating system
• Java and Python installed
• A browser with network access to all servers
• A commandline compression utility
• A unique license key file provided by WANdisco. You will need one for each node and you may need to provide the server IP addresses.

1.4.2 Git installations

Git installation requires:

• WANdisco's modified distribution of Git, 2.3.1

  Make sure you don't overwrite the WANdisco Git binaries with system versions. The WANdisco versions are required for replication to work correctly.

• Matching file and directory-level permissions on repositories
  Requirement
  You must run Git and GitMS on the same server.
  Alert
  A repository can belong to only one replication group at a time.

1.4.3 Repository consistency

Although it is recommended that repositories are identical, the hooks directory can differ if site to site variances require it. However, file and directory level permissions on all repositories do need to match.

The list below details which contents of the root directories need to match between servers, and those which don't:

/conf

Strongly recommend that the contents match between replicas

/db

As this is where repository data is stored it is crucial that this is a perfect match between servers

locks

Locks must be synced between nodes. You can't afford for a commit to be rejected on one site that was allowed on all the others.

hooks

Normally the same hooks should be installed in all Git repositories. However if policies differ from site to site then hooks can be different. Note, if using GerritMS do not install Git hooks as it fires specific Gerrit hooks.

The replicated hooks that are currently supported are:

• pre-receive
• update
• post-update
• post-receive
• rp-post-update
• rp-post-receive

See hooks for more information.

2. Installation checklist

Though you may have referred to the checklist before evaluating GitMS, we strongly recommend that you reread it before deployment to confirm that your system still meets all requirements.

ulimit -u unlimited && ulimit -f unlimited && ulimit -n 64000

# Default limit for number of user's processes to prevent
      # accidental fork bombs.
      # See rhbz #432903 for reasoning.
      * soft nproc 1024   <- Increase this limit or ulimit -u will be reset to 1024
      # The asterisk changes values for all users. If you want to change for a specific user, replace it with the username:
      gitms soft nproc 65000
      gitms hard nproc 65000
      gitms soft nofile 65000
      gitms hard nofile 65000
      gitms soft 

      gitms           soft    nofile  65000
      gitms           hard    nofile  65000
      gitms           soft    nproc   65000
      gitms           hard    nproc   65000

session  required  pam_limits.so

session  required  pam_limits.so

3. Installation

This Installation Guide describes setting up GitMS for the first time. If you are upgrading from an earlier version of GitMS you should also follow this procedure. GitMS is a completely new class of product so it's not possible to follow a shortcut upgrade procedure.

3.1 Installation overview

This is an overview of the process:

1. Double-check the Installation checklist. Take time to make sure that you have everything set up and ready. This avoids problems during installation. In particular, check:
   • Git authentication: Git is installed, and using authentication.
   • JDK: You need to run an Oracle JDK. We recommend JDK 7, but 6 works, with warnings.
   • Java memory settings: The Java process on which GitMS runs is assigned a minimum and maximum amount of system memory. By default it gets 128MB at startup and 4GB maximum.
   • System resources: Ensure that your system is going to operate with a comfortable margin.
2. Ensure that your repositories are copied into place on all nodes.
3. Download and copy the MultiSite files into place.
4. Run the setup, then complete the installation from a web browser.

3.2 Before you start

1. Check through the Installation checklist.

   If running with Access Control/Flume
   If you are following on from a previous installation/upgrade that was done using root, all subsequent upgrades also need to be run using root.

2. Ensure that you have WANdisco's latest Git binaries pre-installed. GitMS edition requires FSFSWD libraries that are built into WANdisco's version of Git.
3. Repositories need to be created using the file system switch (--fs-type fsfswd).
4. Ensure that the system user used for installing GitMS has access to Java, otherwise the installation fails.
5. At the end of an installation (when including auditing functionality), you'll currently see an error message:

   
   Do you want to continue with the installation? (Y/n) y
   Installing Apache Flume to /opt/wandisco/flume-git-multisite
   WARNING: Cannot read /opt/wandisco/git-multisite/replicator/logs/gitms.log
   Stopping flume: [OK]
   Starting flume: [OK]
   Starting ui: [OK]
   Checking if the GUI is listening on port 8080: ............Done
   
   Please visit http://<thisHost>:8080/ to finish the installation
   
   Installation Complete

   You can ignore this error, the missing log file is not created by the system at this stage. It is created once the Git MultiSite replicator is first started, after the installation is complete.

 export LOG_FILE="opt/wandiscoscp/log/file.file"

3.3 Install GitMS

1. Extract the setup file.
2. Save the wandisco-git-multisite.sh installer file to your Installation site.
3. Make the script executable, e.g. enter the command:

   chmod a+x wandisco-git-multisite.sh

   Workaround if /tmp directory is "noexec"
   Running the installer script will write files to the system's /tmp directory. If the system's /tmp directory is mounted with the "noexec" option then you will need to use the following argument when running the installer:
   --target <someDirectoryWhichCanBeWrittenAndExecuted>
   E.g.

   ./git-multisite.sh --target /opt/wandisco/installation/

4. Run the setup script:

     [root@redhat6 ~]# chmod a+x git-multisite.sh
     [root@redhat6 ~]# ./git-multisite.sh
     Verifying archive integrity... All good.
     Uncompressing WANdisco MultiSite .......
         ::   ::  ::     #     #   ##    ####  ######   #   #####   #####   #####
        :::: :::: :::    #     #  #  #  ##  ## #     #  #  #     # #     # #     #
       ::::::::::: :::   #  #  # #    # #    # #     #  #  #       #       #     #
      ::::::::::::: :::  # # # # #    # #    # #     #  #   #####  #       #     #
       ::::::::::: :::   # # # # #    # #    # #     #  #        # #       #     #
        :::: :::: :::    ##   ##  #  ## #    # #     #  #  #     # #     # #     #
         ::   ::  ::     #     #   ## # #    # ######   #   #####   #####   #####
   
   
     INFO: Using the following Memory settings:
   
     INFO: UI:         -Xms128m -Xmx1024m
     INFO: Replicator: -Xms1024m -Xmx4096m
   
     Do you want to use these settings for the installation? (Y/n)
     

5. Enter Y and click Enter.

   Which port should the MultiSite UI listen on? [8080]:

   Running Gerrit?
   If you are going to integrate GitMS with Gerrit then make sure that you select a port that will not conflict. Gerrit also defaults to port 8080.

6. Confirm the port that you want to run the admin interface on:

   We strongly advise against running Git MultiSite as the root user.
   
     Which user should Git MultiSite run as?

7. Confirm the user who will run GitMS:

   This user will need to have read and write access to your git repos

8. Which group should Git MultiSite run as?

9. Confirm the group of the user running GitMS:

   Installing with the following settings:
   
   MultiSite user:    gitms
   MultiSite group:   gitms
   MultiSite UI Port: 8080
   MultiSite UI Minimum memory: 128
   MultiSite UI Maximum memory: 1024
   MultiSite Replicator Minimum memory: 1024
   MultiSite Replicator Maximum memory: 4096
   
   Do you want to continue with the installation? (Y/n)

10. Confirm the configuration settings and enter Y to finish the install. In our example, our server runs as gitms with a group of gitms.
11. Open a browser and go to the provided URL. If your server's DNS isn't running you can go to the next step at the following address:

    http://<IP_Adress>:<admin port>/multisite-local

    e.g. http://10.0.100.252:8080/

    Flush your browser cache
    If you are reinstalling and using SSL, then you should clear your browser cache before you continue. Previous SSL details are stored in the cache and will cause SSL errors if they are not flushed.

12. The web installer begins with the Welcome screen:
    
    

    Set up > Start

    Welcome to Git MultiSite.
    
    You're about to run through the installation, which should only take a couple of minutes.
    
    If you run into difficulties on the way, check our documentation or talk to our support team through the Customer upport Website.
    
    Before you click Next, make sure you Read the Installation Checklist
    

13. Click Next to begin the installation.
14. The next screen contains the WANdisco Master Subscription Agreement and Terms & Conditions. To continue the installation click the I Agree button.
    

    Set up > License agreement

15. On the next screen, License Upload, you are prompted to browse for your product license key file. Click the Browse button and locate your file. You received this from the WANdisco sales team. Contact them if you have any problems locating or using your license file.
    

    Set up > license.key file

16. On the Administrator Setup screen enter the username plus an associated password that you will use to log in to Git MultiSite's UI. This information is only added during the installation of the first "inductor" node.
    

    Set up > Admin settings, entered or uploaded in the users.properties file

    Username

    The administrator's username.

    Password

    The administrator's password.

    Confirm Password

    Enter your password again to confirm correct entry.

    User Interface HTTP Port

    You entered the port during the first part of the installation. You can now choose an alternate port here.
    This port is sometimes referred to as the jetty port.

    For all subsequent node installations you should provide the users.properties file.
    Working with the user.properites file
    

    This properties file stores the unique information for the default admin user account. It is essential that this information exactly matches up between nodes. For this reason, it is only entered once during a deployment and then subsequently copied to all other nodes in the form of the users.properties file.

    The default location of the file is:

    /opt/wandisco/git-multisite/replicator/properties/users.properties

    If something goes wrong and you don't have a valid users.properties file in your deployment, Git MultiSite can automatically create a new one if you follow the procedure to Create a new users.properties file.

    

    Set up > user.properties file for all nodes after the first node

17. The last screen in the setup process covers Server Settings:

    Set up > Server Settings

    Node ID

    The default name for this node.

    Temporary limitation
    Node names cannot contain spaces or periods.

    Node IP/Host

    The node's IP or hostname. If the server is multi-homed, you can select the IP to which you want Git MultiSite to be associated.
    

    Enter FQDN in this field
    We strongly recommend that you use fully qualified domain names for IP addresses. This can avoid SSL certification problems.

    Replication Port

    Select the port to use for replicated Git repository data. Default=6444.

    Content Server Port

    Select the port to use to transfer replicated content (repository changes). Default=4321. This is different from the port used by WANdisco's DConE² agreement engine.

    Content Node Count

    This setting gives you the ability to enforce a degree of resiliance. The value represents the number of nodes within a membership that must receive the content before a proposal is submitted for agreement. If the value is greater than the total learners in the current membership, it is adjusted to total learners in the current membership. The proposing node is not considered in the calculation.

    Minimum Content Nodes Required

    Ticking this checkbox will enforce the Content Node Count as a prerequisite for replication.

    REST API Port

    The port to be used for Git MultiSite's REST-based API. Default=8082.

    REST API UI Using SSL

    Check box for enabling the use of SSL for all API traffic.

    REST API SSL Port

    The port to be used for Git MultiSite's REST-based API when traffic is secured using SSL encryption. Default=8445.

    UI Port

    The port for HTTP access to the MultiSite administrative interface. Default=8080.

    UI SSL Port

    The port for HTTPS encrypted access to the MultiSite administrative interface. Default=8443.

    SSL Certificate Alias

    The name of your SSL Certificate file.

    SSL Key Password

    The password for your HTTPS service.

    SSL Key Store

    The name of the keystore file. The keystore contains the public keys of authorized users.

    SSL Key Store Password

    The password associated with the keystore.

    SSL Trust Store

    The location of your truststore file. The truststore contains CA certifcates to trust. If your server's certificate is signed by a recognized Certification Authority (CA), the default truststore that ships with the JRE will already trust it because it already trusts trustworthy CAs. Therefore, you don't need to build your own, or to add anything to the one from the JRE.

    SSL Trust Store Password

    The password for your truststore.

    Truststores and key stores
    

    You might be familiar with the Public key system that allows two parties to use encryption to keep their communications with each other private (incomprehensible to an intercepting third-party).

    The keystore is used to store the public and private keys that are used in this system. However, iIn isolation, however, the system remains susceptible to the hijacking of the public key file, where an end user may receive a fake public key and be unaware that it will enable communication with an impostor.

    Enter Certificate Authorities (CAs). These trusted third parties issue digital certificates that verify that a given public key matches with the expected owner. These digital certificates are kept in the truststore. An SSL implementation that uses both keystore and truststore files offers a more secure SSL solution.

18. Click FINISH when you have entered everything. The installer now completes the configuration.
19. Click the START USING MULTISITE button that appears. Click the button to log in for the first time.
20. Log in. Enter the username and password chosen ealier in the process then click FINISHED - LET'S GO!.
21. The first time you view the dashboard, it contains mostly blank areas. Read the Reference Guide to learn what the buttons and options mean.

3.4 Non-interactive installation

You can now install GitMS non-interactively. Set the following environment variables:

GITMS_USER

The system user that runs GitMS.

GITMS_GROUP

The system group that GitMS runs in.

GITMS_UI_PORT

The TCP port that the browser UI initially uses. You can change this during the browser-based setup.

GITMS_UMASK

Set your required Umask settings. We validate your entry so that it must be a 3-digit number that begins with a zero, e.g. 077. Note: The first digit signifies the base of the number (octal) so 0777 is a 3-digit number. The product installs using 0022 or 022, but always shows 0022 when installing.

Optional variables:

GITMS_UI_MEM_LOW

The minimum amount of UI memory.

GITMS_UI_MEM_HIGH

The maximum amount of UI memory.

GITMS_REP_MEM_LOW

The minimum amount of Replicator memory.

GITMS_REP_MEM_HIGH

The maximum amount of Replicator memory.

For a scripted start to the installation run:

  GITMS_USER=wandisco
  GITMS_GROUP=wandisco
  GITMS_UI_PORT=8181
  GITMS_UMASK=0777
  export GITMS_USER GITMS_GROUP GITMS_UI_PORT GITMS_UMASK
  ./git-multisite.sh
  

The installation then runs without user interaction. When installation is complete, the browser-based UI starts. You then need to complete the node set up from step 10.

3.5 Repeat installation at all sites

Repeat the installation process for every node required to share your Git repositories.

You may benefit from creating an image of your initial server, with the repositories in place and using this as a starting point on your other sites. This helps ensure that your replicas are in exactly the same state.

4. Node induction

After installing Git MultiSite at all sites, you need to make the sites aware of each other through the node induction process. Carefully follow the steps in this section.

4.1 Membership induction

You must connect nodes in a specific sequence. Follow these steps to ensure that your sites can talk to each other:

1. When Git MultiSite is installed on all your sites, select one node to be your Inductor. This node will accept requests for membership and share its existing membership information. You can select any node.
   
2. Log in to this Inductor's admin console, http://<Inductor's IP>:8080/multisite-local/, and get the following information, mainly from the SETTINGS tab.
   
   All your remaining sites are now classed as inductees.
3. Select one of your remaining inductee sites. Connect to its web admin console, http://<Inductee1:8080/multisite-local/, and go to the Nodes tab.
4. Click the Connect to Node button and enter the details that you collected from your inductor node.
   
   

   Node ID*

   The name of the inductor node. You can verify this from the NODE ID entry on the inductor node's SETTINGS tab, see step 2.

   Node Location ID*

   The reference code that defines the inductor node's location. You can verify this from the NODE ID entry on the inductor node's SETTINGS tab, see step 2.

   Node IP Address*

   The IP address of the inductor node server.

   Node Port No*

   The DConE Port number, 6444 by default, defined on the inductor node's SETTINGS tab.

   When you have entered these details, click the Send Connection Request button. The inductor node accepts the request and adds the inductee to its membership. Refresh your browser to see that this has happened..

5. Go back to step 3 and select one of your remaining inductees. Repeat this process until all the sites that you want to be included in the current membership have been connected to the inductor.

4.2 Create a replication group

GitMS lets you share specific repositories between selected sites. Do this by creating Replication Groups that contain a list of sites and the specific repositories that they will share. For example, this figure shows 4 sites running 2 replication groups. Replication Group 1 replicates Repo1 across all four sites, while Replication Group 2 replicates repo2 across a subset of sites.

Four sites running two replication groups

Follow this procedure to create a Replication Group. You can create as many replication groups as you like. However, each repository can only be part of one active replication group at a time:

1. When you have sites defined, click the REPLICATION GROUPS tab. Then click on the Create Replication Group button.
   
   

   Create Replication Group

   Local node automatically made the first member
   You cannot create a replication group remotely. The node on which you are creating the group must itself be a member. For this reason, when creating a replication group, the first node is added automatically.
2. Enter a name for your Replication Group in the Replication Group Name field. Then enter an existing Node name in the Add Sites field. All existing sites that match your entry will appear. Click to select them. Instead of typing in a name you can click the drop-down button and choose from a list of existing sites that are not already members of the new group.
   
   You can select any number of available sites. The sites that you select will appear as clickable buttons in the Add Node field.
   

   Enter a name and add some nodes

3. New sites are added as Active Voters, denoted by "AV". You can change the type of a node by clicking on its label. For an explanation of what each node type does, see the Reference Guide section, Guide to node types.
   

   Change node type

   When you have added all sites and configured their type, click Create Replication Group to see a group's details.
4. Replication Groups that you create are listed on the REPLICATION GROUPS tab.
   

   Groups boxes

   Click View to view your options.

Important: Don't cancel replication group creation tasks
If you create a new replication group, then find that the task is stuck in pending because one of your nodes is down, do not use the Cancel Tasks option on the Dashboard's Pending Tasks table.
If, when all nodes are up and running, the replication group creation tasks are still not progressing, please contact the WANdisco support team for assistance.

4.3 Add repositories

When you have added at least one Replication Group you can add repositories to your node:

1. Click the REPOSITORIES tab, then click Add.
   
   

   REPOSITORIES > Add

2. Enter the Repository's name, the file system path (full path to the repository), and use the drop-down to select the replication group. You can set the repository to be read-only by ticking the Global Ready-only. You can deselect this later. Click ADD REPO.
   
   

   REPOSITORIES > Enter details > ADD REPO

Alert
If a repository that you added gets stuck in the deploying state, the Dashboard Replicator Tasks window notifies you. Cancel the deployment and try to add the repository again. To cancel a deployment, go to the Replicator Tasks window and click Cancel Task.
3. Click the REPOSITORIES tab to see a list of the repositories added.
   
   

   Repositories listed

   The repositories list shows:

   Name

   The name of the repository, which is the same as the folder name in the Git directory.

   Take care when naming repositories.

   Follow any relevant best practices when naming repositories. For example, there's a known issue with Git running on MacOS where repositories that have the hash "#" in their name will fail operations, such as Git Clone. (NV-5280)

   Path

   The full path to the repository.

   Replication Group

   The replication group in which the repository may be replicated.

   Size

   The file size of the repository.

   Table columns describe master branch, not the whole repository

   The following columns of information describe the master branch.

   Youngest Rev

   The youngest, most recent, revision in the repository. Comparing the youngest revisions between replicas is a quick test that a repository is in the same state on all sites.

   Last Modified

   The timestamp for the last revision, which provides a quick indicator for the last time a Git user made a change.

   Global RO

   Checkbox that indicates whether the repository is globally Read-only, that is Read-only at all sites.

   Local RO

   Checkbox that indicates whether the repository is locally Read-only, that is Read-only to users at this node. The repository receives updates from the replicas on other sites, but never instigates changes itself.

4.4 Using Git submodules

If you use submodules, they are typically defined using the full URL of the repository, for example:

git add submodule test2 git@192.168.1.30:/home/wandisco/repos/subrepo.git

This adds the following into your .gitmodules file:

[submodule "test2"]
  path = test2
  url = git@192.168.1.30:/home/wandisco/repos/subrepo.git

In this way, submodule activity will occur against a specific Git server.

If the repository used as a submodule is being replicated through GitMS, you lose the benefits of using the repository on a local node. To maintain the benefits of the replicated environment, specify the relationship to the submodule using a relative path, such as:

git submodule add REPONAME ../RELATIVE-PATH-TO-REPO

For example:

git submodule add ../subrepo.git test2

This adds the following entry to your .gitmodules file:

[submodule "test2"]
  path = test2
  url = ../subrepo.git

Note: If you're using external submodules, you can continue to specify them using full URLs. This is only applicable to local submodules you want replicated.