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>Client:
  59   APIHost: <span class="userinput">uuid_prefix.your.domain</span>:443
  60 Listen: ":<span class="userinput">9003</span>"
  61 Postgres:
  62   dbname: arvados_production
  63   host: localhost
  64   password: <span class="userinput">xxxxxxxx</span>
  65   user: arvados
  66 </code></pre>
  67 </notextile>
  68
  69 h3. Start the service (option 1: systemd)
  70
  71 If your system does not use systemd, skip this section and follow the "runit instructions":#runit instead.
  72
  73 If your system uses systemd, the arvados-ws service should already be set up. Start it and check its status:
  74
  75 <notextile>
  76 <pre><code>~$ <span class="userinput">sudo systemctl restart arvados-ws</span>
  77 ~$ <span class="userinput">sudo systemctl status arvados-ws</span>
  78 &#x25cf; arvados-ws.service - Arvados websocket server
  79    Loaded: loaded (/lib/systemd/system/arvados-ws.service; enabled)
  80    Active: active (running) since Tue 2016-12-06 11:20:48 EST; 10s ago
  81      Docs: https://doc.arvados.org/
  82  Main PID: 9421 (arvados-ws)
  83    CGroup: /system.slice/arvados-ws.service
  84            └─9421 /usr/bin/arvados-ws
  85
  86 Dec 06 11:20:48 zzzzz arvados-ws[9421]: {"level":"info","msg":"started","time":"2016-12-06T11:20:48.207617188-05:00"}
  87 Dec 06 11:20:48 zzzzz arvados-ws[9421]: {"Listen":":9003","level":"info","msg":"listening","time":"2016-12-06T11:20:48.244956506-05:00"}
  88 Dec 06 11:20:48 zzzzz systemd[1]: Started Arvados websocket server.
  89 </code></pre>
  90 </notextile>
  91
  92 If it is not running, use @journalctl@ to check logs for errors:
  93
  94 <notextile>
  95 <pre><code>~$ <span class="userinput">sudo journalctl -n10 -u arvados-ws</span>
  96 ...
  97 Dec 06 11:12:48 zzzzz systemd[1]: Starting Arvados websocket server...
  98 Dec 06 11:12:48 zzzzz arvados-ws[8918]: {"level":"info","msg":"started","time":"2016-12-06T11:12:48.030496636-05:00"}
  99 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"}
 100 </code></pre>
 101 </notextile>
 102
 103 Skip ahead to "confirm the service is working":#confirm.
 104
 105 h3(#runit). Start the service (option 2: runit)
 106
 107 Install runit to supervise the arvados-ws daemon.  {% include 'install_runit' %}
 108
 109 Create a supervised service.
 110
 111 <notextile>
 112 <pre><code>~$ <span class="userinput">sudo mkdir /etc/service/arvados-ws</span>
 113 ~$ <span class="userinput">cd /etc/service/arvados-ws</span>
 114 ~$ <span class="userinput">sudo mkdir log log/main</span>
 115 ~$ <span class="userinput">printf '#!/bin/sh\nexec arvados-ws 2>&1\n' | sudo tee run</span>
 116 ~$ <span class="userinput">printf '#!/bin/sh\nexec svlogd main\n' | sudo tee log/run</span>
 117 ~$ <span class="userinput">sudo chmod +x run log/run</span>
 118 ~$ <span class="userinput">sudo sv exit .</span>
 119 ~$ <span class="userinput">cd -</span>
 120 </code></pre>
 121 </notextile>
 122
 123 Use @sv stat@ and check the log file to verify the service is running.
 124
 125 <notextile>
 126 <pre><code>~$ <span class="userinput">sudo sv stat /etc/service/arvados-ws</span>
 127 run: /etc/service/arvados-ws: (pid 12520) 2s; run: log: (pid 12519) 2s
 128 ~$ <span class="userinput">tail /etc/service/arvados-ws/log/main/current</span>
 129 {"level":"info","msg":"started","time":"2016-12-06T11:56:20.669171449-05:00"}
 130 {"Listen":":9003","level":"info","msg":"listening","time":"2016-12-06T11:56:20.708847627-05:00"}
 131 </code></pre>
 132 </notextile>
 133
 134 h3(#confirm). Confirm the service is working
 135
 136 Confirm the service is listening on its assigned port and responding to requests.
 137
 138 <notextile>
 139 <pre><code>~$ <span class="userinput">curl http://0.0.0.0:<b>9003</b>/status.json</span>
 140 {"Clients":1}
 141 </code></pre>
 142 </notextile>
 143
 144 h3. Set up a reverse proxy with SSL support
 145
 146 The arvados-ws service will be accessible from anywhere on the internet, so we recommend using SSL for transport encryption.
 147
 148 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).
 149
 150 For example, using Nginx:
 151
 152 <notextile><pre>
 153 upstream arvados-ws {
 154   server                127.0.0.1:<span class="userinput">9003</span>;
 155 }
 156
 157 server {
 158   listen                <span class="userinput">[your public IP address]</span>:443 ssl;
 159   server_name           ws.<span class="userinput">uuid_prefix.your.domain</span>;
 160
 161   proxy_connect_timeout 90s;
 162   proxy_read_timeout    300s;
 163
 164   ssl                   on;
 165   ssl_certificate       <span class="userinput"/>YOUR/PATH/TO/cert.pem</span>;
 166   ssl_certificate_key   <span class="userinput"/>YOUR/PATH/TO/cert.key</span>;
 167
 168   location / {
 169     proxy_pass          http://arvados-ws;
 170     proxy_set_header    Upgrade         $http_upgrade;
 171     proxy_set_header    Connection      "upgrade";
 172     proxy_set_header    Host            $host;
 173     proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
 174   }
 175 }
 176 </pre></notextile>
 177
 178 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.
 179
 180 h3. Update API server configuration
 181
 182 Ensure the websocket server address is correct in the API server configuration file @/etc/arvados/api/application.yml@.
 183
 184 <notextile>
 185 <pre><code>websocket_address: wss://ws.<span class="userinput">uuid_prefix.your.domain</span>/websocket
 186 </code></pre>
 187 </notextile>
 188
 189 Restart Nginx to reload the API server configuration.
 190
 191 <notextile>
 192 <pre><code>$ sudo nginx -s reload</span>
 193 </code></pre>
 194 </notextile>
 195
 196 h3. Verify DNS and proxy setup
 197
 198 Use a host elsewhere on the Internet to confirm that your DNS, proxy, and SSL are configured correctly.
 199
 200 <notextile>
 201 <pre><code>$ <span class="userinput">curl https://ws.<b>uuid_prefix.your.domain</b>/status.json</span>
 202 {"Clients":1}
 203 </code></pre>
 204 </notextile>