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 @5565778cf15ae9af22ad392053430213e9016631@ here.
  37
  38 <pre>
  39 the_version=5565778cf15ae9af22ad392053430213e9016631
  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 &darr;
  66
  67 <pre>
  68 {
  69  "kind":"arvados#job",
  70  "etag":"dwbrasqcozpjsqtfshzdjfiii",
  71  "uuid":"qr1hi-8i9sb-3i0yi357k0mauwz",
  72 ...
  73  "script":"hash",
  74  "script_parameters":{
  75   "input":"33a9f3842b01ea3fdf27cc582f5ea2af"
  76  },
  77  "script_version":"5565778cf15ae9af22ad392053430213e9016631",
  78 ...
  79 }
  80 </pre>
  81
  82 h3. Monitor job progress
  83
  84 Go to Workbench, drop down the Compute menu, and click Jobs. The job you submitted should appear at the top of the list.
  85
  86 Hit "Refresh" until it finishes.
  87
  88 You can also watch the log messages while the job runs:
  89
  90 <pre>
  91 curl -s -H "Authorization: OAuth2 $ARVADOS_API_TOKEN" \
  92   https://{{ site.arvados_api_host }}/arvados/v1/jobs/JOB_UUID_HERE/log_tail_follow
  93 </pre>
  94
  95 h3. Inspect the job output
  96
  97 Find the output of the job by looking at the Jobs page (in the Compute menu) in Workbench, or by using the API:
  98
  99 <pre>
 100 arv -h job get --uuid JOB_UUID_HERE
 101 </pre>
 102
 103 The output locator will look like <code>5894dfae5d6d8edf135f0ea3dba849c2+62+K@qr1hi</code>.
 104
 105 List the files in the collection:
 106
 107 <pre>
 108 arv keep ls 5894dfae5d6d8edf135f0ea3dba849c2+62+K@qr1hi
 109 </pre>
 110
 111 &darr;
 112
 113 <pre>
 114 md5sum.txt
 115 </pre>
 116
 117 Show the contents of the md5sum.txt file:
 118
 119 <pre>
 120 arv keep less 5894dfae5d6d8edf135f0ea3dba849c2+62+K@qr1hi/md5sum.txt
 121 </pre>
 122
 123 h3. Inspect the code
 124
 125 The @script@ and @script_version@ attributes of a Job allow you to confirm the code that was used to run the job. Specifically, @script@ refers to a file in the @/crunch_scripts@ directory in the tree indicated by the commit hash @script_version@.
 126
 127 Example:
 128
 129 <pre>
 130 cd
 131 git clone git://github.com/clinicalfuture/arvados.git
 132 cd arvados
 133 git checkout $the_version
 134 less crunch_scripts/hash
 135 </pre>