doc/install/arvbox.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Arvados-in-a-box
   5 ...
   6
   7 Arvbox is a Docker-based self-contained development, demonstration and testing environment for Arvados.  It is not intended for production use.
   8
   9 h2. Quick start
  10
  11 <pre>
  12 $ git clone https://github.com/curoverse/arvados.git
  13 $ cd arvados/tools/arvbox/bin
  14 $ ./arvbox start localdemo
  15 </pre>
  16
  17 h2. Requirements
  18
  19 * Linux 3.x+ and Docker 1.9+
  20 * Minimum of 3 GiB of RAM  + additional memory to run jobs
  21 * Minimum of 3 GiB of disk + storage for actual data
  22
  23 h2. Usage
  24
  25 <pre>
  26 $ arvbox
  27 Arvados-in-a-box                      http://arvados.org
  28
  29 arvbox (build|start|run|open|shell|ip|stop|rebuild|reset|destroy|log|svrestart)
  30
  31 build <config>      build arvbox Docker image
  32 start|run <config>  start arvbox container
  33 open       open arvbox workbench in a web browser
  34 shell      enter arvbox shell
  35 ip         print arvbox docker container ip address
  36 host       print arvbox published host
  37 status     print some information about current arvbox
  38 stop       stop arvbox container
  39 restart <config>  stop, then run again
  40 rebuild  <config>  stop, build arvbox Docker image, run
  41 reset      delete arvbox arvados data (be careful!)
  42 destroy    delete all arvbox code and data (be careful!)
  43 log <service> tail log of specified service
  44 ls <options>  list directories inside arvbox
  45 cat <files>   get contents of files inside arvbox
  46 pipe       run a bash script piped in from stdin
  47 sv <start|stop|restart> <service> change state of service inside arvbox
  48 clone <from> <to>   clone an arvbox
  49 </pre>
  50
  51 h2. Configs
  52
  53 h3. dev
  54
  55 Development configuration.  Boots a complete Arvados environment inside the container.  The "arvados", "arvado-dev" and "sso-devise-omniauth-provider" code directories along data directories "postgres", "var", "passenger" and "gems" are bind mounted from the host file system for easy access and persistence across container rebuilds.  Services are bound to the Docker container's network IP address and can only be accessed on the local host.
  56
  57 In "dev" mode, you can override the default autogenerated settings of Rails projects by adding "application.yml.override" to any Rails project (sso, api, workbench).  This can be used to test out API server settings or point Workbench at an alternate API server.
  58
  59 h3. localdemo
  60
  61 Demo configuration.  Boots a complete Arvados environment inside the container. Unlike the development configuration, code directories are included in the demo image, and data directories are stored in a separate data volume container. Services are bound to the Docker container's network IP address and can only be accessed on the local host.
  62
  63 h3. test
  64
  65 Run the test suite.
  66
  67 h3. publicdev
  68
  69 Publicly accessible development configuration.  Similar to 'dev' except that service ports are published to the host's IP address and can accessed by anyone who can connect to the host system.  See below for more information.  WARNING! The public arvbox configuration is NOT SECURE and must not be placed on a public IP address or used for production work.
  70
  71 h3. publicdemo
  72
  73 Publicly accessible development configuration.  Similar to 'localdemo' except that service ports are published to the host's IP address and can accessed by anyone who can connect to the host system.  See below for more information.  WARNING! The public arvbox configuration is NOT SECURE and must not be placed on a public IP address or used for production work.
  74
  75 h2. Environment variables
  76
  77 h3. ARVBOX_DOCKER
  78
  79 The location of Dockerfile.base and associated files used by "arvbox build".
  80 default: result of $(readlink -f $(dirname $0)/../lib/arvbox/docker)
  81
  82 h3. ARVBOX_CONTAINER
  83
  84 The name of the Docker container to manipulate.
  85 default: arvbox
  86
  87 h3. ARVBOX_BASE
  88
  89 The base directory to store persistent data for arvbox containers.
  90 default: $HOME/.arvbox
  91
  92 h3. ARVBOX_DATA
  93
  94 The base directory to store persistent data for the current container.
  95 default: $ARVBOX_BASE/$ARVBOX_CONTAINER
  96
  97 h3. ARVADOS_ROOT
  98
  99 The root directory of the Arvados source tree
 100 default: $ARVBOX_DATA/arvados
 101
 102 h3. ARVADOS_DEV_ROOT
 103
 104 The root directory of the Arvados-dev source tree
 105 default: $ARVBOX_DATA/arvados-dev
 106
 107 h3. SSO_ROOT
 108
 109 The root directory of the SSO source tree
 110 default: $ARVBOX_DATA/sso-devise-omniauth-provider
 111
 112 h3. ARVBOX_PUBLISH_IP
 113
 114 The IP address on which to publish services when running in public configuration.  Overrides default detection of the host's IP address.
 115
 116 h2. Using Arvbox for Arvados development
 117
 118 The "Arvbox section of Hacking Arvados":https://dev.arvados.org/projects/arvados/wiki/Arvbox has information about using Arvbox for Arvados development.
 119
 120 h2. Making Arvbox accessible from other hosts
 121
 122 In "dev" and "localdemo" mode, Arvbox can only be accessed on the same host it is running.  To publish Arvbox service ports to the host's service ports and advertise the host's IP address for services, use @publicdev@ or @publicdemo@:
 123
 124 <pre>
 125 $ arvbox rebuild publicdemo
 126 </pre>
 127
 128 This attempts to auto-detect the correct IP address to use by taking the IP address of the default route device.  If the auto-detection is wrong, you want to publish a hostname instead of a raw address, or you need to access it through a different device (such as a router or firewall), set @ARVBOX_PUBLISH_IP@ to the desire hostname or IP address.
 129
 130 <pre>
 131 $ export ARVBOX_PUBLISH_IP=example.com
 132 $ arvbox rebuild publicdemo
 133 </pre>
 134
 135 Note: this expects to bind the host's port 80 (http) for workbench, so you cannot have a conflicting web server already running on the host.  It does not attempt to take bind the host's port 22 (ssh), as a result the arvbox ssh port is not published.
 136
 137 h2. Notes
 138
 139 Services are designed to install and auto-configure on start or restart.  For example, the service script for keepstore always compiles keepstore from source and registers the daemon with the API server.
 140
 141 Services are run with process supervision, so a service which exits will be restarted.  Dependencies between services are handled by repeatedly trying and failing the service script until dependencies are fulfilled (by other service scripts) enabling the service script to complete.