doc/install/salt-vagrant.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Arvados in a VM with Vagrant
   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 # "Vagrant":#vagrant
  13 # "Final steps":#final_steps
  14 ## "DNS configuration":#dns_configuration
  15 ## "Install root certificate":#ca_root_certificate
  16 # "Initial user and login":#initial_user
  17 # "Test the installed cluster running a simple workflow":#test_install
  18
  19 h2(#vagrant). Vagrant
  20
  21 {% include 'branchname' %}
  22
  23 This is a package-based installation method. Start by cloning the @{{ branchname }}@ branch from "https://git.arvados.org/arvados.git":https://git.arvados.org/arvados.git . The Salt scripts are available in the @tools/salt-install@ directory.
  24
  25 A @Vagrantfile@ is provided to install Arvados in a virtual machine on your computer using "Vagrant":https://www.vagrantup.com/.
  26
  27 To get it running, install Vagrant in your computer, edit the variables at the top of the @provision.sh@ script as needed, and run
  28
  29 <notextile>
  30 <pre><code>vagrant up
  31 </code></pre>
  32 </notextile>
  33
  34 If you want to reconfigure the running box, you can just:
  35
  36 1. edit the pillars to suit your needs
  37 2. run
  38
  39 <notextile>
  40 <pre><code>vagrant reload --provision
  41 </code></pre>
  42 </notextile>
  43
  44 h2(#final_steps). Final configuration steps
  45
  46 h3(#dns_configuration). DNS configuration
  47
  48 After the setup is done, you need to set up your DNS to be able to access the cluster.
  49
  50 The simplest way to do this is to edit your @/etc/hosts@ file (as root):
  51
  52 <notextile>
  53 <pre><code>export CLUSTER="arva2"
  54 export DOMAIN="arv.local"
  55 export HOST_IP="127.0.0.2"    # This is valid either if installing in your computer directly
  56                               # or in a Vagrant VM. If you're installing it on a remote host
  57                               # just change the IP to match that of the host.
  58 echo "${HOST_IP} api keep keep0 collections download ws workbench workbench2 ${CLUSTER}.${DOMAIN} api.${CLUSTER}.${DOMAIN} keep.${CLUSTER}.${DOMAIN} keep0.${CLUSTER}.${DOMAIN} collections.${CLUSTER}.${DOMAIN} download.${CLUSTER}.${DOMAIN} ws.${CLUSTER}.${DOMAIN} workbench.${CLUSTER}.${DOMAIN} workbench2.${CLUSTER}.${DOMAIN}" >> /etc/hosts
  59 </code></pre>
  60 </notextile>
  61
  62 h3(#ca_root_certificate). Install root certificate
  63
  64 Arvados uses SSL to encrypt communications. Its UI uses AJAX which will silently fail if the certificate is not valid or signed by an unknown Certification Authority.
  65
  66 For this reason, the @arvados-formula@ has a helper state to create a root certificate to authorize Arvados services. The @provision.sh@ script will leave a copy of the generated CA's certificate (@arvados-snakeoil-ca.pem@) in the script's directory so you can add it to your workstation.
  67
  68 Installing the root certificate into your web browser will prevent security errors when accessing Arvados services with your web browser.
  69
  70 # Go to the certificate manager in your browser.
  71 #* In Chrome, this can be found under "Settings &rarr; Advanced &rarr; Manage Certificates" or by entering @chrome://settings/certificates@ in the URL bar.
  72 #* In Firefox, this can be found under "Preferences &rarr; Privacy & Security" or entering @about:preferences#privacy@ in the URL bar and then choosing "View Certificates...".
  73 # Select the "Authorities" tab, then press the "Import" button.  Choose @arvados-snakeoil-ca.pem@
  74
  75 The certificate will be added under the "Arvados Formula".
  76
  77 To access your Arvados instance using command line clients (such as arv-get and arv-put) without security errors, install the certificate into the OS certificate storage.
  78
  79 * On Debian/Ubuntu:
  80
  81 <notextile>
  82 <pre><code>cp arvados-root-cert.pem /usr/local/share/ca-certificates/
  83 /usr/sbin/update-ca-certificates
  84 </code></pre>
  85 </notextile>
  86
  87 * On Red Hat, AlmaLinux, and Rocky Linux:
  88
  89 <notextile>
  90 <pre><code>cp arvados-root-cert.pem /etc/pki/ca-trust/source/anchors/
  91 /usr/bin/update-ca-trust
  92 </code></pre>
  93 </notextile>
  94
  95 h2(#initial_user). Initial user and login
  96
  97 At this point you should be able to log into the Arvados cluster.
  98
  99 If you didn't change the defaults, the initial URL will be:
 100
 101 * https://workbench.arva2.arv.local:8443
 102
 103 or, in general, the url format will be:
 104
 105 * https://workbench.@<cluster>.<domain>:8443@
 106
 107 By default, the provision script creates an initial user for testing purposes. This user is configured as administrator of the newly created cluster.
 108
 109 Assuming you didn't change the defaults, the initial credentials are:
 110
 111 * User: 'admin'
 112 * Password: 'password'
 113 * Email: 'admin@arva2.arv.local'
 114
 115 h2(#test_install). Test the installed cluster running a simple workflow
 116
 117 As documented in the <a href="{{ site.baseurl }}/install/salt-single-host.html">Single Host installation</a> page, You can run a test workflow to verify the installation finished correctly. To do so, you can follow these steps:
 118
 119 <notextile>
 120 <pre><code>vagrant ssh</code></pre>
 121 </notextile>
 122
 123 and once in the instance:
 124
 125 <notextile>
 126 <pre><code>cd /tmp/cluster_tests
 127 ./run-test.sh
 128 </code></pre>
 129 </notextile>