X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/855a790d7be3ff345f04226bde3719fb90e6d9a5..6e5158294c7e19af9031fc43fefc21275e758911:/doc/install/install-api-server.html.textile.liquid?ds=inline
diff --git a/doc/install/install-api-server.html.textile.liquid b/doc/install/install-api-server.html.textile.liquid
index c3d5200b16..1c5f04fe34 100644
--- a/doc/install/install-api-server.html.textile.liquid
+++ b/doc/install/install-api-server.html.textile.liquid
@@ -4,182 +4,338 @@ navsection: installguide
title: Install the API server
...
-This installation guide assumes you are on a 64 bit Debian or Ubuntu system.
-
h2. Install prerequisites
-~$ sudo apt-get install \
- bison build-essential gettext libcurl3 libcurl3-gnutls \
- libcurl4-openssl-dev libpcre3-dev libpq-dev libreadline-dev \
- libssl-dev libxslt1.1 postgresql sudo wget zlib1g-dev
-
~$ cd $HOME # (or wherever you want to install)
-~$ git clone https://github.com/curoverse/arvados.git
-
~$ cd arvados/services/api
-~/arvados/services/api$ bundle install
-
~$ sudo apt-get install bison build-essential libcurl4-openssl-dev git arvados-api-server
+
+
-h2. Choose your environment
+On a Red Hat-based system, install the following packages:
-The API server can be run in @development@ or in @production@ mode. Unless this installation is going to be used for development on the Arvados API server itself, you should run it in @production@ mode.
+~$ sudo yum install bison make automake gcc gcc-c++ libcurl-devel git arvados-api-server
+
+~/arvados/services/api$ cp -i config/environments/production.rb.example config/environments/production.rb
+~$ ruby -e 'puts rand(2**128).to_s(36)'
+6gqa1vu492idd7yca9tfandj3
~/arvados/services/api$ cp -i config/application.yml.example config/application.yml
+~$ sudo -u postgres createuser --encrypted -R -S --pwprompt arvados
+[sudo] password for you: yourpassword
+Enter password for new role: paste-password-you-generated
+Enter it again: paste-password-again
~$ sudo -u postgres createdb arvados_production -T template0 -E UTF8 -O arvados
+
+~/arvados/services/api$ sudo mkdir -p /var/lib/arvados/git
-~/arvados/services/api$ sudo git clone --bare ../../.git /var/lib/arvados/git/arvados.git
-
~$ 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.example /etc/arvados/api/database.yml
+/var/www/arvados-api/current$ sudo cp config/application.yml.example /etc/arvados/api/application.yml
+
+
-Generate a new secret token for signing cookies:
+h2. Configure the database connection
-~/arvados/services/api$ rake secret
-zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
-
uuid_prefix: zzzzz
+~/arvados/services/api$ ruby -e 'puts rand(2**128).to_s(36)'
-6gqa1vu492idd7yca9tfandj3
+~$ ruby -e 'puts rand(2**400).to_s(36)'
+yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
~/arvados/services/api$ sudo -u postgres createuser --createdb --encrypted --pwprompt arvados
-[sudo] password for you: yourpassword
-Enter password for new role: paste-password-you-generated
-Enter it again: paste-password-again
-Shall the new role be a superuser? (y/n) n
-Shall the new role be allowed to create more new roles? (y/n) n
-
secret_token: yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
+
+
+h3(#blob_signing_key). blob_signing_key
-Configure API server to connect to your database by creating and updating @config/database.yml@. Replace the @xxxxxxxx@ database password placeholders with the new password you generated above.
+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@:
~/arvados/services/api$ cp -i config/database.yml.sample config/database.yml
-~/arvados/services/api$ edit config/database.yml
+~$ ruby -e 'puts rand(2**400).to_s(36)'
+xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
~/arvados/services/api$ RAILS_ENV=production bundle exec rake db:setup
-
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.
+
+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.
-Alternatively, if the database user you intend to use for the API server is not allowed to create new databases, you can create the database first and then populate it with rake. Be sure to adjust the database name if you are using the @development@ environment. This sequence of commands is functionally equivalent to the rake db:setup command above.
+Example @application.yml@:
~/arvados/services/api$ su postgres createdb arvados_production -E UTF8 -O arvados
-~/arvados/services/api$ RAILS_ENV=production bundle exec rake db:structure:load
-~/arvados/services/api$ RAILS_ENV=production bundle exec rake db:seed
-
sso_app_id: arvados-server
+ sso_app_secret: wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
+ sso_provider_url: https://sso.example.com
+
+
+
+h3. workbench_address
+
+Set @workbench_address@ to the URL of your workbench application after following "Install Workbench.":install-workbench-app.html
+
+Example @application.yml@:
-{% include 'notebox_begin' %}
-You can safely ignore the following error message you may see when loading the database structure:
ERROR: must be owner of extension plpgsql
workbench_address: https://workbench.zzzzz.example.com
+
+
+h3. websocket_address
-h2(#omniauth). Set up omniauth
+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@.
-First copy the omniauth configuration file:
+Example @application.yml@:
~/arvados/services/api$ cp -i config/initializers/omniauth.rb.example config/initializers/omniauth.rb
+ websocket_address: wss://ws.zzzzz.example.com/websocket
+
~$ sudo mkdir -p /var/lib/arvados/git/repositories
APP_ID = 'arvados-server'
-APP_SECRET = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
-CUSTOM_PROVIDER_URL = 'https://sso.example.com/'
+ git_repositories_dir: /var/lib/arvados/git/repositories
~/arvados/services/api$ bundle exec rails server --port=3030
-
git_internal_dir: /var/lib/arvados/internal.git
+
+
-h3. Production environment
+h2. Prepare the API server deployment
-We recommend "Passenger":https://www.phusionpassenger.com/ to run the API server in production.
+Now that all your configuration is in place, run @/usr/local/bin/arvados-api-server-upgrade.sh@. This will install and check your configuration, install necessary gems, and run any necessary database setup.
-Point it to the services/api directory in the source tree.
+{% include 'notebox_begin' %}
+You can safely ignore the following messages if they appear while this script runs:
+Don't run Bundler as root. Bundler can ask for sudo if it is needed, and installing your bundle as root will +break this application for all non-root users on this machine.+
fatal: Not a git repository (or any of the parent directories): .git+{% include 'notebox_end' %} + +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). Set up Web servers -To enable streaming so users can monitor crunch jobs in real time, make sure to add the following to your Passenger configuration: +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:
PassengerBufferResponse off
+
+- Install Nginx and Phusion Passenger.
+
+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
+
+set -e
+exec 2>&1
+
+# Uncomment the line below if you're using RVM.
+#source /etc/profile.d/rvm.sh
+
+envdir="`pwd`/env"
+mkdir -p "$envdir"
+echo ws-only > "$envdir/ARVADOS_WEBSOCKETS"
+
+cd /var/www/arvados-api/current
+echo "Starting puma in `pwd`"
+
+# You may need to change arguments below to match your deployment, especially -u.
+exec chpst -m 1073741824 -u www-data:www-data -e "$envdir" \
+ bundle exec puma -t 0:512 -e production -b tcp://127.0.0.1:8100
+
+
+
+Edit the http section of your Nginx configuration to run the Passenger server, and act as a front-end for both it and Puma. You might add a block like the following, adding SSL and logging parameters to taste:
+
+server {
+ listen 127.0.0.1:8000;
+ server_name localhost-api;
+
+ root /var/www/arvados-api/current/public;
+ index index.html index.htm index.php;
+
+ passenger_enabled on;
+ # If you're using RVM, uncomment the line below.
+ #passenger_ruby /usr/local/rvm/wrappers/default/ruby;
+}
+
+upstream api {
+ server 127.0.0.1:8000 fail_timeout=10s;
+}
+
+upstream websockets {
+ # The address below must match the one specified in puma's -b option.
+ server 127.0.0.1:8100 fail_timeout=10s;
+}
+
+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;
+ proxy_set_header X-External-Client $external_client;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ }
+}
+
+server {
+ listen [your public IP address]:443 ssl;
+ 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";
+ proxy_set_header Host $host;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ }
+}
+
+
+Restart Nginx:
+
+~$ sudo nginx -s reload
+
+
+
+
+