gigantum

Gigantum CLI

Simple user-facing command line interface (CLI) for installing and running the Gigantum Client locally

Introduction

This Python package is provided as a method to install and run the Gigantum Client, locally on your computer. It provides a simple command line interface to install, update, start, stop, and configure the application.

More detailed install instructions can be found at the Gigantum docs site

If you encounter any issues or have any questions or comments, please join our Spectrum Chat Community.

Prerequisites

• Python

  This tool requires that you have Python and pip installed on your system. It works with Python 3.4 and newer.

• Docker

  Gigantum requires the free Docker Community Edition to be installed to run locally on your computer. You do not need to keep Docker running at all times, but it must be open before you start the Gigantum application and can be closed after you stop the Gigantum application.

  If you don't already have Docker, you can install it directly from the Docker website

  • Windows:

    • Requires Microsoft Windows 10 Professional, Enterprise, or Education (64-bit)
    • On most systems, Virtualization must be enabled in the "BIOS" (aka UEFI), and Hyper-V must also be enabled. Docker will usually set this for you, but is a good first place to look if things aren't working.
    • Requires Docker CE Stable: https://store.docker.com/editions/community/docker-ce-desktop-windows

  • Mac:

    • Docker for Mac works on OS X El Capitan 10.11 and newer macOS releases: https://store.docker.com/editions/community/docker-ce-desktop-mac

  • Ubuntu:

    • Install using Docker's "helper" script, which will perform all install steps for you (you may inspect the get-docker.sh script before running it):

      $ cd ~
      $ curl -fsSL get.docker.com -o get-docker.sh
      $ sudo sh get-docker.sh
      

    • OR install manually, following the instructions here: https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/

      • Typical installations will use the amd64 option in step 4 of "Setup The Repository"
      • You can skip step 3 of install Docker CE

    • Regardless of the install method used above, it is required that you add your normal user account to the docker user group so that you can run Docker commands without elevated privileges. Run the following command and then logout and back into your system for changes to take effect.

      $ sudo usermod -aG docker <your username>
      

      • Note, Docker provides this warning when doing this, which in most cases is not an issue:

        WARNING: Adding a user to the "docker" group will grant the ability to run containers which can be used to obtain root privileges on the docker host. Refer to https://docs.docker.com/engine/security/security/#docker-daemon-attack-surface for more information.

• (Optional) Adjust Docker Resources

On Windows or MacOS, you can configure the amount of CPU and RAM allocated to Docker by clicking on Preferences > Advanced from the Docker Menu. Docker will use up to the amount specified when operating.

![preferences](docs/img/resources.png)

Install the CLI

This package is available for install via pip. It runs on Python 3.4+ and supports Windows, OSX and Linux.

• (Optional) To isolate this package from your system Python, it is often best to create a virtual environment first. This is not required, but recommended if you feel comfortable enough with Python. The Gigantum CLI installs a minimal set of Python dependencies, so in general it should be safe to just install if preferred.

  Using virtualenvwrapper:

  $ mkvirtualenv gigantum
  

  If you are familiar with conda or prefer to manually manage a virtualenv (or venv), these methods will also work.

• Install Gigantum CLI

  $ python3 -m pip install -U gigantum
  

  OR if you are actively developing the CLI, you may wish to install it from a checkout of this repository like so:

  $ git checkout <URL for gigantum-cli>
  $ python3 -m pip install -e gigantum-cli
  

  Do NOT use python setup.py develop.

Commands

The Gigantum CLI provides a few simple commands to support installation, updating, and use. When the pip package is installed, the Gigantum CLI is installed as a globally available script called gigantum.

Usage of the CLI then becomes:

$ gigantum -h
Usage: gigantum [OPTIONS] COMMAND [ARGS]...

  A Command Line Interface to manage the Gigantum Client.

Options:
  -h, --help  Show this message and exit.

Commands:
  config    Manage the Client configuration file.
  feedback  Open the default web browser to provide feedback.
  install   Install the Gigantum Client Docker Image.
  server    Manage server connections for this Client instance.
  start     Start Gigantum Client.
  stop      Stop Gigantum Client.
  update    Check if an update is available for Gigantum Client.

Usage

Gigantum Working Directory

The Gigantum working directory is where all your work is stored on your local filesystem. You can interact directly with this directory if you'd like, but it is recommended to use the Gigantum UI as it ensures all activity is properly recorded.

The default working directory location changes based on your operating system:

• Windows: C:\Users\<username>\gigantum
• OSX: /Users/<username>/gigantum
• Linux: /home/<username>/gigantum

This directory follows a standard directory structure that organizes content by user and namespace. A namespace is the "owner" of a Project or Dataset, and typically the creator. The working directory is organized as illustrated below:

<Gigantum Working Directory>
    |_ servers
        |_ <server id>
            |_ <logged in user's username>
                |_ <namespace>
                       |_ labbooks
                          |_ <project name>
                       |_ datasets
                          |_ <dataset name>

As an example, if the user sarah created 1 Project and downloaded 1 Project from the user janet the directory would look like this:

<Gigantum Working Directory>
    |_ servers
        |_ gigantum-com
            |_ sarah
                |_ sarah
                       |_ labbooks
                          |_ my-first-labbook
                |_ janet
                       |_ labbooks
                          |_ initial-analysis-1

User Account

To use the Gigantum application you must have a Gigantum user account. When you run the application for the first time you can register with the default server gigantum.com.

By default, once you login your user identity is cached locally. This lets you run the application when disconnected from the internet and without needing to log in again. If you logout, you will not be able to use the application again until you have internet access and can re-authenticate.

Typical Work Flow

After everything is installed, a typical usage would follow a workflow like this:

• Start the Docker app if it is not already running

• Open a terminal

• Activate your virtualenv (if setup)

  $ workon gigantum
  

• Start the application

  $ gigantum start
  

• A browser will open to http://localhost:10000

• Perform your desired work

• When complete, stop the application

  $ gigantum stop
  

• If desired, quit the Docker app

Providing Feedback

If you encounter any issues using the Gigantum CLI, submit them to this GitHub repository issues page.

If you encounter any issues or have any feedback while using the the Gigantum Application, use the gigantum feedback command to open the discussion board.

Contributing

Gigantum uses the Developer Certificate of Origin. This is lightweight approach that doesn't require submission and review of a separate contributor agreement. Code is signed directly by the developer using facilities built into git.

Please see docs/contributing.md in the gtm repository.

Credits

TODO

License