X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/e51a22dc5b9da795b68c87cb9d0a45e4732ed2f6..2a96c097e5a176018d078a5d6985403072e8672e:/doc/install/install-api-server.html.textile.liquid diff --git a/doc/install/install-api-server.html.textile.liquid b/doc/install/install-api-server.html.textile.liquid index f5d5825377..1c5f04fe34 100644 --- a/doc/install/install-api-server.html.textile.liquid +++ b/doc/install/install-api-server.html.textile.liquid @@ -16,21 +16,19 @@ h3(#install_postgres). Install PostgreSQL {% include 'install_postgres' %} -h3(#build_tools_apiserver). Build tools - -On older distributions, you may need to use a backports repository to satisfy these requirements. For example, on older Red Hat-based systems, consider using the "postgresql92":https://www.softwarecollections.org/en/scls/rhscl/postgresql92/ and "nginx16":https://www.softwarecollections.org/en/scls/rhscl/nginx16/ Software Collections. +h2(#install_apiserver). Install API server and dependencies On a Debian-based system, install the following packages: -
~$ sudo apt-get install bison build-essential libcurl4-openssl-dev git nginx arvados-api-server
+
~$ sudo apt-get install bison build-essential libcurl4-openssl-dev git arvados-api-server
 

 
 
 On a Red Hat-based system, install the following packages:
 
 
-
~$ sudo yum install bison make automake gcc gcc-c++ libcurl-devel nginx git arvados-api-server
+
~$ sudo yum install bison make automake gcc gcc-c++ libcurl-devel git arvados-api-server
 

 
 
@@ -73,7 +71,7 @@ The API server package uses configuration files that you write to @/etc/arvados/
 
~$ sudo mkdir -p /etc/arvados/api
 ~$ sudo chmod 700 /etc/arvados/api
 ~$ cd /var/www/arvados-api/current
-/var/www/arvados-api/current$ sudo cp config/database.yml.sample /etc/arvados/api/database.yml
+/var/www/arvados-api/current$ sudo cp config/database.yml.example /etc/arvados/api/database.yml
 /var/www/arvados-api/current$ sudo cp config/application.yml.example /etc/arvados/api/application.yml
 

 
@@ -82,61 +80,120 @@ h2. Configure the database connection
 
 Edit @/etc/arvados/api/database.yml@ and replace the @xxxxxxxx@ database password placeholders with the PostgreSQL password you generated above.
 
-h2. Configure the API server
+h2(#configure_application). Configure the API server
+
+Edit @/etc/arvados/api/application.yml@ to configure the settings described in the following sections.  The deployment script will consistently deploy this to the API server's configuration directory.  The API server reads both @application.yml@ and its own @config/application.default.yml@ file.  The settings in @application.yml@ take precedence over the defaults that are defined in @config/application.default.yml@.  The @config/application.yml.example@ file is not read by the API server and is provided as a starting template only.
 
-Edit @/etc/arvados/api/application.yml@ following the instructions below.  The deployment script will consistently deploy this to the API server's configuration directory.  The API server reads both @application.yml@ and its own @config/application.default.yml@ file.  Values in @application.yml@ take precedence over the defaults that are defined in @config/application.default.yml@.  The @config/application.yml.example@ file is not read by the API server and is provided for installation convenience only.
+@config/application.default.yml@ documents additional configuration settings not listed here.  You can "view the current source version":https://arvados.org/projects/arvados/repository/revisions/master/entry/services/api/config/application.default.yml for reference.
 
-Always put your local configuration in @application.yml@ instead of editing @application.default.yml@.
+Only put local configuration in @application.yml@.  Do not edit @application.default.yml@.
 
 h3(#uuid_prefix). uuid_prefix
 
-Define your @uuid_prefix@ in @application.yml@ by setting the @uuid_prefix@ field in the section for your environment.  This prefix is used for all database identifiers to identify the record as originating from this site.  It must be exactly 5 alphanumeric characters (lowercase ASCII letters and digits).
+Define your @uuid_prefix@ in @application.yml@ by setting the @uuid_prefix@ field in the section for your environment.  This prefix is used for all database identifiers to identify the record as originating from this site.  It must be exactly 5 lowercase ASCII letters and digits.
 
-h3(#git_repositories_dir). git_repositories_dir
+Example @application.yml@:
+
+
+
  uuid_prefix: zzzzz

+
+
+h3. secret_token
 
-Additional git setup will be done on the "next page":install-arv-git-httpd.html. For now, just create the repository storage directory.
+The @secret_token@ is used for for signing cookies.  IMPORTANT: This is a site secret. It should be at least 50 characters.  Generate a random value and set it in @application.yml@:
 
 
-
~$ sudo mkdir -p /var/lib/arvados/git/repositories
+
~$ ruby -e 'puts rand(2**400).to_s(36)'
+yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
 

 
-h3. secret_token
+Example @application.yml@:
+
+
+
  secret_token: yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

+
 
-Generate a new secret token for signing cookies:
+h3(#blob_signing_key). blob_signing_key
+
+The @blob_signing_key@ is used to enforce access control to Keep blocks.  This same key must be provided to the Keepstore daemons when "installing Keepstore servers.":install-keepstore.html  IMPORTANT: This is a site secret. It should be at least 50 characters.  Generate a random value and set it in @application.yml@:
 
 
 
~$ ruby -e 'puts rand(2**400).to_s(36)'
-zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
+xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 

 
-Then put that value in the @secret_token@ field.
+Example @application.yml@:
+
+
+
  blob_signing_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

+
+
+h3(#omniauth). sso_app_secret, sso_app_id, sso_provider_url
+
+The following settings enable the API server to communicate with the "Single Sign On (SSO) server":install-sso.html to authenticate user log in.
+
+Set @sso_provider_url@ to the base URL where your SSO server is installed.  This should be a URL consisting of the scheme and host (and optionally, port), without a trailing slash.
 
-h3. blob_signing_key
+Set @sso_app_secret@ and @sso_app_id@ to the corresponding values for @app_secret@ and @app_id@ used in the "Create arvados-server client for Single Sign On (SSO)":install-sso.html#client step.
 
-If you want access control on your "Keepstore":install-keepstore.html server(s), you should set @blob_signing_key@ to the same value as the permission key you provide to your Keepstore daemon(s).
+Example @application.yml@:
+
+
+
  sso_app_id: arvados-server
+  sso_app_secret: wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
+  sso_provider_url: https://sso.example.com
+

+
 
 h3. workbench_address
 
-Fill in the url of your workbench application in @workbench_address@, for example
+Set @workbench_address@ to the URL of your workbench application after following "Install Workbench.":install-workbench-app.html
+
+Example @application.yml@:
+
+
+
  workbench_address: https://workbench.zzzzz.example.com

+
+
+h3. websocket_address
+
+Set @websocket_address@ to the @wss://@ URL of the API server websocket endpoint after following "Set up Web servers":#set_up.  The path of the default endpoint is @/websocket@.
+
+Example @application.yml@:
+
+
+
  websocket_address: wss://ws.zzzzz.example.com/websocket

+
+
+h3(#git_repositories_dir). git_repositories_dir
+
+The @git_repositories_dir@ setting specifies the directory where user git repositories will be stored.
 
-  https://workbench.@uuid_prefix@.your.domain
+The git server setup process is covered on "its own page":install-arv-git-httpd.html. For now, create an empty directory in the default location:
 
-h3(#omniauth). sso_app_id, sso_app_secret, sso_provider_url
+
+
~$ sudo mkdir -p /var/lib/arvados/git/repositories
+

 
-For @sso_app_id@ and @sso_app_secret@, provide the same @app_id@ and @app_secret@ used in the "Create arvados-server client for Single Sign On (SSO)":install-sso.html#client step.
+If you intend to store your git repositories in a different location, specify that location in @application.yml@.
 
-For @sso_provider_url@, provide the base URL where your SSO server is installed: just the scheme and host, with no trailing slash.
+Default setting in @application.default.yml@:
 
 
-
  sso_app_id: arvados-server
-  sso_app_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-  sso_provider_url: https://sso.example.com
+
  git_repositories_dir: /var/lib/arvados/git/repositories
 

 
 
-h3. Other options
+h3(#git_internal_dir). git_internal_dir
 
-Consult @/var/www/arvados-api/current/config/application.default.yml@ for a full list of configuration options. (But don't edit it. Edit @application.yml@ instead.)
+The @git_internal_dir@ setting specifies the location of Arvados' internal git repository.  By default this is @/var/lib/arvados/internal.git@.  This repository stores git commits that have been used to run Crunch jobs.  It should _not_ be a subdirectory of @git_repositories_dir@.
+
+Example @application.yml@:
+
+
+
  git_internal_dir: /var/lib/arvados/internal.git
+

+
 
 h2. Prepare the API server deployment
 
@@ -151,17 +208,15 @@ break this application for all non-root users on this machine.

 
 This command aborts when it encounters an error.  It's safe to rerun multiple times, so if there's a problem with your configuration, you can fix that and try again.
 
-h2. Set up Web servers
+h2(#set_up). Set up Web servers
 
 For best performance, we recommend you use Nginx as your Web server front-end, with a Passenger backend for the main API server and a Puma backend for API server Websockets.  To do that:
 
 
 
    
-
  1. Install Nginx via your distribution or a backports repository.
    2. 
-
-
  2. Install Phusion Passenger for Nginx.
    3. 
+
  3. Install Nginx and Phusion Passenger.
    4. 
 
-
  4. Puma is already included with the API server's gems.  We recommend you use a tool like runit or something similar.  Here's a sample run script for that:
    
+
  5. Puma is already included with the API server's gems.  We recommend you run it as a service under runit or a similar tool.  Here's a sample runit script for that:
    
 
 
    #!/bin/bash
 
@@ -209,17 +264,37 @@ upstream websockets {
 
 proxy_http_version 1.1;
 
+# When Keep clients request a list of Keep services from the API server, the
+# server will automatically return the list of available proxies if
+# the request headers include X-External-Client: 1.  Following the example
+# here, at the end of this section, add a line for each netmask that has
+# direct access to Keep storage daemons to set this header value to 0.
+geo $external_client {
+  default        1;
+  10.20.30.0/24  0;
+}
+
 server {
   listen       [your public IP address]:443 ssl;
   server_name  uuid_prefix.your.domain;
 
   ssl on;
+  ssl_certificate     /YOUR/PATH/TO/cert.pem;
+  ssl_certificate_key /YOUR/PATH/TO/cert.key;
 
   index  index.html index.htm index.php;
 
+  # This value effectively limits the size of API objects users can create,
+  # especially collections.  If you change this, you should also set
+  # `max_request_size` in the API server's application.yml file to the same
+  # value.
+  client_max_body_size 128m;
+
   location / {
     proxy_pass            http://api;
     proxy_redirect        off;
+    proxy_connect_timeout 90s;
+    proxy_read_timeout    300s;
 
     proxy_set_header      X-Forwarded-Proto https;
     proxy_set_header      Host $http_host;
@@ -234,12 +309,16 @@ server {
   server_name  ws.uuid_prefix.your.domain;
 
   ssl on;
+  ssl_certificate     /YOUR/PATH/TO/cert.pem;
+  ssl_certificate_key /YOUR/PATH/TO/cert.key;
 
   index  index.html index.htm index.php;
 
   location / {
     proxy_pass            http://websockets;
     proxy_redirect        off;
+    proxy_connect_timeout 90s;
+    proxy_read_timeout    300s;
 
     proxy_set_header      Upgrade $http_upgrade;
     proxy_set_header      Connection "upgrade";
@@ -251,7 +330,12 @@ server {
 
    
 
    6. 
 
-
  6. Restart Nginx.
    7. 
+
  7. Restart Nginx:
    
+
+
    ~$ sudo nginx -s reload
+
    
+
+
    8.