README.how.to.launch.Galaxy

This file describes how to launch an instance of Galaxy step-by-step on Amazon Cloud. 
If you have any questions about this, please email help@modencode.org.

NOTE: Steps 1 to 4 need only to be done once.  Afterward, you can go directly to Step 5 to launch 
your Galaxy. 


Step 1.  Create your Amazon EC2 account if you don't already have one.  Go to http://aws.amazon.com, click 
on 'Sign Up Now' and follow the instructions.  Keep your Amazon access and secret keys handy because 
you will need them in Step 3. Also, ensure that you have admin access under the AWS account you are using,
otherwise Cloudman will fail to initialize Galaxy. 

Step 2. Use git to clone or check out the latest copy of the modENCODE DCC Galaxy source code and tools.

  > cd 
  > git clone https://github.com/modENCODE-DCC/Galaxy.git
  > cd Galaxy 
 

Step 3. Edit 'env.sh' and set your JAVA_HOME, AWS_ACCESS_KEY, and AWS_SECRET_KEY environment variables.  
Set your environments by doing the following:

 > .  env.sh 

 Test and make sure your environments are set correctly by doing the following:

 > ec2-describe-regions

  If you are able to run the above command then your environments are set correctly.  If you are not able to 
run the above command then see the below link on how to setup your EC2 API tools:

   http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/SettingUp_CommandLine.html


Step 4. Edit 'config.txt' to include the following configuration values for your modENCODE Galaxy instance
and CloudMan.  The Galaxy creation script bin/modENCODE_galaxy_create.pl in Step 5 uses values in this 
file to configure Galaxy and Cloudman.

  CLOUDMAN_PASSWORD: galaxy_123
    Password to get into CloudMan console.  Default value is 'galaxy_123'. 

  KEY_PAIR: YOUR_NAME_modENCODE_Galaxy_Key
    Keypair name to use to login to Galaxy.  Default value is 'YOUR_NAME_modENCODE_Galaxy_Key'.
  SECURITY_GROUP: YOUR_NAME_modENCODE_Galaxy_Group
    Security group to be used by Galaxy.  Default value is 'YOUR_NAME_modENCODE_Galaxy_Group'.
  INSTANCE_NAME: YOUR_NAME_modENCODE_Galaxy_Instance
    Label or name of your modENCODE Galaxy instance. Default value is 'YOUR_NAME_modENCODE_Galaxy_Instance'.
  CLUSTER_NAME: YOUR_NAME_modENCODE_Galaxy_Cluster
    Galaxy cluster name.  Default value is 'YOUR_NAME_modENCODE_Galaxy_Cluster'.

  AMI: ami-da58aab3
    Latest Galaxy AMI ID.  Default value is 'ami-da58aab3'.  For the latest AMI, 
    see http://wiki.g2.bx.psu.edu/CloudMan/AWS/GettingStarted
  INSTANCE_TYPE: m1.medium
    Amazon instance type.  Default value is 'm1.medium' ( recommended ).
    For other Amazon instance types, see http://aws.amazon.com/ec2/instance-types
  REGION: us-east-1
    Amazon regioin to create modENCODE Galaxy instance in.  Default value is 'us-east-1'.
  AVAILABILITY_ZONE: us-east-1a
    Amazon zone to create modENCODE Galaxy instance in.  Default value is 'us-east-1a'.

NOTE: At the moment, Galaxy is supported only in US East region - see http://wiki.g2.bx.psu.edu/CloudMan.


Step 5. Launch an instance of modENCODE Galaxy using bin/modENCODE_galaxy_create.pl.  Run the script by itself to 
get its usage.  To launch modENCODE Galaxy instance with the configuration file created in Step 4, do the 
following:

  > bin/modENCODE_galaxy_create.pl  config.txt 

  Your modENCODE Galaxy instance may take a couple of minutes to start.  For your convenience, this script 
also outputs your Galaxy URL, your CloudMan console URL, and the ssh command to login to your modENCODE Galaxy.  
The Galaxy URL, CloudMan console URL, and the ssh command should look something like:

Galaxy URL:
  ec2-xx-xx-xx-xx.compute-1.amazonaws.com

CloudMan console URL:
  ec2-xx-xx-xx-xx.compute-1.amazonaws.com/cloud

ssh command:
  ssh -i KEY_FILE.pem ubuntu@ec2-xx-xx-xx-xx.compute-1.amazonaws.com


  Once Galaxy has started, go to your CloudMan console to configure your modENCODE Galaxy instance. 
If you get an error message in your browser, then your CloudMan console is not ready yet.
Wait for a few seconds and reload your CloudMan console.  To login to your CloudMan console, leave the 
username field blank and use the password as indicated in 'config.txt' in Step 4.  

In your Initial Cluster Configuration dialog box, click on 'Show more start up options' and then select 
'Galaxy Cluster' and input your initial storage size.  Your initial storage size depends on the number
of data sets, how large the data sets are, and how many analysis you are planning to do.  For the purpose 
of getting things up and running, input 10Gb as your initial storage size.  Click on 'Choose CloudMan Platform'. 
NOTE: be sure to increase your initial storage size if you are analyzing many data sets or large data sets.


Step 6. Check to make sure all Galaxy services have started.  Go to your CloudMan console and click on 'Admin' 
( top right of your browser ).  Scroll down to 'Services controls' and check to make sure status for Galaxy, 
PostgreSQL, SGE, and File systems are in 'Running' state.    These four services should start automatically.
Reload and wait until all of these services have started.  

NOTE: These four services should start within 10 minutes.  If the services don't start after 5 minutes then
there is something wrong!  Please contact help@modencode.org for help if this is the case.
  
  Once all four Galaxy services have started successfully, go to your Galaxy URL in a browser, and you should 
see: (1) the usual Galaxy tools in your Galaxy Tools panel on the left; (2) 'Welcome to Galaxy on the Cloud' 
logo in your working panel.


Step 7. Before any analysis, you will need one or more additional compute nodes for your analysis.
The number of compute nodes to add depends on the number of data sets, how large your data set is, and
how many analysis you want to do with your data.  For the purpose of showing how to use modENCODE DCC tools,
start one additional compute node.  Login to your CloudMan Console and click on "Add nodes" to
add one more additional compute node for your analysis.  Leave "Type of node(s)" as "Same as Master" and
click on "Start Additional Nodes".

  Wait until all your compute nodes are up and running - in your CloudMan Console, your compute nodes are up
and running when their icons are in green and black colors.


Step 8.  You are now ready to use Galaxy for your analysis.  If you want to use Galaxy to call peaks, see
instructions in docs/README.how.to.call.peaks.


Step 9. Finally, when you are done with all your analysis, terminate your Galaxy instance and its cluster.  Go to your 
CloudMan console and click on 'Terminate cluster', check off 'also delete this cluster', and click on 'Yes, power off'.
Your modENCODE Galaxy and its volumes should be terminated and delete shortly.  Use the AWS Management Console to make 
sure all nodes and volumes created by your modENCODE Galaxy are terminated and deleted.  

And that's it!  Happy Computing!
--
modENCODE DCC
help@modencode.org