doc/user/topics/arv-web.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Using arv-web"
   5 ...
   6
   7 @arv-web@ enables you to run a custom web service from the contents of an Arvados collection.
   8
   9 h2. Usage
  10
  11 @arv-web@ enables you to set up a web service based on the most recent collection in a project.  An arv-web application is a reproducible, immutable application bundle where the web app is packaged with both the code to run and the data to serve.  Because Arvados Collections can be updated with minimum duplication, it is efficient to produce a new application bundle when the code or data needs to be updated; retaining old application bundles makes it easy to go back and run older versions of your web app.
  12
  13 <pre>
  14 usage: arv-web.py [-h] --project PROJECT [--port PORT] [--image IMAGE]
  15
  16 optional arguments:
  17   -h, --help         show this help message and exit
  18   --project PROJECT  Project to watch
  19   --port PORT        Local bind port
  20   --image IMAGE      Docker image to run
  21 </pre>
  22
  23 At startup, @arv-web@ queries an Arvados project and mounts the most recently modified collection into a temporary directory.  It then runs a Docker image with the collection bound to @/mnt@ inside the container.  When a new collection is added to the project, or an existing project is updated, it will stop the running Docker container, unmount the old collection, mount the new most recently modified collection, and restart the Docker container with the new mount.
  24
  25 h2. Docker container
  26
  27 The @Dockerfile@ in @arvados/docker/arv-web@ builds a Docker image that runs Apache with @/mnt@ as the DocumentRoot.  It is configured to run web applications which use Python WSGI, Ruby Rack, or CGI; to serve static HTML; or browse the contents of the @public@ subdirectory of the collection using default Apache index pages.
  28
  29 To build the Docker image:
  30
  31 <notextile>
  32 <pre><code>~$ <span class="userinput">cd arvados/docker</span>
  33 ~/arvados/docker$ <span class="userinput">docker build -t arvados/arv-web arv-web</span>
  34 </code></pre>
  35 </notextile>
  36
  37 h2. Running sample applications
  38
  39 First, in Arvados Workbench, create a new project.  Copy the project UUID from the URL bar (this is the part of the URL after @projects/...@)
  40
  41 Now upload a collection containing a "Python WSGI web app:":http://wsgi.readthedocs.org/en/latest/
  42
  43 <notextile>
  44 <pre><code>~$ <span class="userinput">cd arvados/services/arv-web</span>
  45 ~/arvados/services/arv-web$ <span class="userinput">arv-put --project [zzzzz-j7d0g-yourprojectuuid] --name sample-wsgi-app sample-wsgi-app</span>
  46 0M / 0M 100.0%
  47 Collection saved as 'sample-wsgi-app'
  48 zzzzz-4zz18-ebohzfbzh82qmqy
  49 ~/arvados/services/arv-web$ <span class="userinput">./arv-web.py --project [zzzzz-j7d0g-yourprojectuuid] --port 8888</span>
  50 2015-01-30 11:21:00 arvados.arv-web[4897] INFO: Mounting zzzzz-4zz18-ebohzfbzh82qmqy
  51 2015-01-30 11:21:01 arvados.arv-web[4897] INFO: Starting Docker container arvados/arv-web
  52 2015-01-30 11:21:02 arvados.arv-web[4897] INFO: Container id e79e70558d585a3e038e4bfbc97e5c511f21b6101443b29a8017bdf3d84689a3
  53 2015-01-30 11:21:03 arvados.arv-web[4897] INFO: Waiting for events
  54 </code></pre>
  55 </notextile>
  56
  57 The sample application will be available at @http://localhost:8888@.
  58
  59 h3. Updating the application
  60
  61 If you upload a new collection to the same project, arv-web will restart the web service and serve the new collection.  For example, uploading a collection containing a "Ruby Rack web app:":https://github.com/rack/rack/wiki
  62
  63 <notextile>
  64 <pre><code>~$ <span class="userinput">cd arvados/services/arv-web</span>
  65 ~/arvados/services/arv-web$ <span class="userinput">arv-put --project [zzzzz-j7d0g-yourprojectuuid] --name sample-rack-app sample-rack-app</span>
  66 0M / 0M 100.0%
  67 Collection saved as 'sample-rack-app'
  68 zzzzz-4zz18-dhhm0ay8k8cqkvg
  69 </code></pre>
  70 </notextile>
  71
  72 @arv-web@ will automatically notice the change, load a new container, and send an update signal (SIGHUP) to the service:
  73
  74 <pre>
  75 2015-01-30 11:21:03 arvados.arv-web[4897] INFO:Waiting for events
  76 2015-01-30 11:21:04 arvados.arv-web[4897] INFO:create zzzzz-4zz18-dhhm0ay8k8cqkvg
  77 2015-01-30 11:21:05 arvados.arv-web[4897] INFO:Mounting zzzzz-4zz18-dhhm0ay8k8cqkvg
  78 2015-01-30 11:21:06 arvados.arv-web[4897] INFO:Sending refresh signal to container
  79 2015-01-30 11:21:07 arvados.arv-web[4897] INFO:Waiting for events
  80 </pre>
  81
  82 h2. Writing your own applications
  83
  84 The @arvados/arv-web@ image serves Python and Ruby applications using Phusion Passenger and Apache @mod_passenger@.  See "Phusion Passenger users guide for Apache":https://www.phusionpassenger.com/documentation/Users%20guide%20Apache.html for details, and look at the sample apps @arvados/services/arv-web/sample-wsgi-app@ and @arvados/services/arv-web/sample-rack-app@.
  85
  86 You can serve CGI applications using standard Apache CGI support.  See "Apache Tutorial: Dynamic Content with CGI":https://httpd.apache.org/docs/current/howto/cgi.html for details, and look at the sample app @arvados/services/arv-web/sample-cgi-app@.
  87
  88 You can also serve static content from the @public@ directory of the collection.  Look at @arvados/services/arv-web/sample-static-page@ for an example.  If no @index.html@ is found in @public/@, it will render default Apache index pages, permitting simple browsing of the collection contents.
  89
  90 h3. Custom images
  91
  92 You can provide your own Docker image.  The Docker image that will be used create the web application container is specified in the "docker_image" file in the root of the collection.  Specify @--image@ on the command @arv-web@ line to override the contents of "docker_image".