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 $ curl -O https://git.arvados.org/arvados.git/blob_plain/refs/heads/main:/tools/arvbox/bin/arvbox
  18 $ chmod +x arvbox
  19 $ ./arvbox start localdemo
  20 $ ./arvbox root-cert
  21 $ ./arvbox adduser demouser demo@example.com
  22 </pre>
  23
  24 You will then need to "install the arvbox root certificate":#root-cert .  After that, you can now log in to Workbench as @demouser@ with the password you selected.
  25
  26 h2. Requirements
  27
  28 * Linux 3.x+ and Docker 1.10+
  29 * Minimum of 3 GiB of RAM  + additional memory to run jobs
  30 * Minimum of 3 GiB of disk + storage for actual data
  31
  32 h2. Usage
  33
  34 <pre>
  35 $ arvbox
  36 Arvados-in-a-box             https://doc.arvados.org/install/arvbox.html
  37
  38 start|run <config> [tag]   start arvbox container
  39 stop               stop arvbox container
  40 restart <config>   stop, then run again
  41 status             print some information about current arvbox
  42 ip                 print arvbox docker container ip address
  43 host               print arvbox published host
  44 shell              enter shell as root
  45 ashell             enter shell as 'arvbox'
  46 psql               enter postgres console
  47 open               open arvbox workbench in a web browser
  48 root-cert          get copy of root certificate
  49 update  <config>   stop, pull latest image, run
  50 build   <config>   build arvbox Docker image
  51 reboot  <config>   stop, build arvbox Docker image, run
  52 rebuild <config>   build arvbox Docker image, no layer cache
  53 checkpoint         create database backup
  54 restore            restore checkpoint
  55 hotreset           reset database and restart API without restarting container
  56 reset              delete arvbox arvados data (be careful!)
  57 destroy            delete all arvbox code and data (be careful!)
  58 log <service>      tail log of specified service
  59 ls <options>       list directories inside arvbox
  60 cat <files>        get contents of files inside arvbox
  61 pipe               run a bash script piped in from stdin
  62 sv <start|stop|restart> <service>
  63                    change state of service inside arvbox
  64 clone <from> <to>  clone dev arvbox
  65 adduser <username> <email>
  66                    add a user login
  67 removeuser <username>
  68                    remove user login
  69 listusers          list user logins
  70 </pre>
  71
  72 h2(#root-cert). Install root certificate
  73
  74 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.
  75
  76 # Export the certificate using @arvbox root-cert@
  77 # Go to the certificate manager in your browser.
  78 #* In Chrome, this can be found under "Settings &rarr; Advanced &rarr; Manage Certificates" or by entering @chrome://settings/certificates@ in the URL bar.
  79 #* 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...".
  80 # Select the "Authorities" tab, then press the "Import" button.  Choose @arvbox-root-cert.pem@
  81
  82 The certificate will be added under the "Arvados testing" organization as "arvbox testing root CA".
  83
  84 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.
  85
  86 h3. On Debian/Ubuntu:
  87
  88 <notextile>
  89 <pre><code>cp arvbox-root-cert.pem /usr/local/share/ca-certificates/
  90 /usr/sbin/update-ca-certificates
  91 </code></pre>
  92 </notextile>
  93
  94 h3. On CentOS:
  95
  96 <notextile>
  97 <pre><code>cp arvbox-root-cert.pem /etc/pki/ca-trust/source/anchors/
  98 /usr/bin/update-ca-trust
  99 </code></pre>
 100 </notextile>
 101
 102 h2. Configs
 103
 104 h3. dev
 105
 106 Development configuration.  Boots a complete Arvados environment inside the container.  The "arvados" and "arvados-dev" 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.
 107
 108 In "dev" mode, you can override the default autogenerated settings of Rails projects by adding "application.yml.override" to any Rails project (api, workbench).  This can be used to test out API server settings or point Workbench at an alternate API server.
 109
 110 h3. localdemo
 111
 112 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.
 113
 114 h3. test
 115
 116 Starts postgres and initializes the API server, then runs the Arvados test suite.  Will pass command line arguments to test runner.  Supports test runner interactive mode.
 117
 118 h3. devenv
 119
 120 Starts a minimal container with no services and the host's $HOME bind mounted inside the container, then enters an interactive login shell.  Intended to make it convenient to use tools installed in arvbox that don't require services.
 121
 122 h3. publicdev
 123
 124 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.
 125
 126 h3. publicdemo
 127
 128 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.
 129
 130 h2. Environment variables
 131
 132 h3. ARVBOX_DOCKER
 133
 134 The location of Dockerfile.base and associated files used by "arvbox build".
 135 default: result of $(readlink -f $(dirname $0)/../lib/arvbox/docker)
 136
 137 h3. ARVBOX_CONTAINER
 138
 139 The name of the Docker container to manipulate.
 140 default: arvbox
 141
 142 h3. ARVBOX_BASE
 143
 144 The base directory to store persistent data for arvbox containers.
 145 default: $HOME/.arvbox
 146
 147 h3. ARVBOX_DATA
 148
 149 The base directory to store persistent data for the current container.
 150 default: $ARVBOX_BASE/$ARVBOX_CONTAINER
 151
 152 h3. ARVADOS_ROOT
 153
 154 The root directory of the Arvados source tree
 155 default: $ARVBOX_DATA/arvados
 156
 157 h3. ARVADOS_DEV_ROOT
 158
 159 The root directory of the Arvados-dev source tree
 160 default: $ARVBOX_DATA/arvados-dev
 161
 162 h3. ARVBOX_PUBLISH_IP
 163
 164 The IP address on which to publish services when running in public configuration.  Overrides default detection of the host's IP address.
 165
 166 h2. Using Arvbox for Arvados development
 167
 168 The "Arvbox section of Hacking Arvados":https://dev.arvados.org/projects/arvados/wiki/Arvbox has information about using Arvbox for Arvados development.
 169
 170 h2. Making Arvbox accessible from other hosts
 171
 172 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@:
 173
 174 <pre>
 175 $ arvbox start publicdemo
 176 </pre>
 177
 178 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.
 179
 180 <pre>
 181 $ export ARVBOX_PUBLISH_IP=example.com
 182 $ arvbox start publicdemo
 183 </pre>
 184
 185 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.
 186
 187 h2. Notes
 188
 189 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.
 190
 191 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.