Installing Git Fusion using the OVA

Who is this for? The git-fusion.ova image includes both a Git Fusion and a Perforce Server instance. The Perforce instance is pre-loaded with sample data and configured for use with the included Git Fusion instance. There is a simple set of instructions to turn off this local Perforce service and connect the Git Fusion instance to your own external Perforce service.

Use the OVA if any of the following apply to you:

  • You want to deploy to a virtual environment, and Ubuntu 12.04 LTS is an acceptable platform.

  • You are not an experienced Linux administrator, as this installation method requires the least amount of Linux expertise.

Prerequisites

Note

See the Git Fusion release notes for the most comprehensive and recent software and hardware requirements.

  • 64-bit operating system on the host computer.

  • Virtualization framework that supports the import of .ova files.

Installation steps

  1. Download the git-fusion.ova:

    http://www.perforce.com/downloads/git-fusion

    ftp://ftp.perforce.com/perforce/r15.1/bin.noarch/git-fusion.ova

  2. Import the OVA into your virtualization framework.

    For production use, we recommend at least 4 cores and 16 GB memory.

    Configure as required for your site. Reinitialize the MAC address of all network cards if you are presented with the option.

  3. Start the Git Fusion virtual machine.

  4. Set Linux account passwords at the prompts.

    • root: root account on the virtual machine

    • perforce: service account used by the pre-loaded Perforce service

    • git: service account used by Git Fusion

  5. Automatic update to the pre-loaded Perforce service.

    The Perforce service is installed and updated using a Debian package. At this point, the virtual machine will attempt to connect to package.perforce.com and check for an update to this package. If one is available, it will automatically be installed. No user action is required for this step.

    You can update the Perforce service package at a later date with the following command:

    $ sudo apt-get update && sudo apt-get install perforce-server-base
  6. Enter a Git Fusion server ID or accept the default.

    Server IDs are required to enable multiple Git Fusion instances to connect to the same Perforce service.

    Note

    If you want to change your Server ID at a later time, you can run p4gf_super_init.py with the --id option. For more information, see Managing Git Fusion server IDs.

When you have entered a server ID or accepted the default, the Git Fusion virtual machine completes its startup process. You now have a running Git Fusion instance connected to a local, pre-loaded Perforce service.

Make note of the IP address displayed in the console window. You can use it to perform your first git clone and to access the online SSH key management console. For information about the SSH key management console, see SSH key management console.

Next Steps

If you are using the OVA to install Git Fusion against another Perforce service:

If you want to use the Perforce service included in the OVA, your installation is complete.

Now you can perform a git clone of the Talkhouse sample repo. When Git Fusion receives the clone request, it will create a new Git repo out of existing files in Perforce, and deliver the resulting repo to the Git client. For authorization, you'll first need to create a Perforce user.

  1. Create a Perforce user.

    1. Log into the Git Fusion virtual machine as root (or open a shell on another system that has the p4 client installed).

    2. Create a Perforce user:

      p4 -p ipaddress:1666 -u super user -f username

      where ipaddress is the IP address displayed in the VM console window (the one you noted when you installed the OVA).

      Note that super is a pre-configured Perforce super user.

      Enter :wq to save the new user.

  2. Assign a password.

    p4 -p ipaddress:1666 -u username passwd
  3. Clone the Talkhouse repo.

    You can perform the clone from any computer with a Git installation and network access to the Git Fusion virtual machine.

    1. First tell Git not to verify the SSL certification.

      $ export GIT_SSL_NO_VERIFY=true

      Note

      We deliver Git Fusion in the OVA with a self-signed SSL certificate. Exporting this environment variable tells Git not to verify the SSL certification in the current shell session only. To tell Git never to verify SSL certificates, use the following command:

      git config --global http.sslVerify false

      To point Git Fusion to your own signed SSL certificate (recommended if you will be using this Git Fusion installation for anything other than demonstration purposes), see Pointing the Git Fusion HTTPS server to your own SSL certificate.

    2. Perform the clone operation using the IP address (without the port number) displayed in the Git Fusion VM console window (the one you noted when you installed the OVA.

      git clone https://ip_address/Talkhouse

      When prompted, enter the user name and password you created in Step 1.

To learn more about adding users and setting up repos see:

To learn more about how to work with the Perforce service included with the OVA, see: Perforce Server and the OVA

Connecting the Git Fusion OVA installation to your Perforce service

Who is this for? You want to use the Git Fusion instance that you installed with the OVA against a Perforce service on another machine, such as your existing production Perforce service. For this installation, you need some Perforce and Linux administration experience.

Prerequisites for the Perforce service:

Note

See the Git Fusion release notes for the most comprehensive and recent software and hardware requirements.

  • See the Git Fusion release notes for current Perforce Server (P4D) version requirements.

  • You must have root level access to the server(s) that host(s) your Perforce service, as well as Perforce super user access.

  • Python 2.6+, 3.2+, or 3.3+ on the server hosting the Perforce service triggers.

  1. Turn off the local Perforce service.

    Log into the Git Fusion virtual machine as root and run:

    # service p4d stop
    # update-rc.d p4d disable

  2. Update the Apache web service site configuration file to add your Perforce service.

    Note

    If you prefer to use SSH rather than HTTPS authentication, skip this step and see Set up SSH authentication using the OVA's SSH key management console.

    1. Stop the Apache web service.

      # service apache2 stop
    2. Open the git-fusion-ssl Apache site configuration file.

      # vi /etc/apache2/sites-available/git-fusion-ssl 
    3. Edit the AddExternalAuth line to include the full hostname, port, and P4CHARSET of your Perforce service.

      AddExternalAuth p4_auth "/opt/perforce/git-fusion/libexec/p4auth.sh myperforceserver:port charset"
    4. Save your changes and exit vi.

      :wq
    5. Start the Apache web service.

      # service apache2 start
  3. Run the configure-git-fusion.sh script.

    # /opt/perforce/git-fusion/libexec/configure-git-fusion.sh

    The script prompts you for the following:

    • Whether you want to connect to an existing Perforce service or create a new one:

      Type remote to use an existing Perforce service on another host.

    • How you want to handle the Perforce change owner for git commits authored by non-Perforce users.

      Enter reject to reject push which contains commits authored by non-Perforce users (default)

      Enter pusher to accept commits authored by non-Perforce users and set the change owner to the pusher

      Enter unknown to accept commits authored by non-Perforce users and set the change owner to 'unknown_git'. This option will also create 'unknown_git' Perforce user.

      Note

      Note: The actual pusher, author, and committer are always recorded in the Perforce changelist description.

    • Perforce service's hostname and port (P4PORT).

    • Perforce super user name and password to enable Git Fusion to run administrative p4 commands.

    • Git Fusion time zone, in Olson format.

      Set it to your Perforce service time zone or accept the default, which is the Git Fusion host machine's time zone.

      Git Fusion uses the Olson time zone format, as recognized by pytz (for example, US/Pacific rather than PST).

    • Whether you want to configure HTTPS authentication

      Enter no, since HTTPS authentication is already configured on the Git Fusion OVA

    • Single password to be shared by any new Perforce users that Git Fusion creates to enable it to interact with the Perforce service.

      The first time you install and configure a Git Fusion instance for use with any given Perforce service, the script creates the users git-fusion-user, git-fusion-reviews-server-id, git-fusion-reviews--non-gf, and git-fusion-reviews--all-gf.

      Note

      You can set individual passwords after the configuration script is finished by issuing the following command:

      p4 -p myperforceserver:port -C charset -u user_name passwd

    When the script is finished, it congratulates you and suggests that you configure your Perforce service to use Git Fusion's atomic push triggers.

    For detailed information about the functions performed by the configuration script, along with information about rerunning it to change your initial configuration settings, see configure-git-fusion.sh in the Script Reference.

  4. Configure Git Fusion triggers in the Perforce service to support atomic pushes.

    Important

    We recommend that any submit triggers running on your Perforce service exclude changes that are submitted by git-fusion-user. These include change-submit, change-commit,and change-content triggers that enforce a local policy, like requiring jobs, specific content, or specific formatting in the changelist description. Such triggers can interrupt Git Fusion in the middle of a push, which will damage the repository as replicated within Perforce.

    If you cannot exclude git-fusion-user from these triggers, you can instead create preflight hooks that reject git pushes based on local policies derived from your current submit triggers. For more information, see Adding preflight commits to reject pushes.

    1. Copy the p4gf_submit_trigger.py script and the high performance wrapper p4gf_submit_trigger_wrapper.sh from /opt/perforce/git-fusion/libexec to the server hosting the Perforce service.

      Note

      The wrapper script is written in Bash, which has a much lower startup overhead than Python. The wrapper quickly determines if the triggered event is related to a Git Fusion operation, in which case a call to the Python script is avoided entirely. Although the Python script can also be called directly, this arrangement improves Git Fusion performance.

      Note

      If your Perforce service is hosted on a platform supported by Git Fusion packages, you can install the helix-git-fusion-trigger package on it to satisfy this step.

    2. Log in to the server hosting the Perforce service as a user with sudo privileges.

    3. Run the p4gf_submit_trigger.py script to install and configure the triggers.

      $ p4gf_submit_trigger.py --install  myperforceserver:port perforce_super_user password

      The script does the following:

      • Creates login tickets for the Perforce users git-fusion-user, git-fusion-reviews-server-id, git-fusion-reviews--non-gf, and git-fusion-reviews--all-gf.

      • Creates a trigger configuration file, p4gf_submit_trigger.cfg, in the same directory as the trigger script, that holds your P4PORT and P4CHARSET variables, as well as the path to the P4 binary.

      • Adds Git Fusion trigger entries to the Perforce Triggers table. If the high performance Bash wrapper is present, triggers will be configured to call it, otherwise they will be configured to call the Python script directly.

      • If your Perforce service is SSL-enabled, generates the p4gf_submit_trigger.trust file in the same directory as the trigger script to manage the trust of the SSL connection.

      • Sets the p4 key that verifies that the trigger was installed.

      If you are upgrading an existing Git Fusion installation, the script replaces your old Git Fusion triggers with new ones. It does not touch any other triggers.

    For more details about p4gf_submit_trigger.py, see the Script Reference.

    For more information about triggers, see the Perforce System Administrator's Guide, "Scripting Perforce: Triggers and Daemons."

  5. Verify the configuration from the Git Fusion server.

    Switch to the Git Fusion service account (git) on the Git Fusion server and run p4gf_super_init.py.

    # su - git
    $ p4gf_super_init.py --user perforce_super_user

    The script should report that everything has been created, already exists, or is up to date.

Next steps

You are now ready to:

Pointing the Git Fusion HTTPS server to your own SSL certificate

We deliver Git Fusion in the OVA with a self-signed SSL certificate. If you will be using this Git Fusion installation for anything other than testing and evaluation, we recommend that you use your own signed SSL certificate. If you are using SSH for authentication, you can skip this task.

Note

If you keep the default self-signed SSL certificate, you must tell Git not to verify the SSL certification when you perform Git commands against Git Fusion repos, either on a per-session basis (by running export GIT_SSL_NO_VERIFY=true) or for all sessions (by running git config --global http.sslVerify false).

To enable Git Fusion to use your own signed SSL certificate:

  1. Stop the Apache web service:

    Log into the Git Fusion virtual machine as root and run:

    # service apache2 stop
  2. Open the git-fusion-ssl Apache site configuration file.

    # vi /etc/apache2/sites-available/git-fusion-ssl
  3. Edit the lines SSLCertificateFile and SSLCertificateKeyFile to point to your signed SSL certificate and key.

      SSLCertificateFile /path/to/your_certificate_file
      SSLCertificateKeyFile /path/to/your_private_key_file
  4. Save your changes and exit vi.

    :wq
  5. Start the Apache web service.

    # service apache2 start