GitSwarm 2016.3-2 Documentation


Pre-installation steps

Use the following steps to prepare your system for installation of GitSwarm:

  1. Check if your server meets the requirements.

  2. Adjust default firewall rules.

    By default, the CentOS/RHEL firewall rules block HTTP and SSH access.

    1. For CentOS/RHEL 6.6+:

      sudo lokkit -s http -s ssh
    2. For CentOS/RHEL 7:

      sudo firewall-cmd --permanent --add-service=http
      sudo firewall-cmd --permanent --add-service=ssh
      sudo systemctl reload firewalld

    If you intend to run GitSwarm on a non-standard port, you must adjust the firewall rules accordingly. For example, to allow GitSwarm to accept connections on port 12345:

    1. For CentOS/RHEL 6.6+:

      sudo lokkit -p 12345:tcp
    2. For CentOS/RHEL 7:

      sudo firewall-cmd --zone=public --add-port=12345/tcp --permanent
      sudo systemctl reload firewalld
  3. Optional: Ensure that your system is up-to-date.

    We advise installing GitSwarm on a fully up-to-date operating system:

    1. For Ubuntu (12.04 and 14.04):

      sudo apt-get update
      sudo apt-get upgrade
    2. For CentOS/RHEL 6.6+ and 7:

      sudo yum update
  4. Install a mail server and curl.

    GitSwarm requires a local mail server to facilitate delivery of notifications via email, and curl is used in the Quick install.

    Note: If you install Postfix, select Internet Site during setup. Do not use Exim to send email from GitSwarm.

    Then install your selected mail server. For example:

    1. For Ubuntu (12.04 and 14.04):

      sudo apt-get install postfix curl
    2. For CentOS/RHEL 6.6+:

      sudo yum install postfix curl
      sudo service postfix start
      sudo chkconfig postfix on
    3. For CentOS/RHEL 7:

      sudo yum install postfix curl
      sudo systemctl enable postfix
      sudo systemctl start postfix
  5. Ensure that GitSwarm's port is not in use.

    GitSwarm is a web application, which uses port 80 (for HTTP) or port 443 (for HTTPS) by default. GitSwarm cannot operate without exclusive access to its port, so make sure no other service is using its intended port. Learn how to discover which processes are listening on specific ports.

Quick install

curl -s | sudo sh -

Perform the post-installation steps.

Pre-installation Checks

As of GitSwarm 2016.3-2, the GitSwarm package will check, prior to installation, if user['home'] is set to a reserved directory (/opt/gitswarm, /opt/perforce or /opt/rh). If it is set to a reserved directory, the package installation will fail with an error like the following:

ERROR: "user['home']" set to reserved directory '/opt/gitswarm'.
ERROR: '/opt/gitswarm', '/opt/perforce' and '/opt/rh' are reserved directories
ERROR: for GitSwarm and should not be used for "user['home']".
ERROR: Please edit:
ERROR:     /opt/perforce/package-control/helix-gitswarm.config-overrides
ERROR: update "user['home']" and ensure that it is not set to a reserved
ERROR: directory (as listed above).
ERROR: If you are upgrading your GitSwarm installation, please migrate
ERROR: your installation to the new setting for "user['home']" before
ERROR: attempting to upgrade your GitSwarm installation.  Detailed instructions
ERROR: on how to migrate your home directory can be found in our online
ERROR: documentation here:

If you encounter this error on a new installtion of GitSwarm, please create/edit /opt/perforce/package-control/helix-gitswarm.config-overrides and add/edit the key


setting it to a directory that is not reserved. After changing the path, please retry the installation of GitSwarm.

Manual install

If you prefer to manually perform, or review, the steps undertaken by the bootstrap script above, see the Manual installation steps.

Perform the post-installation steps.


  1. Verify the external URL for your GitSwarm instance:

    View /etc/gitswarm/gitswarm.rb, and verify that the following setting is set to the URL that your GitSwarm users should use:

    external_url ""

    Edit the setting if necessary.

    Note: It is possible to run GitSwarm on a non-standard port by specifying the port as part of the external_url:

    external_url ""

    If you do use a non-standard port, see above for instructions on adjusting the firewall for CentOS/RHEL systems.

  2. Set the timezone for your GitSwarm instance:

    Edit /etc/gitswarm/gitswarm.rb, and edit the line:

    #gitlab_rails['time_zone'] = 'UTC'

    Replace UTC with an appropriate timezone, and uncomment the line.

  3. Check the 'home' directory for your GitSwarm instance:

    As of 2016.3-2, GitSwarm will check user['home'] during its configuration and fail with the following error if it's set to a reserved directory:

    Recipe: gitswarm::default
    * ruby_block[Checking home directory for 'git'] action run
    Error executing action `run` on resource 'ruby_block[Checking home directory for 'git']'
    Cannot set home directory for 'git' to '/opt/gitswarm'

    If this happens, please open /etc/gitswarm/gitswarm.rb and edit the line:

    user['home'] = ...

    replacing the path with a directory that is not reserved by GitSwarm (/opt/gitswarm, /opt/perforce, /opt/rh).

  4. Configure GitSwarm.

    If you have made changes to /etc/gitswarm/gitswarm.rb, then you will want to run reconfigure for them to take effect.

    sudo gitswarm-ctl reconfigure
  5. Browse to the hostname.

    Since the 2016.2 release, GitSwarm asks for a password for the root user (previous releases used a known password). Once you have specified a password, you can login.

  6. Tweet about it!

If you are interested, learn about the GitSwarm directory structure.

If you prefer to use HTTPS with GitSwarm, learn how to configure HTTPS.

To uninstall GitSwarm, follow the uninstall steps.

Additional Setup Options


Note: For additional troubleshooting and configuration options, please see the Omnibus GitLab readme.