Improvements to LWR documentation.

Add separate examples for MQ driven stuff - this should clear up things and make it clear which new parameters are required when using message queue and which are no longer required. Add more documentation for remote dependency resolution. Document rewrite_parameters.

job_conf.xml.sample_advanced

@@ -23,11 +23,6 @@
           <!-- More information on LWR can be found at https://lwr.readthedocs.org -->
           <!-- Uncomment following line to use libcurl to perform HTTP calls (defaults to urllib) -->
           <!-- <param id="transport">curl</param> -->
-          <!-- Uncomment following parameters (second optional) to target a message
-               queue, ensure jobs_directory is specified on destinations and all
-               file actions are remote executable. -->
-          <!-- <param id="url">amqp://guest:guest@localhost:5672//</param> -->
-          <!-- <param id="manager">_default_</param> -->
           <!-- *Experimental Caching*: Uncomment next parameters to enable
                caching and specify the number of caching threads to enable on Galaxy
                side. Likely will not work with newer features such as MQ support.
@@ -37,6 +32,16 @@
           <!-- <param id="cache">True</param> -->
           <!-- <param id="transfer_threads">2</param> -->
         </plugin>
+        <plugin id="amqp_lwr" type="runner" load="galaxy.jobs.runners.lwr:LwrJobRunner">
+          <param id="url">amqp://guest:guest@localhost:5672//</param>
+          <!-- If using message queue driven LWR - the LWR will generally
+               initiate file transfers so a the URL of this Galaxy instance
+               must be configured. -->
+          <param id="galaxy_url">http://localhost:8080/</param>
+          <!-- If multiple managers configured on the LWR, specify which one
+               this plugin targets. -->
+          <!-- <param id="manager">_default_</param> -->
+        </plugin>
         <plugin id="cli" type="runner" load="galaxy.jobs.runners.cli:ShellJobRunner" />
         <plugin id="condor" type="runner" load="galaxy.jobs.runners.condor:CondorJobRunner" />
         <plugin id="slurm" type="runner" load="galaxy.jobs.runners.slurm:SlurmJobRunner" />
@@ -116,7 +121,11 @@
             <!-- Uncomment the following statement to disable file staging (e.g.
                  if there is a shared file system between Galaxy and the LWR 
                  server). Alternatively action can be set to 'copy' - to replace 
-                 http transfers with file system copies. -->
+                 http transfers with file system copies, 'remote_transfer' to cause
+                 the lwr to initiate HTTP transfers instead of Galaxy, or
+                 'remote_copy' to cause lwr to initiate file system copies.
+                 If setting this to 'remote_transfer' be sure to specify a
+                 'galaxy_url' attribute on the runner plugin above. -->
             <!-- <param id="default_file_action">none</param> -->
             <!-- The above option is just the default, the transfer behavior
                  none|copy|http can be configured on a per path basis via the
@@ -128,24 +137,29 @@
             <!-- Uncomment following option to disable Galaxy tool dependency
                  resolution and utilize remote LWR's configuraiton of tool
                  dependency resolution instead (same options as Galaxy for
-                 dependency resolution are available in LWR).
+                 dependency resolution are available in LWR). At a minimum
+                 the remote LWR server should define a tool_dependencies_dir in
+                 its `server.ini` configuration. The LWR will not attempt to
+                 stage dependencies - so ensure the the required galaxy or tool
+                 shed packages are available remotely (exact same tool shed
+                 installed changesets are required).
             -->
             <!-- <param id="dependency_resolution">remote</params> -->
+            <!-- Traditionally, the LWR allow Galaxy to generate a command line
+                 as if it were going to run the command locally and then the
+                 LWR client rewrites it after the fact using regular
+                 expressions. Setting the following value to true causes the
+                 LWR runner to insert itself into the command line generation
+                 process and generate the correct command line from the get go.
+                 This will likely be the default someday - but requires a newer
+                 LWR version and is less well tested. -->
+            <!-- <param id="rewrite_parameters">true</params> -->
             <!-- Uncomment following option to enable setting metadata on remote
                  LWR server. The 'use_remote_datatypes' option is available for
                  determining whether to use remotely configured datatypes or local
                  ones (both alternatives are a little brittle). -->
             <!-- <param id="remote_metadata">true</param> -->
             <!-- <param id="use_remote_datatypes">false</param> -->
-            <!-- Traditionally, the LWR client sends request to LWR
-                 server to populate various system properties. This
-                 extra step can be disabled and these calculated here
-                 on client by uncommenting jobs_directory and
-                 specifying any additional remote_property_ of
-                 interest. When using message queues this is nessecary
-                 not optional.
-            -->
-            <!-- <param id="jobs_directory">/path/to/remote/lwr/lwr_staging/</param> -->
             <!-- <param id="remote_property_galaxy_home">/path/to/remote/galaxy-central</param> -->
             <!-- If remote LWR server is configured to run jobs as the real user,
                  uncomment the following line to pass the current Galaxy user
@@ -157,6 +171,27 @@
             -->
             <!-- <param id="submit_native_specification">-P bignodes -R y -pe threads 8</param> -->            
         </destination>
+        <destination id="amqp_lwr_dest" runner="amqp_lwr" >
+            <!-- url and private_token are not valid when using MQ driven LWR. The plugin above
+                 determines which queue/manager to target and the underlying MQ server should be
+                 used to configure security.
+            -->
+            <!-- Traditionally, the LWR client sends request to LWR
+                 server to populate various system properties. This
+                 extra step can be disabled and these calculated here
+                 on client by uncommenting jobs_directory and
+                 specifying any additional remote_property_ of
+                 interest, this is not optional when using message
+                 queues.
+            -->
+            <param id="jobs_directory">/path/to/remote/lwr/lwr_staging/</param>
+            <!-- Default the LWR send files to and pull files from Galaxy when
+                 using message queues (in the more traditional mode Galaxy sends
+                 files to and pull files from the LWR - this is obviously less
+                 appropriate when using a message queue).
+            -->
+            <param id="default_file_action">remote_transfer</param>
+        </destination>
         <destination id="ssh_torque" runner="cli">
             <param id="shell_plugin">SecureShell</param>
             <param id="job_plugin">Torque</param>