README.md

   1 # Arvados-in-a-box
   2
   3 Self-contained development, demonstration and testing environment for Arvados.
   4
   5 ## Quick start
   6
   7 ```
   8 $ bin/arvbox reboot localdemo
   9 ```
  10
  11 ## Usage
  12
  13 ```
  14 Arvados-in-a-box
  15
  16 arvbox (build|start|run|open|shell|ip|stop|reboot|reset|destroy|log|svrestart)
  17
  18 build <config>      build arvbox Docker image
  19 start|run <config>  start arvbox container
  20 open       open arvbox workbench in a web browser
  21 shell      enter arvbox shell
  22 ip         print arvbox ip address
  23 stop       stop arvbox container
  24 restart <config>  stop, then run again
  25 reboot  <config>  stop, build arvbox Docker image, run
  26 reset      delete arvbox arvados data (be careful!)
  27 destroy    delete all arvbox code and data (be careful!)
  28 log       <service> tail log of specified service
  29 svrestart <service> restart specified service inside arvbox
  30 clone <from> <to>   clone an arvbox
  31 ```
  32
  33 ## Requirements
  34
  35 * Linux 3.x+ and Docker 1.9+
  36 * Minimum of 3 GiB of RAM  + additional memory to run jobs
  37 * Minimum of 3 GiB of disk + storage for actual data
  38
  39 ## Configs
  40
  41 ### dev
  42 Development configuration.  Boots a complete Arvados environment inside the
  43 container.  The "arvados", "arvado-dev" and "sso-devise-omniauth-provider" code
  44 directories along data directories "postgres", "var", "passenger" and "gems"
  45 are bind mounted from the host file system for easy access and persistence
  46 across container rebuilds.  Services are bound to the Docker container's
  47 network IP address and can only be accessed on the local host.
  48
  49 In "dev" mode, you can override the default autogenerated settings of Rails
  50 projects by adding "application.yml.override" to any Rails project (sso, api,
  51 workbench).  This can be used to test out API server settings or point
  52 Workbench at an alternate API server.
  53
  54 ### localdemo
  55 Demo configuration.  Boots a complete Arvados environment inside the container.
  56 Unlike the development configuration, code directories are included in the demo
  57 image, and data directories are stored in a separate data volume container.
  58 Services are bound to the Docker container's network IP address and can only be
  59 accessed on the local host.
  60
  61 ### test
  62 Run the test suite.
  63
  64 ### publicdev
  65 Publicly accessible development configuration.  Similar to 'dev' except that
  66 service ports are published to the host's IP address and can accessed by anyone
  67 who can connect to the host system.  WARNING! The public arvbox configuration
  68 is NOT SECURE and must not be placed on a public IP address or used for
  69 production work.
  70
  71 ### publicdemo
  72 Publicly accessible development configuration.  Similar to 'localdemo' except
  73 that service ports are published to the host's IP address and can accessed by
  74 anyone who can connect to the host system.  WARNING! The public arvbox configuration
  75 is NOT SECURE and must not be placed on a public IP address or used for
  76 production work.
  77
  78 ## Environment variables
  79
  80 ### ARVBOX_DOCKER
  81 The location of Dockerfile.base and associated files used by "arvbox build".
  82 default: result of $(readlink -f $(dirname $0)/../lib/arvbox/docker)
  83
  84 ### ARVBOX_CONTAINER
  85 The name of the Docker container to manipulate.
  86 default: arvbox
  87
  88 ### ARVBOX_BASE
  89 The base directory to store persistent data for arvbox containers.
  90 default: $HOME/.arvbox
  91
  92 ### ARVBOX_DATA
  93 The base directory to store persistent data for the current container.
  94 default: $ARVBOX_BASE/$ARVBOX_CONTAINER
  95
  96 ### ARVADOS_ROOT
  97 The root directory of the Arvados source tree
  98 default: $ARVBOX_DATA/arvados
  99
 100 ### ARVADOS_DEV_ROOT
 101 The root directory of the Arvados-dev source tree
 102 default: $ARVBOX_DATA/arvados-dev
 103
 104 ### SSO_ROOT
 105 The root directory of the SSO source tree
 106 default: $ARVBOX_DATA/sso-devise-omniauth-provider
 107
 108 ### ARVBOX_PUBLISH_IP
 109 The IP address on which to publish services when running in public
 110 configuration.  Overrides default detection of the host's IP address.
 111
 112 ## Notes
 113
 114 Services are designed to install and auto-configure on start or restart.  For
 115 example, the service script for keepstore always compiles keepstore from source
 116 and registers the daemon with the API server.
 117
 118 Services are run with process supervision, so a service which exits will be
 119 restarted.  Dependencies between services are handled by repeatedly trying and
 120 failing the service script until dependencies are fulfilled (by other service
 121 scripts) enabling the service script to complete.