doc/install/install-docker.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Build and install Docker images
   5 ...
   6
   7 This method is intended for evaluation and development on a local workstation. It is not suitable for production use in a cluster deployment.
   8
   9 h2. Prerequisites
  10
  11 # A GNU/Linux (virtual) machine
  12 # A working Docker installation (see "Installing Docker":https://docs.docker.com/installation/)
  13 # A working Go installation (see "Install the Go tools":https://golang.org/doc/install)
  14 # A working Ruby installation, with the Bundler gem installed
  15
  16 h3. Install Ruby and Bundler
  17
  18 {% include 'install_ruby_and_bundler' %}
  19
  20 h2. Download the source tree
  21
  22 <notextile>
  23 <pre><code>~$ <span class="userinput">cd $HOME</span> # (or wherever you want to install)
  24 ~$ <span class="userinput">git clone https://github.com/curoverse/arvados.git</span>
  25 </code></pre></notextile>
  26
  27 See also: "Downloading the source code":https://dev.arvados.org/projects/arvados/wiki/Download on the Arvados wiki.
  28
  29 h2. Building the Arvados Docker containers
  30
  31 First of all, a suitable @config.yml@ file is needed. The easiest way to generate one based on the provided @config.yml.example@ file is to run the @build.sh@ script. If no @config.yml@ file exists, it will will prompt for a few inputs, write the @config.yml@ file, and then proceed to build all the Docker containers. If @config.yml@ exists, invoking @build.sh@ will simply build all Docker containers or update those that need to be updated.
  32
  33 Run @build.sh@ without arguments to generate @config.yml@ and build all Docker containers (this will take a while!):
  34
  35 <notextile>
  36 <pre><code>
  37 ~$ <span class="userinput">./build.sh</span>
  38 Generating config.yml.
  39 Arvados needs to know the email address of the administrative user,
  40 so that when that user logs in they are automatically made an admin.
  41 This should be an email address associated with a Google account.
  42
  43 Enter your Google ID email address here:
  44
  45 ...
  46
  47 Step 7 : ADD generated/setup.sh /usr/local/bin/setup.sh
  48  ---> d7c0e7fdf7ab
  49 Removing intermediate container f3d81180795d
  50 Step 8 : CMD ["/usr/bin/supervisord", "-n"]
  51  ---> Running in 84c64cb9f0d5
  52  ---> d6cbb5002604
  53 Removing intermediate container 84c64cb9f0d5
  54 Successfully built d6cbb5002604
  55 date >shell-image
  56 </code></pre></notextile>
  57
  58 If all goes well, you should now have a number of Docker images built (the image id will be different):
  59
  60 <notextile>
  61 <pre><code>~$ <span class="userinput">docker.io images</span>
  62 REPOSITORY              TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
  63 arvados/shell           latest              d6cbb5002604        10 minutes ago      1.613 GB
  64 arvados/sso             latest              377f1fa0108e        11 minutes ago      1.807 GB
  65 arvados/keep            latest              ade0e0d2dd00        12 minutes ago      210.8 MB
  66 arvados/keepproxy       latest              b39ef0baba02        12 minutes ago      241.6 MB
  67 arvados/workbench       latest              b0e4fb6da385        12 minutes ago      2.218 GB
  68 arvados/doc             latest              4b64daec9454        12 minutes ago      1.524 GB
  69 arvados/compute         latest              7f1f5f7faf54        13 minutes ago      1.862 GB
  70 arvados/slurm           latest              f5bfd1008e6b        17 minutes ago      1.573 GB
  71 arvados/api             latest              6b93c5f5fc42        17 minutes ago      2.274 GB
  72 arvados/passenger       latest              add2d11fdf24        18 minutes ago      1.738 GB
  73 arvados/base            latest              81eaadd0c6f5        22 minutes ago      1.463 GB
  74 arvados/debian          7.6                 f339ce275c01        6 days ago          116.8 MB
  75 arvados/debian          latest              f339ce275c01        6 days ago          116.8 MB
  76 arvados/debian          wheezy              f339ce275c01        6 days ago          116.8 MB
  77 crosbymichael/skydock   latest              e985023521f6        3 months ago        510.7 MB
  78 crosbymichael/skydns    next                79c99a4608ed        3 months ago        525 MB
  79 crosbymichael/skydns    latest              1923ce648d4c        5 months ago        137.5 MB
  80 </code></pre></notextile>
  81
  82 h2. Updating the Arvados Docker containers
  83
  84 @build.sh@ takes a few optional arguments:
  85
  86 <notextile>
  87 <pre><code>
  88 ~$ <span class="userinput"> ./build.sh --help</span>
  89
  90 usage: ./build.sh [options]
  91
  92 Calling ./build.sh without arguments will build all Arvados docker images
  93
  94 ./build.sh options:
  95   -h, --help   Print this help text
  96   clean        Clear all build information
  97   realclean    clean and remove all Arvados Docker images except arvados/debian
  98   deepclean    realclean and remove arvados/debian, crosbymichael/skydns and
  99                crosbymichael/skydns Docker images
 100 </code></pre></notextile>
 101
 102 If there has been an update to the Arvados Docker building code, it is safest to rebuild the Arvados Docker images from scratch. All build information can be cleared with the 'clean' option to build.sh:
 103
 104 <notextile>
 105 <pre><code>~$ <span class="userinput">./build.sh clean</span></code></pre>
 106 </notextile>
 107
 108 You can also use 'realclean', which does what 'clean' does and in addition removes all Arvados Docker containers and images from your system, with the exception of the arvados/debian image.
 109
 110 <notextile>
 111 <pre><code>~$ <span class="userinput">./build.sh realclean</span></code></pre>
 112 </notextile>
 113
 114 Finally, the 'deepclean' option does what 'realclean' does, and also removes the arvados/debian, crosbymichael/skydns and crosbymichael/skydock images.
 115
 116 <notextile>
 117 <pre><code>~$ <span class="userinput">./build.sh deepclean</span></code></pre>
 118 </notextile>
 119
 120 h2. Running the Arvados Docker containers
 121
 122 The @arvdock@ command can be used to start and stop the docker containers. It has a number of options:
 123
 124 <notextile>
 125 <pre><code>
 126 ~$ <span class="userinput">./arvdock -h</span>
 127
 128 usage: ./arvdock (start|stop|restart|reset|test) [options]
 129
 130 start    run new or restart stopped arvados containers
 131 stop     stop arvados containers
 132 restart  stop and then start arvados containers
 133 reset    stop and delete containers WARNING: this will delete the data inside Arvados!
 134 test     run tests
 135
 136 ./arvdock start/stop/restart options:
 137   -d[port], --doc[=port]        Documentation server (default port 9898)
 138   -w[port], --workbench[=port]  Workbench server (default port 9899)
 139   -s[port], --sso[=port]        SSO server (default port 9901)
 140   -a[port], --api[=port]        API server (default port 9900)
 141   -c, --compute                 Compute nodes (starts 2)
 142   -v, --vm                      Shell server
 143   -n, --nameserver              Nameserver
 144   -k, --keep                    Keep servers
 145   -p, --keepproxy               Keepproxy server
 146   -h, --help                    Display this help and exit
 147
 148   If no options are given, the action is applied to all servers.
 149
 150 ./arvdock test [testname] [testname] ...
 151   By default, all tests are run.
 152 </code>
 153 </pre>
 154 </notextile>
 155
 156 To debug issues with the Docker containers use @docker exec@, for example:
 157
 158 <notextile>
 159 <pre><code>
 160 ~$ <span class="userinput">docker exec -t -i api_server /bin/bash</span>
 161 </code></pre></notextile>
 162
 163 To start the docker containers:
 164
 165 <notextile>
 166 <pre><code>
 167 ~$ <span class="userinput">./arvdock start</span>
 168 start_api=false
 169 start_compute=false
 170 start_doc=false
 171 start_keep=false
 172 start_keepproxy=false
 173 start_nameserver=false
 174 start_sso=false
 175 start_vm=false
 176 start_workbench=false
 177 Starting crosbymichael/skydns container...
 178 skydns
 179 /usr/bin/docker.io run -d -p 172.17.42.1:53:53/udp --name skydns crosbymichael/skydns -nameserver 8.8.8.8:53 -domain arvados
 180 89922ec786cbd2098ed6bae205468a675657cdb2db0e0bfdfe76d1e43cb2fe35
 181 Starting crosbymichael/skydock container...
 182 skydock
 183 /usr/bin/docker.io run -d -v /var/run/docker.sock:/docker.sock --name skydock crosbymichael/skydock -ttl 30 -environment dev -s /docker.sock -domain arvados -name skydns
 184 de6a35bb20fb9063fb97218ba2554974546eed969d43b1f5aa31a1ac9576e802
 185 Starting container: api_server
 186   /usr/bin/docker.io start api_server
 187 Started container: api_server
 188 Starting container: compute0
 189   /usr/bin/docker.io start compute0
 190 Started container: compute0
 191 Starting container: compute1
 192   /usr/bin/docker.io start compute1
 193 Started container: compute1
 194 Starting container: keep_server_0
 195   /usr/bin/docker.io start keep_server_0
 196 Started container: keep_server_0
 197 Starting container: keep_server_1
 198   /usr/bin/docker.io start keep_server_1
 199 Started container: keep_server_1
 200 Starting container: keepproxy_server
 201   /usr/bin/docker.io start keepproxy_server
 202 Started container: keepproxy_server
 203 Starting container: doc_server
 204   /usr/bin/docker.io start doc_server
 205 Started container: doc_server
 206
 207 ******************************************************************
 208 You can access the Arvados documentation at http://doc.dev.arvados
 209 ******************************************************************
 210
 211 Starting container: shell
 212   /usr/bin/docker.io start shell
 213 Started container: shell
 214 Starting container: workbench_server
 215   /usr/bin/docker.io start workbench_server
 216 Started container: workbench_server
 217
 218 ********************************************************************
 219 You can access the Arvados workbench at http://workbench.dev.arvados
 220 ********************************************************************
 221
 222 *****************************************************************
 223 To access Arvados you must add the Arvados nameserver to the top
 224 of your DNS configuration in /etc/resolv.conf:
 225 nameserver 172.17.42.1
 226 ******************************************************************
 227
 228 </code></pre></notextile>
 229
 230 h2. Accessing workbench
 231
 232 Point your browser to the Dockerized workbench:
 233
 234 <notextile>
 235 <pre><code><span class="userinput">http://workbench.dev.arvados</span>
 236 </code></pre>
 237 </notextile>
 238
 239 Now use the google account you specified as @API_AUTO_ADMIN_USER@ in @config.yml@ to log in.
 240
 241 You will be prompted by your browser that you are accessing a site with an untrusted SSL certificate. This is normal; by default the Arvados Docker installation uses self-signed SSL certificates for the SSO and API servers, respectively. If you use a local SSO server in a Docker container, you will be prompted *twice*. The default is to use the Curoverse SSO server.