Install the websocket server

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 for additional information.

By convention, we use the following hostname for the websocket service.

ws.uuid_prefix.your.domain

The above hostname should resolve from anywhere on the internet.

Install arvados-ws

Typically arvados-ws runs on the same host as the API server.

On Debian-based systems:

~$ sudo apt-get install arvados-ws

On Red Hat-based systems:

~$ sudo yum install arvados-ws

Verify that arvados-ws is functional:

~$ arvados-ws -h
Usage of arvados-ws:
  -config path
        path to config file (default "/etc/arvados/ws/ws.yml")
  -dump-config
        show current configuration and exit

Create a configuration file

Create /etc/arvados/ws/ws.yml using the following template. Replace xxxxxxxx with the password you generated during database setup.

Client:
  APIHost: uuid_prefix.your.domain:443
Listen: ":9003"
Postgres:
  dbname: arvados_production
  host: localhost
  password: xxxxxxxx
  user: arvados

Start the service (option 1: systemd)

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

If your system uses systemd, the arvados-ws service should already be set up. Start it and check its status:

~$ sudo systemctl restart arvados-ws
~$ sudo systemctl status arvados-ws
● arvados-ws.service - Arvados websocket server
   Loaded: loaded (/lib/systemd/system/arvados-ws.service; enabled)
   Active: active (running) since Tue 2016-12-06 11:20:48 EST; 10s ago
     Docs: https://doc.arvados.org/
 Main PID: 9421 (arvados-ws)
   CGroup: /system.slice/arvados-ws.service
           └─9421 /usr/bin/arvados-ws

Dec 06 11:20:48 zzzzz arvados-ws[9421]: {"level":"info","msg":"started","time":"2016-12-06T11:20:48.207617188-05:00"}
Dec 06 11:20:48 zzzzz arvados-ws[9421]: {"Listen":":9003","level":"info","msg":"listening","time":"2016-12-06T11:20:48.244956506-05:00"}
Dec 06 11:20:48 zzzzz systemd[1]: Started Arvados websocket server.

If it is not running, use journalctl to check logs for errors:

~$ sudo journalctl -n10 -u arvados-ws
...
Dec 06 11:12:48 zzzzz systemd[1]: Starting Arvados websocket server...
Dec 06 11:12:48 zzzzz arvados-ws[8918]: {"level":"info","msg":"started","time":"2016-12-06T11:12:48.030496636-05:00"}
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"}

Skip ahead to confirm the service is working.

Start the service (option 2: runit)

Install runit to supervise the arvados-ws daemon.

On Debian-based systems:

~$ sudo apt-get install runit

On Red Hat-based systems:

~$ sudo yum install runit

Create a supervised service.

~$ sudo mkdir /etc/service/arvados-ws
~$ cd /etc/service/arvados-ws
~$ sudo mkdir log log/main
~$ printf '#!/bin/sh\nexec arvados-ws 2>&1\n' | sudo tee run
~$ printf '#!/bin/sh\nexec svlogd main\n' | sudo tee log/run
~$ sudo chmod +x run log/run
~$ sudo sv exit .
~$ cd -

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

~$ sudo sv stat /etc/service/arvados-ws
run: /etc/service/arvados-ws: (pid 12520) 2s; run: log: (pid 12519) 2s
~$ tail /etc/service/arvados-ws/log/main/current
{"level":"info","msg":"started","time":"2016-12-06T11:56:20.669171449-05:00"}
{"Listen":":9003","level":"info","msg":"listening","time":"2016-12-06T11:56:20.708847627-05:00"}

Confirm the service is working

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

~$ curl http://0.0.0.0:9003/status.json
{"Clients":1}

Set up a reverse proxy with SSL support

The arvados-ws service will be accessible from anywhere on the internet, so we recommend using SSL for transport encryption.

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

For example, using Nginx:

upstream arvados-ws {
  server                127.0.0.1:9003;
}

server {
  listen                [your public IP address]:443 ssl;
  server_name           ws.uuid_prefix.your.domain;

  proxy_connect_timeout 90s;
  proxy_read_timeout    300s;

  ssl                   on;
  ssl_certificate       YOUR/PATH/TO/cert.pem;
  ssl_certificate_key   YOUR/PATH/TO/cert.key;

  location / {
    proxy_pass          http://arvados-ws;
    proxy_set_header    Upgrade         $http_upgrade;
    proxy_set_header    Connection      "upgrade";
    proxy_set_header    Host            $host;
    proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}

Note:

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.

Update API server configuration

Ensure the websocket server address is correct in the API server configuration file /etc/arvados/api/application.yml.

websocket_address: wss://ws.uuid_prefix.your.domain/websocket

Restart Nginx to reload the API server configuration.

$ sudo nginx -s reload

Verify DNS and proxy setup

Use a host elsewhere on the Internet to confirm that your DNS, proxy, and SSL are configured correctly.

$ curl https://ws.uuid_prefix.your.domain/status.json
{"Clients":1}

Previous: Install Composer Next: Install a shell server

The content of this documentation is licensed under the Creative Commons Attribution-Share Alike 3.0 United States licence.
Code samples in this documentation are licensed under the Apache License, Version 2.0.