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

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Install the websocket server
   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-ws server provides event notifications to websocket clients. It can be installed anywhere with access to Postgres database and the Arvados API server, typically behind a web proxy that provides SSL support. See the "godoc page":http://godoc.org/github.com/curoverse/arvados/services/ws for additional information.
  13
  14 # "Update config.yml":#update-config
  15 # "Update nginx configuration":#update-nginx
  16 # "Install arvados-ws package":#install-packages
  17 # "Start the service":#start-service
  18 # "Restart the API server and controller":#restart-api
  19 # "Confirm working installation":#confirm-working
  20
  21 h2(#configure). Update config.yml
  22
  23 Edit the cluster config at @/etc/arvados/config.yml@ and set @Services.Websocket.ExternalURL@ and @Services.Websocket.InternalURLs@.  Replace @zzzzz@ with your cluster id.
  24
  25 <notextile>
  26 <pre><code>    Services:
  27       Websocket:
  28         InternalURLs:
  29           <span class="userinput">"http://ws.ClusterID.example.com:8005"</span>: {}
  30         ExternalURL: <span class="userinput">wss://ws.ClusterID.example.com/websocket</span>
  31 </span></code></pre>
  32 </notextile>
  33
  34 h2(#update-nginx). Update Nginx configuration
  35
  36 The arvados-ws service will be accessible from anywhere on the internet, so we recommend using SSL for transport encryption.
  37
  38 Use a text editor to create a new file @/etc/nginx/conf.d/arvados-ws.conf@ with the following configuration.  Options that need attention are marked with "TODO".
  39
  40 <notextile><pre>
  41 upstream arvados-ws {
  42   server                127.0.0.1:<span class="userinput">8005</span>;
  43 }
  44
  45 server {
  46   listen                <span class="userinput">[your public IP address]</span>:443 ssl;
  47   server_name           ws.<span class="userinput">uuid_prefix.your.domain</span>;
  48
  49   proxy_connect_timeout 90s;
  50   proxy_read_timeout    300s;
  51
  52   ssl                   on;
  53   ssl_certificate       <span class="userinput"/>YOUR/PATH/TO/cert.pem</span>;
  54   ssl_certificate_key   <span class="userinput"/>YOUR/PATH/TO/cert.key</span>;
  55
  56   location / {
  57     proxy_pass          http://arvados-ws;
  58     proxy_set_header    Upgrade         $http_upgrade;
  59     proxy_set_header    Connection      "upgrade";
  60     proxy_set_header    Host            $host;
  61     proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
  62   }
  63 }
  64 </pre></notextile>
  65
  66 h2(#install-packages). Install arvados-ws
  67
  68 h3. Centos 7
  69
  70 <notextile>
  71 <pre><code># <span class="userinput">yum install arvados-ws</span>
  72 </code></pre>
  73 </notextile>
  74
  75 h3. Debian and Ubuntu
  76
  77 <notextile>
  78 <pre><code># <span class="userinput">apt-get --no-install-recommends install arvados-ws</span>
  79 </code></pre>
  80 </notextile>
  81
  82 h3. Start the service
  83
  84 If your system does not use systemd, skip this section and follow the "runit instructions":#runit instead.
  85
  86 If your system uses systemd, the arvados-ws service should already be set up. Start it and check its status:
  87
  88 <notextile>
  89 <pre><code>~$ <span class="userinput">sudo systemctl restart arvados-ws</span>
  90 ~$ <span class="userinput">sudo systemctl status arvados-ws</span>
  91 &#x25cf; arvados-ws.service - Arvados websocket server
  92    Loaded: loaded (/lib/systemd/system/arvados-ws.service; enabled)
  93    Active: active (running) since Tue 2016-12-06 11:20:48 EST; 10s ago
  94      Docs: https://doc.arvados.org/
  95  Main PID: 9421 (arvados-ws)
  96    CGroup: /system.slice/arvados-ws.service
  97            └─9421 /usr/bin/arvados-ws
  98
  99 Dec 06 11:20:48 zzzzz arvados-ws[9421]: {"level":"info","msg":"started","time":"2016-12-06T11:20:48.207617188-05:00"}
 100 Dec 06 11:20:48 zzzzz arvados-ws[9421]: {"Listen":":9003","level":"info","msg":"listening","time":"2016-12-06T11:20:48.244956506-05:00"}
 101 Dec 06 11:20:48 zzzzz systemd[1]: Started Arvados websocket server.
 102 </code></pre>
 103 </notextile>
 104
 105 If it is not running, use @journalctl@ to check logs for errors:
 106
 107 <notextile>
 108 <pre><code>~$ <span class="userinput">sudo journalctl -n10 -u arvados-ws</span>
 109 ...
 110 Dec 06 11:12:48 zzzzz systemd[1]: Starting Arvados websocket server...
 111 Dec 06 11:12:48 zzzzz arvados-ws[8918]: {"level":"info","msg":"started","time":"2016-12-06T11:12:48.030496636-05:00"}
 112 Dec 06 11:12:48 zzzzz arvados-ws[8918]: {"error":"pq: password authentication failed for user \"arvados\"","level":"fatal","msg":"db.Ping failed","time":"2016-12-06T11:12:48.058206400-05:00"}
 113 </code></pre>
 114 </notextile>
 115
 116 h2(#restart-api). Restart the API server and controller
 117
 118 After adding the SSO server to the Services section, make sure the cluster config file is up to date on the API server host, and restart the API server and controller processes to ensure the changes are applied.
 119
 120 <notextile>
 121 <pre><code># <span class="userinput">systemctl restart nginx arvados-controller</span>
 122 </code></pre>
 123 </notextile>
 124
 125 h3(#confirm). Confirm working installation
 126
 127 Confirm the service is listening on its assigned port and responding to requests.
 128
 129 <notextile>
 130 <pre><code>~$ <span class="userinput">curl http://0.0.0.0:<b>8005</b>/status.json</span>
 131 {"Clients":1}
 132 </code></pre>
 133 </notextile>