GitSwarm 2016.3-2 Documentation

Installation

Installation

Pre-installation steps

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

Check if your server meets the requirements.
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
```
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
```
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
```
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 https://package.perforce.com/bootstrap/gitswarm.sh | 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:
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:
ERROR: Please edit:
ERROR:
ERROR:     /opt/perforce/package-control/helix-gitswarm.config-overrides
ERROR:
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:
ERROR:
ERROR:    https://www.perforce.com/perforce/doc.current/manuals/gitswarm/update/README.html#changing-gits-home-directory
ERROR:

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

user['home']

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.

Post-installation

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 "http://gitswarm.example.com"
```
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 "http://gitswarm.example.com:12345"
```
If you do use a non-standard port, see above for instructions on adjusting the firewall for CentOS/RHEL systems.
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.

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']'
================================================================================

RuntimeError
------------
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).

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
```
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.
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

Set up the connection to your Helix Server:

GitSwarm automatically provisions a Helix Server and connects Helix Git Fusion for you when you initially install the GitSwarm packages. Learn more about the provisioned server.

In production, you will likely already have your own Helix Server already setup and will want to configure GitSwarm to talk to it in order to enable Helix Mirroring.
Set up other ways of signing in:

Check out how to setup LDAP or OmniAuth

Troubleshooting

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

error: "X" is an unknown key on CentOS/RHEL 6.6+

This error occurs during install of CentOS/RHEL 6.6+, often in a shared VM environment where some of the keys in /etc/sysctl.conf don't actually apply. The error usually looks something like this:
```
STDERR: error: "net.bridge.bridge-nf-call-ip6tables" is an unknown key
error: "net.bridge.bridge-nf-call-iptables" is an unknown key
error: "net.bridge.bridge-nf-call-arptables" is an unknown key
```
These errors are ignorable, you just need to run sudo gitswarm-ctl reconfigure, and our script shouldn't have to modify that file again and will continue. If you want to future-proof upgrades from failing on the same lines, you can modify your /etc/sysctl.conf and comment out the keys that were listed as unknown.