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 arvados/tools/arvbox/bin$ ./arvbox start localdemo
  13 </pre>
  14
  15 h2. Usage
  16
  17 <pre>
  18 Arvados-in-a-box
  19
  20 arvbox (build|start|run|open|shell|ip|stop|reboot|reset|destroy|log|svrestart)
  21
  22 build <config>      build arvbox Docker image
  23 start|run <config>  start arvbox container
  24 open       open arvbox workbench in a web browser
  25 shell      enter arvbox shell
  26 ip         print arvbox ip address
  27 status     print some information about current arvbox
  28 stop       stop arvbox container
  29 restart <config>  stop, then run again
  30 reboot  <config>  stop, build arvbox Docker image, run
  31 reset      delete arvbox arvados data (be careful!)
  32 destroy    delete all arvbox code and data (be careful!)
  33 log       <service> tail log of specified service
  34 sv        <start|stop|restart> <service> change state of service inside arvbox
  35 clone <from> <to>   clone an arvbox
  36 </pre>
  37
  38 h2. Requirements
  39
  40 * Linux 3.x+ and Docker 1.9+
  41 * Minimum of 3 GiB of RAM  + additional memory to run jobs
  42 * Minimum of 3 GiB of disk + storage for actual data
  43
  44 h2. Configs
  45
  46 h3. dev
  47
  48 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.
  49
  50 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.
  51
  52 h3. localdemo
  53
  54 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.
  55
  56 h3. test
  57
  58 Run the test suite.
  59
  60 h3. publicdev
  61
  62 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.  WARNING! The public arvbox configuration is NOT SECURE and must not be placed on a public IP address or used for production work.
  63
  64 h3. publicdemo
  65
  66 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.  WARNING! The public arvbox configuration is NOT SECURE and must not be placed on a public IP address or used for production work.
  67
  68 h2. Environment variables
  69
  70 h3. ARVBOX_DOCKER
  71
  72 The location of Dockerfile.base and associated files used by "arvbox build".
  73 default: result of $(readlink -f $(dirname $0)/../lib/arvbox/docker)
  74
  75 h3. ARVBOX_CONTAINER
  76
  77 The name of the Docker container to manipulate.
  78 default: arvbox
  79
  80 h3. ARVBOX_BASE
  81
  82 The base directory to store persistent data for arvbox containers.
  83 default: $HOME/.arvbox
  84
  85 h3. ARVBOX_DATA
  86
  87 The base directory to store persistent data for the current container.
  88 default: $ARVBOX_BASE/$ARVBOX_CONTAINER
  89
  90 h3. ARVADOS_ROOT
  91
  92 The root directory of the Arvados source tree
  93 default: $ARVBOX_DATA/arvados
  94
  95 h3. ARVADOS_DEV_ROOT
  96
  97 The root directory of the Arvados-dev source tree
  98 default: $ARVBOX_DATA/arvados-dev
  99
 100 h3. SSO_ROOT
 101
 102 The root directory of the SSO source tree
 103 default: $ARVBOX_DATA/sso-devise-omniauth-provider
 104
 105 h3. ARVBOX_PUBLISH_IP
 106
 107 The IP address on which to publish services when running in public configuration.  Overrides default detection of the host's IP address.
 108
 109 h2. Notes
 110
 111 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.
 112
 113 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.