doc/user/tutorial-job1.textile

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Tutorial: Your first job"
   5 navorder: 20
   6 ---
   7
   8 h1. Tutorial: Your first job
   9
  10 Here you will use the "arv" command line tool to run a simple Crunch script on some sample data.
  11
  12 h3. Prerequisites
  13
  14 * Log in to a VM "using SSH":ssh-access.html
  15 * Put an "API token":api-tokens.html in your @ARVADOS_API_TOKEN@ environment variable
  16 * Put the API host name in your @ARVADOS_API_HOST@ environment variable
  17
  18 If everything is set up correctly, the command @arv -h user current@ will display your account information.
  19
  20 Arv depends on a few gems. It will tell you which ones to install, if they are not present yet. If you need to install the dependencies and are doing so as a non-root user, make sure you set GEM_HOME before you run gem install:
  21
  22 <pre>
  23     export GEM_HOME=~/.gem
  24 </pre>
  25
  26 h3. Submit a job
  27
  28 We will run the "hash" program, which computes the MD5 hash of each file in a collection.
  29
  30 Pick a data collection. We'll use @33a9f3842b01ea3fdf27cc582f5ea2af@ here.
  31
  32 <pre>
  33 the_collection=33a9f3842b01ea3fdf27cc582f5ea2af
  34 </pre>
  35
  36 Pick a code version. We'll use @cdde7f246fec59bc99da86145fd4cf4efcf37a68@ here.
  37
  38 <pre>
  39 the_version=cdde7f246fec59bc99da86145fd4cf4efcf37a68
  40 </pre>
  41
  42 Make a JSON object describing the job.
  43
  44 <pre>
  45 read -rd "\000" the_job <<EOF
  46 {
  47  "script":"hash",
  48  "script_version":"$the_version",
  49  "script_parameters":
  50  {
  51   "input":"$the_collection"
  52  }
  53 }
  54 EOF
  55 </pre>
  56
  57 (The @read -rd "\000"@ stuff just helps us get a multi-line string with lots of double quotation marks into a shell variable.)
  58
  59 Submit the job.
  60
  61 <pre>
  62 arv -h job create --job "$the_job"
  63 </pre>
  64
  65 Go to Workbench, drop down the Compute menu, and click Jobs. The job you submitted should appear at the top of the list.
  66
  67 Hit "Refresh" until it finishes.
  68
  69 You can also watch the log messages while the job runs:
  70
  71 <pre>
  72 curl -s -H "Authorization: OAuth2 $ARVADOS_API_TOKEN" \
  73   https://{{ site.arvados_api_host }}/arvados/v1/jobs/JOB_UUID_HERE/log_tail_follow
  74 </pre>
  75
  76 Great. You ran a job!