18874: Merge commit '6f8dcb2b13f3058db656908fb26b09e23b527f08' into 18874-merge-wb2
[arvados.git] / 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. Requirements
15
16 * Linux 3.x+ and Docker 1.10+
17 * Minimum of 4 GiB of RAM  + additional memory to run jobs
18 * Minimum of 4 GiB of disk + storage for actual data
19
20 h2. Quick start
21
22 {% include 'branchname' %}
23
24 <notextile>
25 <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>
26 $ <span class="userinput">chmod +x arvbox</span>
27 $ <span class="userinput">./arvbox start localdemo</span>
28
29 Arvados-in-a-box starting
30
31 Waiting for workbench2 websockets workbench webshell keep-web controller keepproxy api keepstore1 arv-git-httpd keepstore0 sdk vm ...
32
33 ...
34
35 Your Arvados-in-a-box is ready!
36
37 $ <span class="userinput">./arvbox adduser demouser demo@example.com</span>
38 Password for demouser:
39 Added demouser
40 </code></pre>
41 </notextile>
42
43 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.
44
45 h2(#root-cert). Install root certificate
46
47 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.
48
49 Export the root certificate with this command:
50
51 <pre>
52 $ ./arvbox root-cert
53 Certificate copied to /home/ubuntu/arvbox-root-cert.crt
54 </pre>
55
56 {% assign ca_cert_name = 'arvbox-root-cert.crt' %}
57
58 {% include 'install_ca_cert' %}
59
60 h2. Usage
61
62 <pre>
63 $ arvbox
64 Arvados-in-a-box             https://doc.arvados.org/install/arvbox.html
65
66 start|run <config> [tag]   start arvbox container
67 stop               stop arvbox container
68 restart <config>   stop, then run again
69 status             print some information about current arvbox
70 ip                 print arvbox docker container ip address
71 host               print arvbox published host
72 shell              enter shell as root
73 ashell             enter shell as 'arvbox'
74 psql               enter postgres console
75 open               open arvbox workbench in a web browser
76 root-cert          get copy of root certificate
77 update  <config>   stop, pull latest image, run
78 build   <config>   build arvbox Docker image
79 reboot  <config>   stop, build arvbox Docker image, run
80 rebuild <config>   build arvbox Docker image, no layer cache
81 checkpoint         create database backup
82 restore            restore checkpoint
83 hotreset           reset database and restart API without restarting container
84 reset              delete arvbox arvados data (be careful!)
85 destroy            delete all arvbox code and data (be careful!)
86 log <service>      tail log of specified service
87 ls <options>       list directories inside arvbox
88 cat <files>        get contents of files inside arvbox
89 pipe               run a bash script piped in from stdin
90 sv <start|stop|restart> <service>
91                    change state of service inside arvbox
92 clone <from> <to>  clone dev arvbox
93 adduser <username> <email> [password]
94                    add a user login
95 removeuser <username>
96                    remove user login
97 listusers          list user logins
98 </pre>
99
100 h2. Configs
101
102 h3. dev
103
104 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.
105
106 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.
107
108 h3. localdemo
109
110 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.
111
112 h3. test
113
114 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.
115
116 h3. devenv
117
118 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.
119
120 h3. publicdev
121
122 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.
123
124 h3. publicdemo
125
126 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.
127
128 h2. Environment variables
129
130 h3. ARVBOX_DOCKER
131
132 The location of Dockerfile.base and associated files used by "arvbox build".
133 default: result of $(readlink -f $(dirname $0)/../lib/arvbox/docker)
134
135 h3. ARVBOX_CONTAINER
136
137 The name of the Docker container to manipulate.
138 default: arvbox
139
140 h3. ARVBOX_BASE
141
142 The base directory to store persistent data for arvbox containers.
143 default: $HOME/.arvbox
144
145 h3. ARVBOX_DATA
146
147 The base directory to store persistent data for the current container.
148 default: $ARVBOX_BASE/$ARVBOX_CONTAINER
149
150 h3. ARVADOS_ROOT
151
152 The root directory of the Arvados source tree
153 default: $ARVBOX_DATA/arvados
154
155 h3. ARVADOS_DEV_ROOT
156
157 The root directory of the Arvados-dev source tree
158 default: $ARVBOX_DATA/arvados-dev
159
160 h3. ARVBOX_PUBLISH_IP
161
162 The IP address on which to publish services when running in public configuration.  Overrides default detection of the host's IP address.
163
164 h2. Using Arvbox for Arvados development
165
166 The "Arvbox section of Hacking Arvados":https://dev.arvados.org/projects/arvados/wiki/Arvbox has information about using Arvbox for Arvados development.
167
168 h2. Making Arvbox accessible from other hosts
169
170 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@:
171
172 <pre>
173 $ arvbox start publicdemo
174 </pre>
175
176 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.
177
178 <pre>
179 $ export ARVBOX_PUBLISH_IP=example.com
180 $ arvbox start publicdemo
181 </pre>
182
183 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.
184
185 h2. Notes
186
187 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.
188
189 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.