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;
  }
}

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