---
layout: default
navsection: installguide
title: Install the controller
...
{% comment %}
Copyright (C) The Arvados Authors. All rights reserved.

SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}

The arvados-controller service must be installed on your API server node.

On Debian-based systems:

<notextile>
<pre><code>~$ <span class="userinput">sudo apt-get install arvados-controller</span>
</code></pre>
</notextile>

On Red Hat-based systems:

<notextile>
<pre><code>~$ <span class="userinput">sudo yum install arvados-controller</span>
</code></pre>
</notextile>

Verify the @arvados-controller@ program is functional:

<notextile>
<pre><code>~$ <span class="userinput">arvados-controller -h</span>
Usage:
  -config file
[...]
</code></pre>
</notextile>

h3. Configure Nginx to route requests to the controller

Add @upstream@ and @server@ definitions inside the @http@ section of your Nginx configuration using the following template.

{% include 'notebox_begin' %}

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@.

{% include 'notebox_end' %}

<notextile>
<pre><code>upstream controller {
  server     127.0.0.1:9004  fail_timeout=10s;
}

server {
  listen       <span class="userinput">[your public IP address]</span>:443 ssl;
  server_name  <span class="userinput">uuid_prefix.your.domain</span>;

  ssl on;
  ssl_certificate     <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
  ssl_certificate_key <span class="userinput">/YOUR/PATH/TO/cert.key</span>;

  # Refer to the comment about this setting in the passenger (arvados
  # api server) section of your Nginx configuration.
  client_max_body_size 128m;

  location / {
    proxy_pass            http://controller;
    proxy_redirect        off;
    proxy_connect_timeout 90s;
    proxy_read_timeout    300s;

    proxy_set_header      X-Forwarded-Proto https;
    proxy_set_header      Host $http_host;
    proxy_set_header      X-External-Client $external_client;
    proxy_set_header      X-Real-IP $remote_addr;
    proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}
</code></pre>
</notextile>

Restart Nginx to apply the new configuration.

<notextile>
<pre><code>~$ <span class="userinput">sudo nginx -s reload</span>
</code></pre>
</notextile>

h3(#configuration). Configure arvados-controller

Create the cluster configuration file @/etc/arvados/config.yml@ using the following template.

<notextile>
<pre><code>Clusters:
  <span class="userinput">uuid_prefix</span>:
    Services:
      Controller:
        InternalURLs:
          "http://localhost:<span class="userinput">9004</span>": {} # must match the "upstream controller" section of your Nginx config
      RailsAPI:
        arvados-api-server:
          "http://localhost:<span class="userinput">8000</span>": {} # must match the "upstream api" section of your Nginx config
    PostgreSQL:
      ConnectionPool: 128
      Connection:
        host: localhost
        dbname: arvados_production
        user: arvados
        password: <span class="userinput">xxxxxxxx</span>
        sslmode: require
</code></pre>
</notextile>

Create the host configuration file @/etc/arvados/environment@.

<notextile>
<pre><code>ARVADOS_NODE_PROFILE=apiserver
</code></pre>
</notextile>

h3. Start the service (option 1: systemd)

If your system does not use systemd, skip this section and follow the "runit instructions":#runit instead.

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:

<notextile>
<pre><code>~$ <span class="userinput">sudo systemctl restart arvados-controller</span>
~$ <span class="userinput">sudo systemctl status arvados-controller</span>
&#x25cf; arvados-controller.service - Arvados controller
   Loaded: loaded (/lib/systemd/system/arvados-controller.service; enabled; vendor preset: enabled)
   Active: active (running) since Tue 2018-07-31 13:17:44 UTC; 3s ago
     Docs: https://doc.arvados.org/
 Main PID: 25066 (arvados-control)
   CGroup: /system.slice/arvados-controller.service
           └─25066 /usr/bin/arvados-controller

Jul 31 13:17:44 zzzzz systemd[1]: Starting Arvados controller...
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"}
Jul 31 13:17:44 zzzzz systemd[1]: Started Arvados controller.
</code></pre>
</notextile>

Skip ahead to "confirm the service is working":#confirm.

h3(#runit). Start the service (option 2: runit)

Install runit to supervise the arvados-controller daemon.  {% include 'install_runit' %}

Create a supervised service.

<notextile>
<pre><code>~$ <span class="userinput">sudo mkdir /etc/service/arvados-controller</span>
~$ <span class="userinput">cd /etc/service/arvados-controller</span>
~$ <span class="userinput">sudo mkdir log log/main</span>
~$ <span class="userinput">printf '#!/bin/sh\nset -a\n. /etc/arvados/environment\nexec arvados-controller 2>&1\n' | sudo tee run</span>
~$ <span class="userinput">printf '#!/bin/sh\nexec svlogd main\n' | sudo tee log/run</span>
~$ <span class="userinput">sudo chmod +x run log/run</span>
~$ <span class="userinput">sudo sv exit .</span>
~$ <span class="userinput">cd -</span>
</code></pre>
</notextile>

Use @sv stat@ and check the log file to verify the service is running.

<notextile>
<pre><code>~$ <span class="userinput">sudo sv stat /etc/service/arvados-controller</span>
run: /etc/service/arvados-controller: (pid 12520) 2s; run: log: (pid 12519) 2s
~$ <span class="userinput">tail /etc/service/arvados-controller/log/main/current</span>
{"Listen":"[::]:9004","Service":"arvados-controller","level":"info","msg":"listening","time":"2018-07-31T13:17:44.521694195Z"}
</code></pre>
</notextile>

h3(#confirm). Confirm the service is working

Confirm the service is listening on its assigned port and responding to requests.

<notextile>
<pre><code>~$ <span class="userinput">curl -X OPTIONS http://0.0.0.0:<b>9004</b>/login</span>
{"errors":["Forbidden"],"error_token":"1533044555+684b532c"}
</code></pre>
</notextile>

h3(#confirm-config). Confirm the public configuration is OK

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.

<notextile>
<pre><code>~$ <span class="userinput">curl http://0.0.0.0:<b>9004</b>/arvados/v1/config | jq .</span>
{
  "API": {
    "MaxItemsPerResponse": 1000,
    "MaxRequestAmplification": 4,
    "RequestTimeout": "5m"
  },
  ...
</code></pre>
</notextile>