HomeGuidesChangelog
GuidesDiscussionChangelogLog In

Installation

Install a Team Server

System Requirements

Gigantum Team Server should be installed on a VM or bare metal server running Linux. Currently Ubuntu 18.04, RHEL7, and RHEL8 have been tested and is fully supported. Many Linux distributions should work as long as Docker can run.

The Team Server can run on Docker or a Firecracker micro-vm based backend (coming soon). Docker is best for compatibility with host OS and other constraints, while the Firecracker backend provides additional performance and isolation benefits.

If using the Docker backend, Docker must be installed and the user installing the Team Server must be in the docker group (i.e. able to run docker commands without sudo).

📘

Default Docker package may be incorrect

The default Docker package available in many distributions is often very old or incorrect. You should always refer to Docker's docs to install the correct version for your distribution.

If using the Firecracker backend (coming soon) on a VM, the hypervisor must support nested virtualization.

It is recommended that the server has at least 4 CPUs, 16GB RAM, and 120GB of disk space. Disk space requirements are dependent on your usage, as Team Servers store all data on the local filesystem (Team Server Pro, when available in the near future, will support other storage options).

Additional Considerations

Internet Access

The Team Server installation process requires access to the internet to access license services, pull configuration information, and pull container images. The software may access GitHub.com, hub.docker.com, quay.io, and Gigantum hosted services and container registries during the install process, all on port 443.

TLS Certificates

When installing your Team Server instance, by default a TLS certificate will automatically be provisioned via Let's Encrypt. For this process to succeed, your server must be reachable from the internet on port 80 during the installation process.

If this is not possible due to network restrictions, or you have a certificate that you wish to use instead, you can provide a valid TLS certificate via the --ssl-cert and ssl-cert-key command line arguments

Read more in the Certificates section.

Network Security

If your server is running inside a network that utilizes TLS firewalls or traffic filters, installing with a custom Certificate Authority (CA) may be required. You can add a custom CA as trusted CA by providing the certificate via the --ssl-ca flag at install time. Clients will also need to configure this CA cert before starting.

Backup Disk Space Requirements

The Team Server backup process writes to the local file system and can result in significant storage requirements that should be considered when provisioning your server. Git data is replicated and compressed every time a backup runs. Larger files stored in the input and output sections of projects, along with Dataset files, are backed up via a snapshot process. You should provision at least 2-3 times your anticipated storage needs to maintain reliable backups.

Future versions of the Team Server will provide additional backup targets to help alleviate this issue.

Local Storage

The server installation by default will write state and configuration to ~/.gigactl and data to ~/.gigactl/data. Data includes all database & git data. If external object storage is not in use, then object data from git LFS and Gigantum Datasets will also be written here. This means you must not only have enough disk space allocated on your host, but this space must be available to your home directory.

If you wish to store data elsewhere, you must set the GIGANTUM_CONFIGDIR and GIGANTUM_DATADIR environment variables before running any gigactl command. This will ensure that all commands use the correct configuration and data location.

Getting Ready

You must collect and configure your license file and Settings File before starting the installation process.

Get a copy of your license file and copy it to your server. This file will be sent to you via email once you've completed your purchase. Remember, the external hostname of your server is tied to this license. If you need to change it, email [email protected]

Download the latest gigactl binary and copy it to your server. This is the command line administrator tool that you will use to install the Team Server and perform other maintenance functions.

Create and configure your user settings file. You can find the format and minimum required values in the Settings File section.

Make sure your DNS provider is configured to properly route to your instance using the domain provided while requesting your license file.

Finally, if using the Docker backend make sure Docker is installed and accessible by the user account performing the installation. This means you can run something like docker run hello-world without requiring sudo.

🚧

DNS Configuration Required

You must have DNS configured before installation begins. During setup the external route is used and will lead to errors if your server is not reachable.

Installing a Team Server using Docker

These instructions assume the Docker backend will be used to run the Team Server and you have copied gigactl, your license file, and your user settings file to your home directory on the server. First make sure gigactl is executable:

cd ~
chmod +x ./gigactl

Run the tool once to verify the version and initialize the working directory structure. Do not run this command as root. Doing so may set incorrect permissions on the working directory

./gigactl version

Next, firewall rules must be added to forward traffic to the Team Server running in Docker. This command must be run as root. It creates and enables a service to set iptables rules on boot.

If you wish to preview the changes this command will make run ./gigactl firewall print first.

sudo ./gigactl firewall configure

Next we run the install command. While most configuration is done through the Settings File, there are several flags that can be provided to the install command. To view all options run ./gigactl install hub -h.

Some commonly used command line options are:

  • --auth: Type of authentication to configure. Supported options: internal, oauth2, oidc, ldap. Default is internal.
  • --self-signed: Automatically generate and use a self-signed TLS certificate for server ingress.
  • --ssl-ca: Path to an SSL CA to add as a trusted CA. Note, this is only installed automatically into gigactl managed containers. The CA may need to be manually added to the host's trust store before installation can begin.
  • --ssl-cert and --ssl-cert-key: Paths to an SSL certificate and private key to use for server ingress. By default the Team Server will automatically try to provision a certificate using Let's Encrypt.

You can read more about the certificate flags here.

./gigactl install hub --backend docker --license-file ./gigantum.lic --settings-file ./settings.yaml

Now, grab a coffee :coffee: and wait typically 10-20 minutes depending on your server and network performance. Once the install process is complete, you can Add your Team Server to your Gigantum Client and start working, just like you would with gigantum.com!

📘

Do not delete containers

If you are using the Docker backend, you should not manually stop or delete the running containers that gigactl installs and configures. Use the uninstall command if you wish to remove the server.

Recommended: Installing the Team Server as a Service

After the Team Server has been successfully installed, it can be configured to run as a service on hosts running systemd. While not required, this is recommended and will ensure that if the instance reboots the Team Server will automatically restart. Running this command will require root privileges.

sudo ./gigactl install service --gigactl-dir $HOME/.gigactl

If you do not configure the service, or are running on a host that does not support systemd, you may have to manually start the stopped Docker containers on reboot.