X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/e3c431740907c8dd112a308519af423d906ee2fc..5fcca42249b8b35f50beb9ed4c51d090d76c1767:/doc/install/arvbox.html.textile.liquid?ds=sidebyside diff --git a/doc/install/arvbox.html.textile.liquid b/doc/install/arvbox.html.textile.liquid index f736b58e52..3fbd33928a 100644 --- a/doc/install/arvbox.html.textile.liquid +++ b/doc/install/arvbox.html.textile.liquid @@ -3,43 +3,76 @@ 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
-arvados/tools/arvbox/bin$ ./arvbox start localdemo +$ git clone https://github.com/arvados/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
-Arvados-in-a-box - -arvbox (build|start|run|open|shell|ip|stop|reboot|reset|destroy|log|svrestart) - -build-h2. Requirements +h2. Install root certificate -* 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 +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 certificate using @arvbox root-cert@ +# Go to the certificate manager in your browser. +#* In Chrome, this can be found under "Settings → Advanced → Manage Certificates" or by entering @chrome://settings/certificates@ in the URL bar. +#* In Firefox, this can be found under "Preferences → Privacy & Security" or entering @about:preferences#privacy@ in the URL bar and then choosing "View Certificates...". +# Select the "Authorities" tab, then press the "Import" button. Choose @arvbox-root-cert.pem@ + +The certificate will be added under the "Arvados testing" organization as "arvbox testing root CA". + +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): + +# copy @arvbox-root-cert.pem@ to @/usr/local/share/ca-certificates/@ +# run @/usr/sbin/update-ca-certificates@ h2. Configs @@ -55,15 +88,19 @@ Demo configuration. Boots a complete Arvados environment inside the container. 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 -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. WARNING! The public arvbox configuration is NOT SECURE and must not be placed on a public IP address or used for production work. +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. WARNING! The public arvbox configuration is NOT SECURE and must not be placed on a public IP address or used for production work. +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 @@ -106,6 +143,27 @@ 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@: + +build arvbox Docker image -start|run 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 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 -sv change state of service inside arvbox -clone clone an arvbox +$ arvbox +Arvados-in-a-box https://doc.arvados.org/install/arvbox.html + +start|run [tag] start arvbox container +stop stop arvbox container +restart 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 stop, pull latest image, run +build build arvbox Docker image +reboot stop, build arvbox Docker image, run +rebuild build arvbox Docker image, no layer cache +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 dev arvbox
+$ 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.