Documentation: installation pages improvements. Be clear about the

[arvados.git] / doc / install / install-keepproxy.html.textile.liquid

diff --git a/doc/install/install-keepproxy.html.textile.liquid b/doc/install/install-keepproxy.html.textile.liquid
index 67258983f1123f9cceb5070d84d60bddb5eec8f3..9e8f8787825490ce5c7eab1fdb6427f8f564df6e 100644 (file)
--- a/doc/install/install-keepproxy.html.textile.liquid
+++ b/doc/install/install-keepproxy.html.textile.liquid
@@ -23,11 +23,10 @@ h2. Install Keepproxy
 First add the Arvados apt repository, and then install the Keepproxy package.
 
 <notextile>
-<pre><code>~$ <span class="userinput">echo "# apt.arvados.org" > /etc/apt/sources.list.d/apt.arvados.org.list</span>
-~$ <span class="userinput">echo "deb http://apt.arvados.org/ wheezy main" >> /etc/apt/sources.list.d/apt.arvados.org.list</span>
-~$ <span class="userinput">/usr/bin/apt-key adv --keyserver pool.sks-keyservers.net --recv 1078ECD7</span>
-~$ <span class="userinput">/usr/bin/apt-get update</span>
-~$ <span class="userinput">/usr/bin/apt-get install keepproxy</span>
+<pre><code>~$ <span class="userinput">echo "deb http://apt.arvados.org/ wheezy main" | sudo tee /etc/apt/sources.list.d/apt.arvados.org.list</span>
+~$ <span class="userinput">sudo /usr/bin/apt-key adv --keyserver pool.sks-keyservers.net --recv 1078ECD7</span>
+~$ <span class="userinput">sudo /usr/bin/apt-get update</span>
+~$ <span class="userinput">sudo /usr/bin/apt-get install keepproxy</span>
 </code></pre>
 </notextile>
 
@@ -48,33 +47,13 @@ It's recommended to run Keepproxy under "runit":https://packages.debian.org/sear
 
 h3. Create an API token for the Keepproxy server
 
-The Keepproxy server needs a token to talk to the API server. The token can be associated with the root user. On the <strong>shell server</strong>, use the following command to create the token.
+The Keepproxy server needs a token to talk to the API server.
+
+On the <strong>API server</strong>, use the following command to create the token:
 
 <notextile>
-<pre><code>~$ <span class="userinput">arv api_client_authorization create_system_auth --scopes "[]"</span>
-{
- "href":"/api_client_authorizations/oethieWeKohy4aesahv2moh0Dapheigh9aeNo3uSahg6yaihui",
- "kind":"arvados#apiClientAuthorization",
- "etag":"ieLohYieh5joo3ahxaileChoo",
- "uuid":"oethieWeKohy4aesahv2moh0Dapheigh9aeNo3uSahg6yaihui",
- "owner_uuid":"uuid_prefix-tpzed-000000000000000",
- "created_at":"2014-10-29T15:01:57Z",
- "modified_by_client_uuid":null,
- "modified_by_user_uuid":null,
- "modified_at":null,
- "user_id":1,
- "api_client_id":0,
- "api_token":"fiekieth2luaWe0feePh7yoo6MaifahChaet4ulaitoothais9",
- "created_by_ip_address":"10.1.1.1",
- "default_owner_uuid":null,
- "expires_at":null,
- "last_used_at":null,
- "last_used_by_ip_address":null,
- "scopes":[],
- "_profile":{
-  "request_time":0.037659336
- }
-}
+<pre><code>~/arvados/services/api/script$ <span class="userinput">RAILS_ENV=production ./get_anonymous_user_token.rb</span>
+hoShoomoo2bai3Ju1xahg6aeng1siquuaZ1yae2gi2Uhaeng2r
 </code></pre></notextile>
 
 The value for the @api_token@ field should be added to Keepproxy's environment as ARVADOS_API_TOKEN. Make sure to also set ARVADOS_API_HOST to @uuid_prefix@.your.domain.
@@ -85,6 +64,21 @@ Because the Keepproxy is intended for access from anywhere on the internet, it i
 
 This is best achieved by putting a reverse proxy with SSL support in front of Keepproxy. Keepproxy itself runs on port 25107 by default; your reverse proxy can run on port 443 and pass requests to Keepproxy on port 25107.
 
+If possible, the proxy should be configured to add CORS headers to its own error responses -- otherwise in-browser applications can't report proxy errors. For example, in nginx >= 1.7.5:
+
+<notextile><pre>
+server {
+  server_name keep.example.com
+  ...
+  add_header 'Access-Control-Allow-Methods' 'GET, HEAD, POST, PUT, OPTIONS' always
+  add_header 'Access-Control-Allow-Origin' '*' always
+  add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Length, Content-Type, X-Keep-Desired-Replicas' always
+  add_header 'Access-Control-Max-Age' '86486400' always
+}
+</pre></notextile>
+
+*Warning:* Make sure you don't inadvertently add CORS headers for services _other than keepproxy_ while you're doing this.
+
 h3. Tell the API server about the Keepproxy server
 
 The API server needs to be informed about the presence of your Keepproxy server. Please execute the following commands on your <strong>shell server</strong>.