Package: gigantum
Gigantum CLISimple user-facing command line interface (CLI) for installing and running the
Gigantum Client locallyIntroductionThis 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 Gigantumdocs siteIf you encounter any issues or have any questions or comments, please join ourSpectrum Chat Community.PrerequisitesPythonThis tool requires that you have Python andpipinstalled on your system.
It works with Python 3.4 and newer.DockerGigantum 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
DockerwebsiteWindows: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-windowsMac:Docker for Mac works on OS X El Capitan 10.11 and newer macOS releases:https://store.docker.com/editions/community/docker-ce-desktop-macUbuntu: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-fsSLget.docker.com-oget-docker.sh
$sudoshget-docker.shORinstall manually, following the instructions here:https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/Typical installations will use theamd64option in step 4 of
"Setup The Repository"You can skip step 3 of install Docker CERegardless of the install method used above, it is required that you
add your normal user account to thedockeruser 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 tohttps://docs.docker.com/engine/security/security/#docker-daemon-attack-surfacefor more information.(Optional) Adjust Docker ResourcesOn Windows or MacOS, you can configure the amount of CPU and RAM allocated to
Docker by clicking onPreferences > Advancedfrom the Docker Menu. Docker
will use up to the amount specified when operating.![preferences](docs/img/resources.png)Install the CLIThis package is available for install viapip. 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.Usingvirtualenvwrapper:$ mkvirtualenv gigantumIf 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 gigantumORif 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-cliDo NOT usepython setup.py develop.CommandsThe Gigantum CLI provides a few simple commands to support installation,
updating, and use. When thepippackage is installed, the Gigantum CLI is
installed as a globally available script calledgigantum.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.UsageGigantum Working DirectoryThe 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>\gigantumOSX:/Users/<username>/gigantumLinux:/home/<username>/gigantumThis 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 usersarahcreated 1 Project and downloaded 1 Project
from the userjanetthe directory would look like this:<Gigantum Working Directory>
    |_ servers
        |_ gigantum-com
            |_ sarah
                |_ sarah
                       |_ labbooks
                          |_ my-first-labbook
                |_ janet
                       |_ labbooks
                          |_ initial-analysis-1User AccountTo 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 FlowAfter everything is installed, a typical usage would follow a workflow like
this:Start the Docker app if it is not already runningOpen a terminalActivate your virtualenv (if setup)$ workon gigantumStart the application$ gigantum startA browser will open tohttp://localhost:10000Perform your desired workWhen complete, stop the application$ gigantum stopIf desired, quit the Docker appProviding FeedbackIf you encounter any issues using the Gigantum CLI, submit them to thisGitHub
repository issues page.If you encounter any issues or have any feedback while using the the Gigantum
Application, use thegigantum feedbackcommand to open the discussion board.ContributingGigantum uses theDeveloper 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 seedocs/contributing.mdin the gtm
repository.CreditsTODOLicense