README.md

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