WIP galaxy

docs/user_guide/galaxy_integration/install.rst

@@ -1,4 +1,50 @@
 Install Tripal Galaxy
 =================================
 
-Lorem
+
+Installation
+~~~~~~~~~~~~~
+
+The Tripal Galaxy module is available as a full Drupal module.  Therefore, it can be installed following the typical Drupal module installation either via the GUI or via Drush.  However it requires a few dependencies:
+
+* curl
+* php-curl
+* blend4php
+
+Follow the typical method for installation of tools for your operating system to install curl and php-curl.  For example, on Ubuntu sytems you can install both curl and php-curl with the following command:
+
+.. code-block:: bash
+
+  sudo apt-get install php-curl
+
+
+Additionally, this module requires the presence of the `blend4php library <https://github.com/galaxyproject/blend4php>`_.  The blend4php library was developed as part of the Tripal Gateway Project as stand-alone PHP bindings to the Galaxy RESTful API.  It allows any PHP-based web application to communicate with a remote Galaxy instance.  To install blend4php, navigate to the sites/all/libraries directory of your Drupal installation and issue the following command:
+
+.. code-block:: bash
+
+  git clone https://github.com/galaxyproject/blend4php.git
+
+
+That's it!  The library is now available for Drupal to find.  Now, we can install the Tripal Galaxy module.  We'll do so here using a Drush command:
+
+.. code-block:: bash
+
+  drush pm-enable tripal_galaxy
+
+You will be asked if you would like to download and then enable the module.  Now that the Tripal Galaxy module is installed, navigate to the ``Administration > Tripal > Extensions > Galaxy`` page via the administrative menu.  At this location is the administrative interface for interacting with remote Galaxy servers.  Near the top of the page are several tabs including **Workflows, Job Queue, Usage, Quotas** and **Files**.
+
+
+.. image:: ./install.1.png
+
+
+Set Permissions
+~~~~~~~~~~~~~~~~
+
+
+Now that the Tripal Galaxy module is installed, we must set permissions so that users can add submit workflows and administrators can manage the workflows.  To set permissions, navigate to **People** page and click the **Permissions** tab in the top right.  Search through the list of permissions until you find the section titled **Tripal Galaxy**.  In this section you will find two types of permssions, one for providing access to execute published workflows and one for administering the Galaxy module.  By default Drupal provides three types of roles:  Anonymous, Authenticated and Administrator users.  The screen shot below shows these permissions for these three roles:
+
+.. image:: ./install.2.png
+
+.. warning::
+
+  If your site is not new you may have additional roles.  As a rule you should **never** give the anonymous user either permission.  Anonymous users should **never** be allowed to execute workflows. Set permissions as appropriate for your site's configuration.  Here we allow authenticated users the ability to execute workflows.

docs/user_guide/galaxy_integration/remote_servers.rst

@@ -1,2 +1,34 @@
 Adding a Remote Galaxy Server
-========================
+===============================
+
+Before any workflows can be run, at least one remote Galaxy server must be integrated with Tripal.  This can be done on the Tripal Galaxy administrative page.  This page is available by navigating to  **Administration > Tripal > Extensions > Galaxy**. The following page is presented:
+
+
+.. image:: ./remote_servers.1.png
+
+
+We can add a new remote Galaxy server by clicking the Add Galaxy Instance link.  The following page appears:
+
+.. image:: ./remote_servers.2.png
+
+
+Here we provide the details for the remote Galaxy instance.  This can be a Galaxy instance that was setup and created specifically and dedicated for your site to use, a shared Galaxy instance setup at your institution or one of several `public Galaxy instances <https://galaxyproject.org/public-galaxy-servers/>`_.  For this tutorial we will use the Galaxy Project's `"Use Galaxy" <https://usegalaxy.org/>`_ public instance.  The following values are therefore provided to the fields:
+
+.. csv-table:: Example Galaxy Field Values
+  :header: "Field Name",  "Value"
+
+  "Galaxy Server Name", "Use Galaxy Public Server"
+  "Description", "The Galaxy Project's public server.  Does not provide all tools that may be needed, size and responsiveness is limited."
+  "URL", "https://usegalaxy.org/"
+  "User Name", "*[The name of a user account on the Galaxy server]*"
+  "API Key", "*[The API Key of the user]*"
+
+The fields described above provide everything needed to connect to a remote Galaxy instance. These incluede the URL, user name of a user on the remote Galaxy server and the API Key for that user.  The **Galaxy Server Name** field and **Description** field are meant for you and the site's user's to know where computation is happening and the Description field is for the site admin.
+
+The user name provided will the account under which all Galaxy workflows will be executed, but the Tripal Galaxy module will ensure that each workflow submission runs independent of all others within this user account.  It is recommended to create a **service** account on the remote Galaxy instance that is independent of a real person.  This service account can be specific for your website only.  Every user on Galaxy has the ability to create an API Key. It is via this key that Galaxy will allow remote connections from a client application like Tripal.  To retrieve the API key for your service account user, log on to the remote Galaxy instance and navigate to **User > Preferences > Manage API Key**.  By default, user's do not have an API key.  You can generate a key by clicking the link to generate a new key.  Once the key is generated you must cut-and-paste the key into the **API Key** field of the Tripal Galaxy Instance setup form (shown above).  Click the **Submit** button when done.
+
+Now we can see that we have a Galaxy server available:
+
+.. image:: ./remote_servers.3.png
+
+Clicking the test link beside the server details will check to ensure that we have entered all information correctly and we can successfully connect to the remote Galaxy server. We see in the screenshot above that the test was successful and that the Galaxy server version is currently 17.09.

docs/user_guide/galaxy_integration/site_wide_files.rst

@@ -1,2 +1,20 @@
 Site-wide Files
 ========================
+
+The Galaxy workflows allow users to provide their own files, use Tripal data collections (i.e. data baskets) that they have saved or to use site-wide files that are provied by the site administrators.  These files can be used as input to the workflows provided to the user.  As an administrator, you can provide site-wide files for anyone to use in a Galaxy workflow by navigating to the Galaxy administrative page and clicking the **Files** tab near the top.   The following page appears:
+
+.. image:: ./site_wide_files.1.png
+
+
+Initially, there are no site-wide files available.  You can add a file (such as a whole genome assembly FASTA file) for use in workflows by clicking the **Add a New File** link. The following page appears.
+
+.. image:: ./site_wide_files.2.png
+
+Here you have two options for providing a file.  Either upload the file using the File Upload form or add the URL to the file if it is available from a remote source.  Typically files from remote sources are available with an HTTP URL or FTP URL.   For example, if your site provides whole genome data and the FASTA file for the genome assembly is available for retrieval from an FTP site, you should enter the full FTP URL for the file into the **Remote Path** field.  Next, you must provide the type of file.  Examples of file types include ``fasta``, ``fastq``, ``CSV``, etc.  You must provide a file type because Galaxy workflows sometimes require specific file types as input.  If an input requires a FASTA file then it expects a fasta file be provided.  Sometimes remote files do not have an appropriate extension to properly determine the file type. Therefore, you must indicate the file type.  Finally, the site's users should understand what the file is.  Enter a very brief description of the file to help users recognize what it contains.  When completed, click the Add File button.
+
+In keeping with the example provided earlier in this User's Guide for Setup of an Example Genomics Site, the following screen shot shows a site-wide file for the JGI Citrus sinensis v1.1 assembly FASTA file that has been added.  Any workflow that expects a FASTA file as input will now be able to use this file in a workflow:
+
+.. image:: ./site_wide_files.3.png
+
+
+If you no longer need a specific file available for users you can either disable the file by clicking the **Disable** link in the Actions column, or you can delete the file by clicking the **Delete** link. Disabling the file will allow the file to remain as a site-wide file but exclude it from appearing for use in future workflow submissions.

docs/user_guide/galaxy_integration/user_quotas.rst

@@ -1,2 +1,19 @@
 User Quotas
 ========================
+
+
+One of the most important settings to configure is the quota system. This can be found on the **Quota** tab of the Galaxy Adminstrative page.  Typically, next-gen workflows require multiple large files.  Users will be able to select data available from this site for their workflows but they can also upload their own data.  To ensure that user's do not exceed the limits of the server a quota system is available.  Click the **Quota** tab to reveal the following page:
+
+.. image:: ./user_quotas.1.png
+
+First, the total amount of space consumed by files uploaded for use in Galaxy workflows is shown at the top of the page.  Initially this will indicate 0 B (for zero bytes) as users upload files this statistic will change.  You may return to this page in the future to check how much space is currently used by user uploads. Here you can also specify the default system-wide quota that all users receive.  By default this is set to 64 Megabytes and a days to expiration of 60 days.  Once a file has existed on the site for 60 days the file is marked for deletion and will be removed when the Drupal cron is executed.  The default of 64MB per user is most likely too small for your site.  Adjust this setting and the days to expire as appropriate for your site's expected number of users and storage limitations and click the Save button to preserve any changes you have made.
+
+
+In addition to the default settings for all users, you may want to allow specific users to have a larger (or perhaps smaller) quota.  You can set user-specific quotas by clicking the **Add Custom User Quota** link near the bottom of the page.   The following page appears:
+
+.. image:: ./user_quotas.2.png
+
+
+Here you must specify the Drupal user name of the user who should be granted a custom quota.  This field will auto populate suggestions as you type to help you find the correct username.  Enter the desired quota size and expiration days and click the **Submit** button. you will then see the user-specific quota listed in the table at the bottom of the page:
+
+.. image:: ./user_quotas.3.png