3 navsection: installguide
4 title: Install the websocket server
7 Copyright (C) The Arvados Authors. All rights reserved.
9 SPDX-License-Identifier: CC-BY-SA-3.0
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.
14 By convention, we use the following hostname for the websocket service.
17 <pre><code>ws.<span class="userinput">uuid_prefix.your.domain</span></code></pre>
20 The above hostname should resolve from anywhere on the internet.
22 h2. Install arvados-ws
24 Typically arvados-ws runs on the same host as the API server.
26 On Debian-based systems:
29 <pre><code>~$ <span class="userinput">sudo apt-get install arvados-ws</span>
33 On Red Hat-based systems:
36 <pre><code>~$ <span class="userinput">sudo yum install arvados-ws</span>
40 Verify that @arvados-ws@ is functional:
43 <pre><code>~$ <span class="userinput">arvados-ws -h</span>
46 path to config file (default "/etc/arvados/config.yml")
48 show current configuration and exit
52 h3. Update cluster config
54 Edit the cluster config at @/etc/arvados/config.yml@ and set @Services.Websocket.ExternalURL@ and @Services.Websocket.InternalURLs@. Replace @zzzzz@ with your cluster id. Assumes that the @Services.API@ and @PostgreSQL@ sections are already filled out.
61 <span class="userinput">
63 ExternalURL: wss://ws.uuid_prefix.your.domain/websocket
65 "http://localhost:9003": {}
69 h3. Start the service (option 1: systemd)
71 If your system does not use systemd, skip this section and follow the "runit instructions":#runit instead.
73 If your system uses systemd, the arvados-ws service should already be set up. Start it and check its status:
76 <pre><code>~$ <span class="userinput">sudo systemctl restart arvados-ws</span>
77 ~$ <span class="userinput">sudo systemctl status arvados-ws</span>
78 ● 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
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.
92 If it is not running, use @journalctl@ to check logs for errors:
95 <pre><code>~$ <span class="userinput">sudo journalctl -n10 -u arvados-ws</span>
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"}
103 Skip ahead to "confirm the service is working":#confirm.
105 h3(#runit). Start the service (option 2: runit)
107 Install runit to supervise the arvados-ws daemon. {% include 'install_runit' %}
109 Create a supervised service.
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>
123 Use @sv stat@ and check the log file to verify the service is running.
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"}
134 h3(#confirm). Confirm the service is working
136 Confirm the service is listening on its assigned port and responding to requests.
139 <pre><code>~$ <span class="userinput">curl http://0.0.0.0:<b>9003</b>/status.json</span>
144 h3. Set up a reverse proxy with SSL support
146 The arvados-ws service will be accessible from anywhere on the internet, so we recommend using SSL for transport encryption.
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).
150 For example, using Nginx:
153 upstream arvados-ws {
154 server 127.0.0.1:<span class="userinput">9003</span>;
158 listen <span class="userinput">[your public IP address]</span>:443 ssl;
159 server_name ws.<span class="userinput">uuid_prefix.your.domain</span>;
161 proxy_connect_timeout 90s;
162 proxy_read_timeout 300s;
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>;
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;
178 {% include 'notebox_begin' %}
179 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.
180 {% include 'notebox_end' %}
182 h3. Update API server configuration
184 Restart Nginx to reload the API server configuration.
187 <pre><code>$ sudo nginx -s reload</span>
191 h3. Verify DNS and proxy setup
193 Use a host elsewhere on the Internet to confirm that your DNS, proxy, and SSL are configured correctly.
196 <pre><code>$ <span class="userinput">curl https://ws.<b>uuid_prefix.your.domain</b>/status.json</span>