doc/install/arvbox.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Arvados-in-a-box
   5 ...
   6 {% comment %}
   7 Copyright (C) The Arvados Authors. All rights reserved.
   8
   9 SPDX-License-Identifier: CC-BY-SA-3.0
  10 {% endcomment %}
  11
  12 Arvbox is a Docker-based self-contained development, demonstration and testing environment for Arvados.  It is not intended for production use.
  13
  14 h2. Quick start
  15
  16 <pre>
  17 $ git clone https://github.com/curoverse/arvados.git
  18 $ cd arvados/tools/arvbox/bin
  19 $ ./arvbox start localdemo
  20 </pre>
  21
  22 h2. Requirements
  23
  24 * Linux 3.x+ and Docker 1.9+
  25 * Minimum of 3 GiB of RAM  + additional memory to run jobs
  26 * Minimum of 3 GiB of disk + storage for actual data
  27
  28 h2. Usage
  29
  30 <pre>
  31 $ arvbox
  32 Arvados-in-a-box                      http://arvados.org
  33
  34 start|run <config> [tag]  start arvbox container
  35 stop       stop arvbox container
  36 restart <config>  stop, then run again
  37 status     print some information about current arvbox
  38 ip         print arvbox docker container ip address
  39 host       print arvbox published host
  40 shell      enter arvbox shell
  41 open       open arvbox workbench in a web browser
  42 root-cert  get copy of root certificate
  43 update  <config> stop, pull latest image, run
  44 build   <config> build arvbox Docker image
  45 reboot  <config> stop, build arvbox Docker image, run
  46 rebuild <config> build arvbox Docker image, no layer cache
  47 reset      delete arvbox arvados data (be careful!)
  48 destroy    delete all arvbox code and data (be careful!)
  49 log <service> tail log of specified service
  50 ls <options>  list directories inside arvbox
  51 cat <files>   get contents of files inside arvbox
  52 pipe       run a bash script piped in from stdin
  53 sv <start|stop|restart> <service> change state of service inside arvbox
  54 clone <from> <to>   clone an arvbox
  55 </pre>
  56
  57 h2. Install root certificate
  58
  59 Arvbox creates root certificate to authorize Arvbox services.  Installing the root certificate into your web browser will prevent security errors when accessing Arvbox services with your web browser.  Every  Arvbox instance generates a new root signing key.
  60
  61 # Export the certificate using @arvbox root-cert@
  62 # Go to the certificate manager in your browser.
  63 #* In Chrome, this can be found under "Settings &rarr; Advanced &rarr; Manage Certificates" or by entering @chrome://settings/certificates@ in the URL bar.
  64 #* In Firefox, this can be found under "Preferences &rarr; Privacy & Security" or entering @about:preferences#privacy@ in the URL bar and then choosing "View Certificates...".
  65 # Select the "Authorities" tab, then press the "Import" button.  Choose @arvbox-root-cert.pem@
  66
  67 The certificate will be added under the "Arvados testing" organization as "arvbox testing root CA".
  68
  69 To access your Arvbox instance using command line clients (such as arv-get and arv-put) without security errors, install the certificate into the OS certificate storage (instructions for Debian/Ubuntu):
  70
  71 # copy @arvbox-root-cert.pem@ to @/usr/local/share/ca-certificates/@
  72 # run @/usr/sbin/update-ca-certificates@
  73
  74 h2. Configs
  75
  76 h3. dev
  77
  78 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.
  79
  80 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.
  81
  82 h3. localdemo
  83
  84 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.
  85
  86 h3. test
  87
  88 Run the test suite.
  89
  90 h3. publicdev
  91
  92 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.
  93
  94 h3. publicdemo
  95
  96 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.
  97
  98 h2. Environment variables
  99
 100 h3. ARVBOX_DOCKER
 101
 102 The location of Dockerfile.base and associated files used by "arvbox build".
 103 default: result of $(readlink -f $(dirname $0)/../lib/arvbox/docker)
 104
 105 h3. ARVBOX_CONTAINER
 106
 107 The name of the Docker container to manipulate.
 108 default: arvbox
 109
 110 h3. ARVBOX_BASE
 111
 112 The base directory to store persistent data for arvbox containers.
 113 default: $HOME/.arvbox
 114
 115 h3. ARVBOX_DATA
 116
 117 The base directory to store persistent data for the current container.
 118 default: $ARVBOX_BASE/$ARVBOX_CONTAINER
 119
 120 h3. ARVADOS_ROOT
 121
 122 The root directory of the Arvados source tree
 123 default: $ARVBOX_DATA/arvados
 124
 125 h3. ARVADOS_DEV_ROOT
 126
 127 The root directory of the Arvados-dev source tree
 128 default: $ARVBOX_DATA/arvados-dev
 129
 130 h3. SSO_ROOT
 131
 132 The root directory of the SSO source tree
 133 default: $ARVBOX_DATA/sso-devise-omniauth-provider
 134
 135 h3. ARVBOX_PUBLISH_IP
 136
 137 The IP address on which to publish services when running in public configuration.  Overrides default detection of the host's IP address.
 138
 139 h2. Using Arvbox for Arvados development
 140
 141 The "Arvbox section of Hacking Arvados":https://dev.arvados.org/projects/arvados/wiki/Arvbox has information about using Arvbox for Arvados development.
 142
 143 h2. Making Arvbox accessible from other hosts
 144
 145 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@:
 146
 147 <pre>
 148 $ arvbox start publicdemo
 149 </pre>
 150
 151 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.
 152
 153 <pre>
 154 $ export ARVBOX_PUBLISH_IP=example.com
 155 $ arvbox start publicdemo
 156 </pre>
 157
 158 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.
 159
 160 h2. Notes
 161
 162 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.
 163
 164 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.