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 By convention, we use the following hostname for the websocket service.
  15
  16 <notextile>
  17 <pre><code>ws.<span class="userinput">uuid_prefix.your.domain</span></code></pre>
  18 </notextile>
  19
  20 The above hostname should resolve from anywhere on the internet.
  21
  22 h2. Install arvados-ws
  23
  24 Typically arvados-ws runs on the same host as the API server.
  25
  26 On Debian-based systems:
  27
  28 <notextile>
  29 <pre><code>~$ <span class="userinput">sudo apt-get install arvados-ws</span>
  30 </code></pre>
  31 </notextile>
  32
  33 On Red Hat-based systems:
  34
  35 <notextile>
  36 <pre><code>~$ <span class="userinput">sudo yum install arvados-ws</span>
  37 </code></pre>
  38 </notextile>
  39
  40 Verify that @arvados-ws@ is functional:
  41
  42 <notextile>
  43 <pre><code>~$ <span class="userinput">arvados-ws -h</span>
  44 Usage of arvados-ws:
  45   -config path
  46         path to config file (default "/etc/arvados/ws/ws.yml")
  47   -dump-config
  48         show current configuration and exit
  49 </code></pre>
  50 </notextile>
  51
  52 h3. Create a configuration file
  53
  54 Create @/etc/arvados/ws/ws.yml@ using the following template. Replace @xxxxxxxx@ with the "password you generated during database setup":install-postgresql.html#api.
  55
  56 <notextile>
  57 <pre><code>Client:
  58   APIHost: <span class="userinput">uuid_prefix.your.domain</span>:443
  59 Listen: ":<span class="userinput">9003</span>"
  60 Postgres:
  61   dbname: arvados_production
  62   host: localhost
  63   password: <span class="userinput">xxxxxxxx</span>
  64   user: arvados
  65 </code></pre>
  66 </notextile>
  67
  68 h3. Start the service (option 1: systemd)
  69
  70 If your system does not use systemd, skip this section and follow the "runit instructions":#runit instead.
  71
  72 If your system uses systemd, the arvados-ws service should already be set up. Start it and check its status:
  73
  74 <notextile>
  75 <pre><code>~$ <span class="userinput">sudo systemctl restart arvados-ws</span>
  76 ~$ <span class="userinput">sudo systemctl status arvados-ws</span>
  77 &#x25cf; arvados-ws.service - Arvados websocket server
  78    Loaded: loaded (/lib/systemd/system/arvados-ws.service; enabled)
  79    Active: active (running) since Tue 2016-12-06 11:20:48 EST; 10s ago
  80      Docs: https://doc.arvados.org/
  81  Main PID: 9421 (arvados-ws)
  82    CGroup: /system.slice/arvados-ws.service
  83            └─9421 /usr/bin/arvados-ws
  84
  85 Dec 06 11:20:48 zzzzz arvados-ws[9421]: {"level":"info","msg":"started","time":"2016-12-06T11:20:48.207617188-05:00"}
  86 Dec 06 11:20:48 zzzzz arvados-ws[9421]: {"Listen":":9003","level":"info","msg":"listening","time":"2016-12-06T11:20:48.244956506-05:00"}
  87 Dec 06 11:20:48 zzzzz systemd[1]: Started Arvados websocket server.
  88 </code></pre>
  89 </notextile>
  90
  91 If it is not running, use @journalctl@ to check logs for errors:
  92
  93 <notextile>
  94 <pre><code>~$ <span class="userinput">sudo journalctl -n10 -u arvados-ws</span>
  95 ...
  96 Dec 06 11:12:48 zzzzz systemd[1]: Starting Arvados websocket server...
  97 Dec 06 11:12:48 zzzzz arvados-ws[8918]: {"level":"info","msg":"started","time":"2016-12-06T11:12:48.030496636-05:00"}
  98 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"}
  99 </code></pre>
 100 </notextile>
 101
 102 Skip ahead to "confirm the service is working":#confirm.
 103
 104 h3(#runit). Start the service (option 2: runit)
 105
 106 Install runit to supervise the arvados-ws daemon.  {% include 'install_runit' %}
 107
 108 Create a supervised service.
 109
 110 <notextile>
 111 <pre><code>~$ <span class="userinput">sudo mkdir /etc/service/arvados-ws</span>
 112 ~$ <span class="userinput">cd /etc/service/arvados-ws</span>
 113 ~$ <span class="userinput">sudo mkdir log log/main</span>
 114 ~$ <span class="userinput">printf '#!/bin/sh\nexec arvados-ws 2>&1\n' | sudo tee run</span>
 115 ~$ <span class="userinput">printf '#!/bin/sh\nexec svlogd main\n' | sudo tee log/run</span>
 116 ~$ <span class="userinput">sudo chmod +x run log/run</span>
 117 ~$ <span class="userinput">sudo sv exit .</span>
 118 ~$ <span class="userinput">cd -</span>
 119 </code></pre>
 120 </notextile>
 121
 122 Use @sv stat@ and check the log file to verify the service is running.
 123
 124 <notextile>
 125 <pre><code>~$ <span class="userinput">sudo sv stat /etc/service/arvados-ws</span>
 126 run: /etc/service/arvados-ws: (pid 12520) 2s; run: log: (pid 12519) 2s
 127 ~$ <span class="userinput">tail /etc/service/arvados-ws/log/main/current</span>
 128 {"level":"info","msg":"started","time":"2016-12-06T11:56:20.669171449-05:00"}
 129 {"Listen":":9003","level":"info","msg":"listening","time":"2016-12-06T11:56:20.708847627-05:00"}
 130 </code></pre>
 131 </notextile>
 132
 133 h3(#confirm). Confirm the service is working
 134
 135 Confirm the service is listening on its assigned port and responding to requests.
 136
 137 <notextile>
 138 <pre><code>~$ <span class="userinput">curl http://0.0.0.0:<b>9003</b>/status.json</span>
 139 {"Clients":1}
 140 </code></pre>
 141 </notextile>
 142
 143 h3. Set up a reverse proxy with SSL support
 144
 145 The arvados-ws service will be accessible from anywhere on the internet, so we recommend using SSL for transport encryption.
 146
 147 This is best achieved by putting a reverse proxy with SSL support in front of arvados-ws, running on port 443 and passing requests to arvados-ws on port 9003 (or whatever port you chose in your configuration file).
 148
 149 For example, using Nginx:
 150
 151 <notextile><pre>
 152 upstream arvados-ws {
 153   server                127.0.0.1:<span class="userinput">9003</span>;
 154 }
 155
 156 server {
 157   listen                <span class="userinput">[your public IP address]</span>:443 ssl;
 158   server_name           ws.<span class="userinput">uuid_prefix.your.domain</span>;
 159
 160   proxy_connect_timeout 90s;
 161   proxy_read_timeout    300s;
 162
 163   ssl                   on;
 164   ssl_certificate       <span class="userinput"/>YOUR/PATH/TO/cert.pem</span>;
 165   ssl_certificate_key   <span class="userinput"/>YOUR/PATH/TO/cert.key</span>;
 166
 167   location / {
 168     proxy_pass          http://arvados-ws;
 169     proxy_set_header    Upgrade         $http_upgrade;
 170     proxy_set_header    Connection      "upgrade";
 171     proxy_set_header    Host            $host;
 172     proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
 173   }
 174 }
 175 </pre></notextile>
 176
 177 {% include 'notebox_begin' %}
 178 If you are upgrading a cluster where Nginx is configured to proxy @ws@ requests to puma, change the @server_name@ value in the old configuration block so it doesn't conflict. When the new configuration is working, delete the old Nginx configuration sections (i.e., the "upstream websockets" block, and the "server" block that references @http://websockets@), and disable/remove the runit or systemd files for the puma server.
 179 {% include 'notebox_end' %}
 180
 181 h3. Update API server configuration
 182
 183 Ensure the websocket server address is correct in the API server configuration file @/etc/arvados/api/application.yml@.
 184
 185 <notextile>
 186 <pre><code>websocket_address: wss://ws.<span class="userinput">uuid_prefix.your.domain</span>/websocket
 187 </code></pre>
 188 </notextile>
 189
 190 Restart Nginx to reload the API server configuration.
 191
 192 <notextile>
 193 <pre><code>$ sudo nginx -s reload</span>
 194 </code></pre>
 195 </notextile>
 196
 197 h3. Verify DNS and proxy setup
 198
 199 Use a host elsewhere on the Internet to confirm that your DNS, proxy, and SSL are configured correctly.
 200
 201 <notextile>
 202 <pre><code>$ <span class="userinput">curl https://ws.<b>uuid_prefix.your.domain</b>/status.json</span>
 203 {"Clients":1}
 204 </code></pre>
 205 </notextile>