HomeGuidesChangelog
GuidesDiscussionChangelogLog In

Multi-user Installation

Install the Client as a managed service for multiple users

📘

Team Server Required

Note, due to the need to customize authentication redirect routes, the multi-user installation configuration via a FQDN (instead of ssh to localhost) is only supported when logging into a Team Server.

Deploying the Client as a service on FQDN over HTTPS is supported when using a Client with a Team Server.

Client Installation

Installing the Client as a service for multi-tenant use is similar to the standard installation process with some additional configuration steps. This is only supported when using the CLI.

You must install Docker, the Gigantum CLI, and Gigantum Client on the host. These instructions can be found in the "Installing Gigantum" section, but we'll use the Quick-start script approach because it is the easiest and fastest.

Install Gigantum Client

On your host, follow the Installing with the Quick-start Script instructions. If you install the Client as a service so it starts on boot, it is easy to edit the service to support external access.

You must use Gigantum CLI >= v1.3.2 when running in the configuration outlined below.

🚧

Gigantum CLI >= v1.3.2 Required

You must be running Gigantum CLI 1.3.2. This update is required to properly enable HTTP-to-HTTPS redirection.

Simply run pip install -U gigantum in your virtualenv to update.

Configure the Client

First, initialize a default configuration file using the CLI. This will write the default file to ~/gigantum/.labmanager/config.yaml.

gigantum config init

Next, enable multi-user mode using the CLI.

gigantum config set-auth-mode multi-user

Finally, add the following to ~/gigantum/.labmanager/config.yaml file to indicate where the Client is hosted externally.

proxy:
  external_url: https://myclient.mydomain.com

If you have configured TLS certificates as outlined below, be sure to use https in for the external_url. If you have not, you should use http.

Add the Server

Add the Team Server instance that this Client will sync with using the CLI. This will configure the Client to work with the server and add a button on the server select page.

gigantum server add https://my-test-server.gigantumdemo.com

(Recommended) Configure TLS Certificates

It is recommended to run over HTTPS since user credentials can be leaked over unencrypted HTTP requests. If this is an acceptable risk (e.g. you are running in a closed and secured network) you can omit this step.

It is assumed that you have configured your DNS provider so the desired FQDN resolves to this host.

To get started with TLS certificate configuration, you must first generate the cert and private key. This can be a purchased certificate, one generated by Let's Encrypt for free, or an internally generated corporate certificate.

If the cert is generated from a root CA that is not trusted by default, you will need to provide that CA to the client. You will also need to make sure the CA is added to the host's trust store so the CLI can verify the Client API has started.

With the certificate and key available, place them in the ~/gigantum/certificates/ssl directory. Note, the certificate should have a .crt extension and the key should have a .key extension. Only insert a single certificate file, concatenating certs if needed.

Start the reconfigured client

If you installed the Client as a service, update the unit file to support external access and restart the service to apply all of the changes. The unit file location was printed out at the end of the Quick-start script.

For example, on Ubuntu 20.04, edit the file /etc/systemd/system/gigantum_client.service and update the ExecStart directive to include the --external flag and --port <INT> argument. For HTTP use --port 80 and for HTTPS use --port 443.

ExecStart=/usr/local/bin/gigantum start -w 90 --external --port 443

Once saved, run systemctl daemon-reload to reload the file and then systemctl restart gigantum_client.service. After the restart complete, the Client should be available.

If you have issues running the service, verify where the gigantum command was installed by running which gigantum and double check the unit file that was created for you during the Quick-start script step.

Team Server Configuration

To successfully log into the Client instance, you must allow a redirect after authentication. On the Team Server instance use gigactl to add the allowed redirect. In the example below, the Client is running at https://my-test-client.gigantumdemo.com. Simply change the command to match your Client's hostname/FQDN.

./gigactl auth redirect add https://my-test-client.gigantumdemo.com

Additional Configuration

Removing GigantumHub as an available server

In some cases it may be desirable to have only a single Team Server instance available for use. In this case, you can remove the default server at gigantum.com. First, remove the server from the Client using the CLI.

gigantum server remove gigantum-com

Then change the default server to the desired team server. Edit the ~/gigantum/.labmanager/config.yaml file that was generated during the installation steps above and change core.default_server to the Team Server URL.

Restart the Client for changes to take effect.

Limiting Project container resources

By default, a Project can use whatever CPU and RAM resources it needs. If you have multiple users sharing a Client instance and want to limit resources, edit the ~/gigantum/.labmanager/config.yaml file to apply limits.

The container.cpu field indicates how many fractional CPUs are available to any single Project container. For example, to give each Project up to 2 cores, set container.cpu to 2. If set to null no limit is enforced.

The container.memory field indicates how much RAM is available to any single Project container. For example, to give each Project up to 4GB of RAM, set container.memory to 4g. If set to null no limit is enforced.

Restart the Client for changes to take effect.

Using custom bases

In some cases it is very useful to build your own bases instead of using the default base images provided by Gigantum. Check out the Base Images section for more information.

Limitations

The primary limitation of running the Client in multi-tenant mode is that it is a single machine limited by local resources. Too many users doing too many things may require additional Clients to be provisioned or more disk space added.

Also, currently all GPUs will be available to all Projects. Users must coordinate which GPU is in use. Future updates will manage GPU assignments on a per-Project basis.