[Swift-commit] r7660 - SwiftApps/cloud

[ketan at ci.uchicago.edu]

Author: ketan
Date: 2014-03-08 20:37:45 -0600 (Sat, 08 Mar 2014)
New Revision: 7660

Modified:
   SwiftApps/cloud/README
Log:
asciidocify readme

Modified: SwiftApps/cloud/README
===================================================================
--- SwiftApps/cloud/README	2014-03-08 23:55:42 UTC (rev 7659)
+++ SwiftApps/cloud/README	2014-03-09 02:37:45 UTC (rev 7660)
@@ -1,32 +1,45 @@
 Toolkit to run Swift applications over Amazon EC2 cloud
 ========================================================
 
-0. Installation and setup of EC2 commandline tools is assumed. If you do not have already, please find instructions of getting EC2 api from here:
+EC2 setup
+----------
+
+Installation and setup of EC2 commandline tools is assumed. If you do not have already, please find instructions of getting EC2 api from here:
 http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/SettingUp_CommandLine.html
 
-1. Install Swift
+Install Swift
+--------------
 
-2. Configure:
-    a. environment variables
+Configure
+----------
+
+    environment variables
+    ~~~~~~~~~~~~~~~~~~~~~~
+
     Make sure GLOBUS_TCP_PORT_RANGE and GLOBUS_HOSTNAME are defined. For example:
     
     export GLOBUS_TCP_PORT_RANGE=50000,51000
     export GLOBUS_HOSTNAME=churn.mcs.anl.gov
     
-    c. ec2
+    EC2
+    ~~~~
+
     ami-id, security group, keypair set up.
 
-    b. coaster-service.conf
-    Configure coaster-service.conf. An example coaster-service.conf can be found in the current directory. Make sure to set the EC2XXX variables to the correct values as per your account.
-    Set other environment variables e.g:
+    coaster-service.conf
+    ~~~~~~~~~~~~~~~~~~~~~
+
+    Configure coaster-service.conf. An example coaster-service.conf can be
+    found in the current directory. Make sure to set the EC2XXX variables to
+    the correct values as per your account.  Set other environment variables
+    e.g:
     
-    export WORKER_LOCATION=/home/ubuntu/worker
-    export WORKER_USERNAME=ubuntu
-    export LOG_DIR=logs
-    export SHARED_FILESYSTEM=no
-    export SSH_TUNNELING=yes
+    export WORKER_LOCATION=/home/ubuntu/worker export WORKER_USERNAME=ubuntu
+    export LOG_DIR=logs export SHARED_FILESYSTEM=no export SSH_TUNNELING=yes
 
-3. Start coaster service
+Start coaster service
+----------------------
+
 Start the coaster service using the following command:
 
 start-coaster-service
@@ -35,20 +48,48 @@
 
 Make sure coaster-service.conf is available in the current working directory or use the "-conf" option to use config file located elsewhere.
 
-4. Start Swift run
+Start Swift run
+----------------
+
 Start swift run. Assuming your Swift scripts, applications and data are set, run a Swift script using swift command as follows:
 
    swift -sites.file sites.xml -tc.file apps -config cf catsnsleep.swift -s=10 -n=20
 
 The example catsnsleep.swift and cf files are provided with the package.
 
-5. Manage resources:
-    a. Add EC2 compute instances
+Manage resources
+-----------------
+
+    Add EC2 compute instances
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~
+
     Add more resources via addnodes. Use -n to add by number and -a to add by ip address.
-    b. Remove EC2 compute instances
+
+    Remove EC2 compute instances
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    
     Remove EC2 resources via remnodes.
-    c. Monitor resources
+    
+    Monitor resources
+    ~~~~~~~~~~~~~~~~~
+
     Monitor Swift tasks and EC2 instances while jobs are running.
 
-6. Shut everything down: stop-coaster-service
+Shut down
+----------
+
+stop-coaster-service
 Use the stop-coaster-service command to stop everything.
+
+Troubleshoot
+------------- 
+
+    Coaster service
+    ~~~~~~~~~~~~~~~
+
+    Swift
+    ~~~~~~
+    a. Swift not found: check your PATH and make sure the bin directory of Swift is added
+    b. Swift run shows no progress in task execution: Check if the cloud instances are running
+    c. Swift runs fail: Check if ports are open between submithost and cloud instance
+