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. Requirements
+
+* Linux 3.x+ and Docker 1.10+
+* Minimum of 4 GiB of RAM + additional memory to run jobs
+* Minimum of 4 GiB of disk + storage for actual data
+
h2. Quick start
+{% include 'branchname' %}
+
+<notextile>
+<pre><code>$ <span class="userinput">curl -O <a href="https://git.arvados.org/arvados.git/blob_plain/refs/heads/{{branchname}}:/tools/arvbox/bin/arvbox">https://git.arvados.org/arvados.git/blob_plain/refs/heads/{{branchname}}:/tools/arvbox/bin/arvbox</a></span>
+$ <span class="userinput">chmod +x arvbox</span>
+$ <span class="userinput">./arvbox start localdemo</span>
+
+Arvados-in-a-box starting
+
+Waiting for workbench2 websockets workbench webshell keep-web controller keepproxy api keepstore1 keepstore0 sdk vm ...
+
+...
+
+Your Arvados-in-a-box is ready!
+
+$ <span class="userinput">./arvbox adduser demouser demo@example.com</span>
+Password for demouser:
+Added demouser
+</code></pre>
+</notextile>
+
+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.
+
+h2(#root-cert). Install root certificate
+
+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.
+
+Export the root certificate with this command:
+
<pre>
-$ git clone https://github.com/curoverse/arvados.git
-$ cd arvados/tools/arvbox/bin
-$ ./arvbox start localdemo
+$ ./arvbox root-cert
+Certificate copied to /home/ubuntu/arvbox-root-cert.crt
</pre>
-h2. Requirements
+{% assign ca_cert_name = 'arvbox-root-cert.crt' %}
-* 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
+{% include 'install_ca_cert' %}
h2. Usage
<pre>
-Arvados-in-a-box
-
-arvbox (build|start|run|open|shell|ip|stop|reboot|reset|destroy|log|svrestart)
-
-build <config> build arvbox Docker image
-start|run <config> start arvbox container
-open open arvbox workbench in a web browser
-shell enter arvbox shell
-ip print arvbox ip address
-status print some information about current arvbox
-stop stop arvbox container
-restart <config> stop, then run again
-reboot <config> stop, build arvbox Docker image, run
-reset delete arvbox arvados data (be careful!)
-destroy delete all arvbox code and data (be careful!)
-log <service> tail log of specified service
-sv <start|stop|restart> <service> change state of service inside arvbox
-clone <from> <to> clone an arvbox
+$ arvbox
+Arvados-in-a-box https://doc.arvados.org/install/arvbox.html
+
+start|run <config> [tag] start arvbox container
+stop stop arvbox container
+restart <config> stop, then run again
+status print some information about current arvbox
+ip print arvbox docker container ip address
+host print arvbox published host
+shell enter shell as root
+ashell enter shell as 'arvbox'
+psql enter postgres console
+open open arvbox workbench in a web browser
+root-cert get copy of root certificate
+update <config> stop, pull latest image, run
+build <config> build arvbox Docker image
+reboot <config> stop, build arvbox Docker image, run
+rebuild <config> build arvbox Docker image, no layer cache
+checkpoint create database backup
+restore restore checkpoint
+hotreset reset database and restart API without restarting container
+reset delete arvbox arvados data (be careful!)
+destroy delete all arvbox code and data (be careful!)
+log <service> tail log of specified service
+ls <options> list directories inside arvbox
+cat <files> get contents of files inside arvbox
+pipe run a bash script piped in from stdin
+sv <start|stop|restart> <service>
+ change state of service inside arvbox
+clone <from> <to> clone dev arvbox
+adduser <username> <email> [password]
+ add a user login
+removeuser <username>
+ remove user login
+listusers list user logins
</pre>
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.
+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.
-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.
+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.
h3. localdemo
h3. test
-Run the test suite.
+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.
+
+h3. devenv
+
+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.
h3. publicdev
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.
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@:
<pre>
-$ arvbox reboot publicdemo
+$ arvbox start publicdemo
</pre>
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.
<pre>
$ export ARVBOX_PUBLISH_IP=example.com
-$ arvbox reboot publicdemo
+$ arvbox start publicdemo
</pre>
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.
projects / arvados.git / blobdiff