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

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