doc/install/install-manual-prerequisites.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Planning and prerequisites
   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 Before attempting installation, you should begin by reviewing supported platforms, choosing backends for identity, storage, and scheduling, and decide how you will distribute Arvados services onto machines.  You should also choose an Arvados Cluster ID, choose your hostnames, and aquire TLS certificates.  It may be helpful to make notes as you go along using one of these worksheets:  "New cluster checklist for AWS":new_cluster_checklist_AWS.xlsx - "New cluster checklist for Azure":new_cluster_checklist_Azure.xlsx - "New cluster checklist for on premise SLURM":new_cluster_checklist_slurm.xlsx
  13
  14 The Arvados storage subsystem is called "keep".  The compute subsystem is called "crunch".
  15
  16 # "Supported GNU/Linux distributions":#supportedlinux
  17 # "Choosing which components to install":#components
  18 # "Identity provider":#identity
  19 # "Storage backend (Keep)":#storage
  20 # "Container compute scheduler (Crunch)":#scheduler
  21 # "Hardware or virtual machines":#machines
  22 # "Arvados Cluster ID":#clusterid
  23 # "DNS and TLS":#dnstls
  24
  25 h2(#supportedlinux). Supported GNU/Linux distributions
  26
  27 table(table table-bordered table-condensed).
  28 |_. Distribution|_. State|_. Last supported version|
  29 |CentOS 7|Supported|Latest|
  30 |Debian 10 ("buster")|Supported|Latest|
  31 |Debian 9 ("stretch")|Supported|Latest|
  32 |Ubuntu 18.04 ("bionic")|Supported|Latest|
  33 |Ubuntu 16.04 ("xenial")|Supported|Latest|
  34 |Ubuntu 14.04 ("trusty")|EOL|1.4.3|
  35 |Debian 8 ("jessie")|EOL|1.4.3|
  36 |Ubuntu 12.04 ("precise")|EOL|8ed7b6dd5d4df93a3f37096afe6d6f81c2a7ef6e (2017-05-03)|
  37 |Debian 7 ("wheezy")|EOL|997479d1408139e96ecdb42a60b4f727f814f6c9 (2016-12-28)|
  38 |CentOS 6 |EOL|997479d1408139e96ecdb42a60b4f727f814f6c9 (2016-12-28)|
  39
  40 Arvados packages are published for current Debian releases (until the EOL date), current Ubuntu LTS releases (until the end of standard support), and the latest version of CentOS.
  41
  42 h2(#components). Choosing which components to install
  43
  44 Arvados consists of many components, some of which may be omitted (at the cost of reduced functionality.)  It may also be helpful to review the "Arvados Architecture":{{site.baseurl}}/architecture to understand how these components interact.
  45
  46 table(table table-bordered table-condensed).
  47 |\3=. *Core*|
  48 |"Postgres database":install-postgresql.html |Stores data for the API server.|Required.|
  49 |"API server":install-api-server.html |Core Arvados logic for managing users, groups, collections, containers, and enforcing permissions.|Required.|
  50 |\3=. *Keep (storage)*|
  51 |"Keepstore":install-keepstore.html |Stores content-addressed blocks in a variety of backends (local filesystem, cloud object storage).|Required.|
  52 |"Keepproxy":install-keepproxy.html |Gateway service to access keep servers from external networks.|Required to be able to use arv-put, arv-get, or arv-mount outside the private Arvados network.|
  53 |"Keep-web":install-keep-web.html |Gateway service providing read/write HTTP and WebDAV support on top of Keep.|Required to access files from Workbench.|
  54 |"Keep-balance":install-keep-balance.html |Storage cluster maintenance daemon responsible for moving blocks to their optimal server location, adjusting block replication levels, and trashing unreferenced blocks.|Required to free deleted data from underlying storage, and to ensure proper replication and block distribution (including support for storage classes).|
  55 |\3=. *User interface*|
  56 |"Workbench":install-workbench-app.html, "Workbench2":install-workbench2-app.html |Primary graphical user interface for working with file collections and running containers.|Optional.  Depends on API server, keep-web, websockets server.|
  57 |"Workflow Composer":install-composer.html |Graphical user interface for editing Common Workflow Language workflows.|Optional.  Depends on git server (arv-git-httpd).|
  58 |\3=. *Additional services*|
  59 |"Websockets server":install-ws.html |Event distribution server.|Required to view streaming container logs in Workbench.|
  60 |"Shell server":install-shell-server.html |Synchronize (create/delete/configure) Unix shell accounts with Arvados users.|Optional.|
  61 |"Git server":install-arv-git-httpd.html |Arvados-hosted git repositories, with Arvados-token based authentication.|Optional, but required by Workflow Composer.|
  62 |\3=. *Crunch (running containers)*|
  63 |"crunch-dispatch-slurm":crunch2-slurm/install-prerequisites.html |Run analysis workflows using Docker containers distributed across a SLURM cluster.|Optional if you wish to use Arvados for data management only.|
  64 |"Node Manager":install-nodemanager.html, "arvados-dispatch-cloud":install-dispatch-cloud.html |Allocate and free cloud VM instances on demand based on workload.|Optional, not needed for a static SLURM cluster (such as on-premise HPC).|
  65
  66 h2(#identity). Identity provider
  67
  68 Choose which backend you will use to authenticate users.
  69
  70 * Google login to authenticate users with a Google account.
  71 * LDAP login to authenticate users by username/password using the LDAP protocol, supported by many services such as OpenLDAP and Active Directory.
  72 * PAM login to authenticate users by username/password according to the PAM configuration on the controller node.
  73
  74 h2(#storage). Storage backend
  75
  76 Choose which backend you will use for storing and retrieving content-addressed Keep blocks.
  77
  78 * File systems storage, such as ext4 or xfs, or network file systems such as GPFS or Lustre
  79 * Amazon S3, or other object storage that supports the S3 API including Google Cloud Storage and Ceph.
  80 * Azure blob storage
  81
  82 You should also determine the desired replication factor for your data.  A replication factor of 1 means only a single copy of a given data block is kept.  With a conventional file system backend and a replication factor of 1, a hard drive failure is likely to lose data.  For this reason the default replication factor is 2 (two copies are kept).
  83
  84 A backend may have its own replication factor (such as durability guarantees of cloud buckets) and Arvados will take this into account when writing a new data block.
  85
  86 h2(#scheduler). Container compute scheduler
  87
  88 Choose which backend you will use to schedule computation.
  89
  90 * On AWS EC2 and Azure, you probably want to use @arvados-dispatch-cloud@ to manage the full lifecycle of cloud compute nodes: starting up nodes sized to the container request, executing containers on those nodes, and shutting nodes down when no longer needed.
  91 * For on-premise HPC clusters using "slurm":https://slurm.schedmd.com/ use @crunch-dispatch-slurm@ to execute containers with slurm job submissions.
  92 * For single node demos, use @crunch-dispatch-local@ to execute containers directly.
  93
  94 h2(#machines). Hardware (or virtual machines)
  95
  96 Choose how to allocate Arvados services to machines.  We recommend that each machine start with a clean installation of a supported GNU/Linux distribution.
  97
  98 For a production installation, this is a reasonable starting point:
  99
 100 <div class="offset1">
 101 table(table table-bordered table-condensed).
 102 |_. Function|_. Number of nodes|_. Recommended specs|
 103 |Postgres database, Arvados API server, Arvados controller, Git, Websockets, Container dispatcher|1|16+ GiB RAM, 4+ cores, fast disk for database|
 104 |Workbench, Keepproxy, Keep-web, Keep-balance|1|8 GiB RAM, 2+ cores|
 105 |Keepstore servers ^1^|2+|4 GiB RAM|
 106 |Compute worker nodes ^1^|0+ |Depends on workload; scaled dynamically in the cloud|
 107 |User shell nodes ^2^|0+|Depends on workload|
 108 </div>
 109
 110 ^1^ Should be scaled up as needed
 111 ^2^ Refers to shell nodes managed by Arvados, that provide ssh access for users to interact with Arvados at the command line.  Optional.
 112
 113 {% include 'notebox_begin' %}
 114 For a small demo installation, it is possible to run all the Arvados services on a single node.  Special considerations for single-node installs will be noted in boxes like this.
 115 {% include 'notebox_end' %}
 116
 117 h2(#clusterid). Arvados Cluster ID
 118
 119 Each Arvados installation should have a cluster identifier, which is a unique 5-character lowercase alphanumeric string.   Here is one way to make a random 5-character string:
 120
 121 <notextile>
 122 <pre><code>~$ <span class="userinput">tr -dc 0-9a-z &lt;/dev/urandom | head -c5; echo</span>
 123 </code></pre>
 124 </notextile>
 125
 126 You may also use a different method to pick the cluster identifier. The cluster identifier will be part of the hostname of the services in your Arvados cluster. The rest of this documentation will refer to it as your @ClusterID@.  Whenever @ClusterID@ appears in a configuration example, replace it with your five-character cluster identifier.
 127
 128 h2(#dnstls). DNS entries and TLS certificates
 129
 130 The following services are normally public-facing and require DNS entries and corresponding TLS certificates.  Get certificates from your preferred TLS certificate provider.  We recommend using "Let's Encrypt":https://letsencrypt.org/.  You can run several services on same node, but each distinct hostname requires its own TLS certificate.
 131
 132 This guide uses the following hostname conventions.  A later part of this guide will describe how to set up Nginx virtual hosts.
 133
 134 <div class="offset1">
 135 table(table table-bordered table-condensed).
 136 |_. Function|_. Hostname|
 137 |Arvados API|@ClusterID.example.com@|
 138 |Arvados Git server|git.@ClusterID.example.com@|
 139 |Arvados Websockets endpoint|ws.@ClusterID.example.com@|
 140 |Arvados Workbench|workbench.@ClusterID.example.com@|
 141 |Arvados Workbench 2|workbench2.@ClusterID.example.com@|
 142 |Arvados Keepproxy server|keep.@ClusterID.example.com@|
 143 |Arvados Keep-web server|download.@ClusterID.example.com@
 144 _and_
 145 *.collections.@ClusterID.example.com@ or
 146 *<notextile>--</notextile>collections.@ClusterID.example.com@ or
 147 collections.@ClusterID.example.com@ (see the "keep-web install docs":install-keep-web.html)|
 148 </div>
 149
 150 {% include 'notebox_begin' %}
 151 It is also possible to create your own certificate authority, issue server certificates, and install a custom root certificate in the browser.  This is out of scope for this guide.
 152 {% include 'notebox_end' %}