--- layout: default navsection: installguide title: Arvados-in-a-box ... {% comment %} Copyright (C) The Arvados Authors. All rights reserved. SPDX-License-Identifier: CC-BY-SA-3.0 {% endcomment %} Arvbox is a Docker-based self-contained development, demonstration and testing environment for Arvados. It is not intended for production use. h2. Quick start 
$ git clone https://github.com/curoverse/arvados.git
$ cd arvados/tools/arvbox/bin
$ ./arvbox start localdemo
h2. Requirements * Linux 3.x+ and Docker 1.9+ * Minimum of 3 GiB of RAM + additional memory to run jobs * Minimum of 3 GiB of disk + storage for actual data h2. Usage 
$ arvbox
Arvados-in-a-box                      http://arvados.org

build         build arvbox Docker image
rebuild       build arvbox Docker image, no layer cache
start|run   start arvbox container
open       open arvbox workbench in a web browser
shell      enter arvbox shell
ip         print arvbox docker container ip address
host       print arvbox published host
status     print some information about current arvbox
stop       stop arvbox container
restart   stop, then run again
reboot    stop, build arvbox Docker image, run
reset      delete arvbox arvados data (be careful!)
destroy    delete all arvbox code and data (be careful!)
log  tail log of specified service
ls   list directories inside arvbox
cat    get contents of files inside arvbox
pipe       run a bash script piped in from stdin
sv   change state of service inside arvbox
clone     clone an arvbox
h2. Configs h3. dev 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. 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. h3. localdemo 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. h3. test Run the test suite. h3. publicdev 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. h3. publicdemo 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. h2. Environment variables h3. ARVBOX_DOCKER The location of Dockerfile.base and associated files used by "arvbox build". default: result of $(readlink -f $(dirname $0)/../lib/arvbox/docker) h3. ARVBOX_CONTAINER The name of the Docker container to manipulate. default: arvbox h3. ARVBOX_BASE The base directory to store persistent data for arvbox containers. default: $HOME/.arvbox h3. ARVBOX_DATA The base directory to store persistent data for the current container. default: $ARVBOX_BASE/$ARVBOX_CONTAINER h3. ARVADOS_ROOT The root directory of the Arvados source tree default: $ARVBOX_DATA/arvados h3. ARVADOS_DEV_ROOT The root directory of the Arvados-dev source tree default: $ARVBOX_DATA/arvados-dev h3. SSO_ROOT The root directory of the SSO source tree default: $ARVBOX_DATA/sso-devise-omniauth-provider h3. ARVBOX_PUBLISH_IP The IP address on which to publish services when running in public configuration. Overrides default detection of the host's IP address. h2. Using Arvbox for Arvados development The "Arvbox section of Hacking Arvados":https://dev.arvados.org/projects/arvados/wiki/Arvbox has information about using Arvbox for Arvados development. h2. Making Arvbox accessible from other hosts 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@: 
$ arvbox start publicdemo
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. 
$ export ARVBOX_PUBLISH_IP=example.com
$ arvbox start publicdemo
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. h2. Notes 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. 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.