X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/409d130ddcc4b76def5fa8d61d2584725c61152a..5dce317bcb52fb20e0849f08b5359a8d00bc2954:/doc/install/install-ws.html.textile.liquid
diff --git a/doc/install/install-ws.html.textile.liquid b/doc/install/install-ws.html.textile.liquid
index a36a59a56f..74c4cf3a92 100644
--- a/doc/install/install-ws.html.textile.liquid
+++ b/doc/install/install-ws.html.textile.liquid
@@ -3,167 +3,55 @@ layout: default
navsection: installguide
title: Install the websocket server
...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
-{% include 'notebox_begin_warning' %}
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
-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.
+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/arvados/arvados/services/ws for additional information.
-{% include 'notebox_end' %}
+# "Update config.yml":#update-config
+# "Update nginx configuration":#update-nginx
+# "Install arvados-ws package":#install-packages
+# "Start the service":#start-service
+# "Restart the API server and controller":#restart-api
+# "Confirm working installation":#confirm-working
-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.
+h2(#configure). Update config.yml
-By convention, we use the following hostname for the websocket service.
+Edit the cluster config at @config.yml@ and set @Services.Websocket.ExternalURL@ and @Services.Websocket.InternalURLs@. Replace @zzzzz@ with your cluster id.
-ws.uuid_prefix.your.domain
+ Services:
+ Websocket:
+ InternalURLs:
+ "http://localhost:8005": {}
+ ExternalURL: wss://ws.ClusterID.example.com/websocket
+
-The above hostname should resolve from anywhere on the internet.
-
-h2. 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
-
-
-
-h3. Create a configuration file
-
-Create @/etc/arvados/ws/ws.yml@ using the following template. Replace @xxxxxxxx@ with the "password you generated during database setup":install-postgresql.html#api.
-
-
-Client:
- APIHost: uuid_prefix.your.domain:443
-Listen: ":9003"
-Postgres:
- dbname: arvados_production
- host: localhost
- password: xxxxxxxx
- user: arvados
-
-
-
-h3. Start the service (option 1: systemd)
-
-If your system does not use systemd, skip this section and follow the "runit instructions":#runit 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":#confirm.
-
-h3(#runit). Start the service (option 2: runit)
-
-Install runit to supervise the arvados-ws daemon. {% include '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"}
-
-
-
-h3(#confirm). 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}
-
-
-
-h3. Set up a reverse proxy with SSL support
+h2(#update-nginx). Update Nginx configuration
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:
+Use a text editor to create a new file @/etc/nginx/conf.d/arvados-ws.conf@ with the following configuration. Options that need attention are marked in red.
upstream arvados-ws {
- server 127.0.0.1:9003;
+ server 127.0.0.1:8005;
}
server {
- listen [your public IP address]:443 ssl;
- server_name ws.uuid_prefix.your.domain;
+ listen 443 ssl;
+ server_name ws.ClusterID.example.com;
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;
+ ssl_certificate /YOUR/PATH/TO/cert.pem;
+ ssl_certificate_key /YOUR/PATH/TO/cert.key;
location / {
proxy_pass http://arvados-ws;
@@ -175,30 +63,24 @@ server {
}
-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.
+{% assign arvados_component = 'arvados-ws' %}
-h3. Update API server configuration
+{% include 'install_packages' %}
-Ensure the websocket server address is correct in the API server configuration file @/etc/arvados/api/application.yml@.
+{% include 'start_service' %}
-
-websocket_address: wss://ws.uuid_prefix.your.domain/websocket
-
-
+{% include 'restart_api' %}
-Restart Nginx to reload the API server configuration.
+h2(#confirm). Confirm working installation
-
-$ sudo nginx -s reload
-
-
+We recommend using the "Cluster diagnostics tool.":diagnostics.html
-h3. Verify DNS and proxy setup
+Here are some other checks you can perform manually.
-Use a host elsewhere on the Internet to confirm that your DNS, proxy, and SSL are configured correctly.
+Confirm the service is listening on its assigned port and responding to requests.
-$ curl https://ws.uuid_prefix.your.domain/status.json
-{"Clients":1}
+~$ curl https://ws.ClusterID.example.com/websocket
+not websocket protocol