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

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Install the controller
   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 The arvados-controller service must be installed on your API server node.
  13
  14 On Debian-based systems:
  15
  16 <notextile>
  17 <pre><code>~$ <span class="userinput">sudo apt-get install arvados-controller</span>
  18 </code></pre>
  19 </notextile>
  20
  21 On Red Hat-based systems:
  22
  23 <notextile>
  24 <pre><code>~$ <span class="userinput">sudo yum install arvados-controller</span>
  25 </code></pre>
  26 </notextile>
  27
  28 Verify the @arvados-controller@ program is functional:
  29
  30 <notextile>
  31 <pre><code>~$ <span class="userinput">arvados-controller -h</span>
  32 Usage:
  33   -config file
  34 [...]
  35 </code></pre>
  36 </notextile>
  37
  38 h3. Configure Nginx to route requests to the controller
  39
  40 Add @upstream@ and @server@ definitions inside the @http@ section of your Nginx configuration using the following template.
  41
  42 {% include 'notebox_begin' %}
  43
  44 If you are adding arvados-controller to an existing system as part of the upgrade procedure, do not add a new "server" part here. Instead, add only the "upstream" part as shown here, and update your existing "server" section by changing its @proxy_pass@ directive from @http://api@ to @http://controller@.
  45
  46 {% include 'notebox_end' %}
  47
  48 <notextile>
  49 <pre><code>upstream controller {
  50   server     127.0.0.1:9004  fail_timeout=10s;
  51 }
  52
  53 server {
  54   listen       <span class="userinput">[your public IP address]</span>:443 ssl;
  55   server_name  <span class="userinput">uuid_prefix.your.domain</span>;
  56
  57   ssl on;
  58   ssl_certificate     <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
  59   ssl_certificate_key <span class="userinput">/YOUR/PATH/TO/cert.key</span>;
  60
  61   # Refer to the comment about this setting in the passenger (arvados
  62   # api server) section of your Nginx configuration.
  63   client_max_body_size 128m;
  64
  65   location / {
  66     proxy_pass            http://controller;
  67     proxy_redirect        off;
  68     proxy_connect_timeout 90s;
  69     proxy_read_timeout    300s;
  70
  71     proxy_set_header      X-Forwarded-Proto https;
  72     proxy_set_header      Host $http_host;
  73     proxy_set_header      X-External-Client $external_client;
  74     proxy_set_header      X-Real-IP $remote_addr;
  75     proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
  76   }
  77 }
  78 </code></pre>
  79 </notextile>
  80
  81 Restart Nginx to apply the new configuration.
  82
  83 <notextile>
  84 <pre><code>~$ <span class="userinput">sudo nginx -s reload</span>
  85 </code></pre>
  86 </notextile>
  87
  88 h3(#configuration). Configure arvados-controller
  89
  90 Create the cluster configuration file @/etc/arvados/config.yml@ using the following template.
  91
  92 <notextile>
  93 <pre><code>Clusters:
  94   <span class="userinput">uuid_prefix</span>:
  95     NodeProfiles:
  96       apiserver:
  97         arvados-controller:
  98           Listen: ":<span class="userinput">9004</span>" # must match the "upstream controller" section of your Nginx config
  99         arvados-api-server:
 100           Listen: ":<span class="userinput">8000</span>" # must match the "upstream api" section of your Nginx config
 101     PostgreSQL:
 102       ConnectionPool: 128
 103       Connection:
 104         host: localhost
 105         dbname: arvados_production
 106         user: arvados
 107         password: <span class="userinput">xxxxxxxx</span>
 108         sslmode: require
 109 </code></pre>
 110 </notextile>
 111
 112 Create the host configuration file @/etc/arvados/environment@.
 113
 114 <notextile>
 115 <pre><code>ARVADOS_NODE_PROFILE=apiserver
 116 </code></pre>
 117 </notextile>
 118
 119 h3. Start the service (option 1: systemd)
 120
 121 If your system does not use systemd, skip this section and follow the "runit instructions":#runit instead.
 122
 123 If your system uses systemd, the arvados-controller service should already be set up. Restart it to load the new configuration file, and check its status:
 124
 125 <notextile>
 126 <pre><code>~$ <span class="userinput">sudo systemctl restart arvados-controller</span>
 127 ~$ <span class="userinput">sudo systemctl status arvados-controller</span>
 128 &#x25cf; arvados-controller.service - Arvados controller
 129    Loaded: loaded (/lib/systemd/system/arvados-controller.service; enabled; vendor preset: enabled)
 130    Active: active (running) since Tue 2018-07-31 13:17:44 UTC; 3s ago
 131      Docs: https://doc.arvados.org/
 132  Main PID: 25066 (arvados-control)
 133    CGroup: /system.slice/arvados-controller.service
 134            └─25066 /usr/bin/arvados-controller
 135
 136 Jul 31 13:17:44 zzzzz systemd[1]: Starting Arvados controller...
 137 Jul 31 13:17:44 zzzzz arvados-controller[25191]: {"Listen":"[::]:9004","Service":"arvados-controller","level":"info","msg":"listening","time":"2018-07-31T13:17:44.521694195Z"}
 138 Jul 31 13:17:44 zzzzz systemd[1]: Started Arvados controller.
 139 </code></pre>
 140 </notextile>
 141
 142 Skip ahead to "confirm the service is working":#confirm.
 143
 144 h3(#runit). Start the service (option 2: runit)
 145
 146 Install runit to supervise the arvados-controller daemon.  {% include 'install_runit' %}
 147
 148 Create a supervised service.
 149
 150 <notextile>
 151 <pre><code>~$ <span class="userinput">sudo mkdir /etc/service/arvados-controller</span>
 152 ~$ <span class="userinput">cd /etc/service/arvados-controller</span>
 153 ~$ <span class="userinput">sudo mkdir log log/main</span>
 154 ~$ <span class="userinput">printf '#!/bin/sh\nset -a\n. /etc/arvados/environment\nexec arvados-controller 2>&1\n' | sudo tee run</span>
 155 ~$ <span class="userinput">printf '#!/bin/sh\nexec svlogd main\n' | sudo tee log/run</span>
 156 ~$ <span class="userinput">sudo chmod +x run log/run</span>
 157 ~$ <span class="userinput">sudo sv exit .</span>
 158 ~$ <span class="userinput">cd -</span>
 159 </code></pre>
 160 </notextile>
 161
 162 Use @sv stat@ and check the log file to verify the service is running.
 163
 164 <notextile>
 165 <pre><code>~$ <span class="userinput">sudo sv stat /etc/service/arvados-controller</span>
 166 run: /etc/service/arvados-controller: (pid 12520) 2s; run: log: (pid 12519) 2s
 167 ~$ <span class="userinput">tail /etc/service/arvados-controller/log/main/current</span>
 168 {"Listen":"[::]:9004","Service":"arvados-controller","level":"info","msg":"listening","time":"2018-07-31T13:17:44.521694195Z"}
 169 </code></pre>
 170 </notextile>
 171
 172 h3(#confirm). Confirm the service is working
 173
 174 Confirm the service is listening on its assigned port and responding to requests.
 175
 176 <notextile>
 177 <pre><code>~$ <span class="userinput">curl -X OPTIONS http://0.0.0.0:<b>9004</b>/login</span>
 178 {"errors":["Forbidden"],"error_token":"1533044555+684b532c"}
 179 </code></pre>
 180 </notextile>