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     Services:
  96       Controller:
  97         InternalURLs:
  98           "http://localhost:<span class="userinput">9004</span>": {} # must match the "upstream controller" section of your Nginx config
  99       RailsAPI:
 100         arvados-api-server:
 101           "http://localhost:<span class="userinput">8000</span>": {} # must match the "upstream api" section of your Nginx config
 102     PostgreSQL:
 103       ConnectionPool: 128
 104       Connection:
 105         host: localhost
 106         dbname: arvados_production
 107         user: arvados
 108         password: <span class="userinput">xxxxxxxx</span>
 109         sslmode: require
 110 </code></pre>
 111 </notextile>
 112
 113 Create the host configuration file @/etc/arvados/environment@.
 114
 115 <notextile>
 116 <pre><code>ARVADOS_NODE_PROFILE=apiserver
 117 </code></pre>
 118 </notextile>
 119
 120 h3. Start the service (option 1: systemd)
 121
 122 If your system does not use systemd, skip this section and follow the "runit instructions":#runit instead.
 123
 124 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:
 125
 126 <notextile>
 127 <pre><code>~$ <span class="userinput">sudo systemctl restart arvados-controller</span>
 128 ~$ <span class="userinput">sudo systemctl status arvados-controller</span>
 129 &#x25cf; arvados-controller.service - Arvados controller
 130    Loaded: loaded (/lib/systemd/system/arvados-controller.service; enabled; vendor preset: enabled)
 131    Active: active (running) since Tue 2018-07-31 13:17:44 UTC; 3s ago
 132      Docs: https://doc.arvados.org/
 133  Main PID: 25066 (arvados-control)
 134    CGroup: /system.slice/arvados-controller.service
 135            └─25066 /usr/bin/arvados-controller
 136
 137 Jul 31 13:17:44 zzzzz systemd[1]: Starting Arvados controller...
 138 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"}
 139 Jul 31 13:17:44 zzzzz systemd[1]: Started Arvados controller.
 140 </code></pre>
 141 </notextile>
 142
 143 Skip ahead to "confirm the service is working":#confirm.
 144
 145 h3(#runit). Start the service (option 2: runit)
 146
 147 Install runit to supervise the arvados-controller daemon.  {% include 'install_runit' %}
 148
 149 Create a supervised service.
 150
 151 <notextile>
 152 <pre><code>~$ <span class="userinput">sudo mkdir /etc/service/arvados-controller</span>
 153 ~$ <span class="userinput">cd /etc/service/arvados-controller</span>
 154 ~$ <span class="userinput">sudo mkdir log log/main</span>
 155 ~$ <span class="userinput">printf '#!/bin/sh\nset -a\n. /etc/arvados/environment\nexec arvados-controller 2>&1\n' | sudo tee run</span>
 156 ~$ <span class="userinput">printf '#!/bin/sh\nexec svlogd main\n' | sudo tee log/run</span>
 157 ~$ <span class="userinput">sudo chmod +x run log/run</span>
 158 ~$ <span class="userinput">sudo sv exit .</span>
 159 ~$ <span class="userinput">cd -</span>
 160 </code></pre>
 161 </notextile>
 162
 163 Use @sv stat@ and check the log file to verify the service is running.
 164
 165 <notextile>
 166 <pre><code>~$ <span class="userinput">sudo sv stat /etc/service/arvados-controller</span>
 167 run: /etc/service/arvados-controller: (pid 12520) 2s; run: log: (pid 12519) 2s
 168 ~$ <span class="userinput">tail /etc/service/arvados-controller/log/main/current</span>
 169 {"Listen":"[::]:9004","Service":"arvados-controller","level":"info","msg":"listening","time":"2018-07-31T13:17:44.521694195Z"}
 170 </code></pre>
 171 </notextile>
 172
 173 h3(#confirm). Confirm the service is working
 174
 175 Confirm the service is listening on its assigned port and responding to requests.
 176
 177 <notextile>
 178 <pre><code>~$ <span class="userinput">curl -X OPTIONS http://0.0.0.0:<b>9004</b>/login</span>
 179 {"errors":["Forbidden"],"error_token":"1533044555+684b532c"}
 180 </code></pre>
 181 </notextile>
 182
 183 h3(#confirm-config). Confirm the public configuration is OK
 184
 185 Confirm the publicly accessible configuration endpoint does not reveal any sensitive information (e.g., a secret that was mistakenly entered under the wrong configuration key). Use the jq program, if you have installed it, to make the JSON document easier to read.
 186
 187 <notextile>
 188 <pre><code>~$ <span class="userinput">curl http://0.0.0.0:<b>9004</b>/arvados/v1/config | jq .</span>
 189 {
 190   "API": {
 191     "MaxItemsPerResponse": 1000,
 192     "MaxRequestAmplification": 4,
 193     "RequestTimeout": "5m"
 194   },
 195   ...
 196 </code></pre>
 197 </notextile>