X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/f3e7d40574c721225c280de14394ffd5b97ab4ab..9024a5b5eb247e3a552dbb92a61f7c916c0d4349:/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 3aa123e26f..464559a74c 100644
--- a/doc/install/install-api-server.html.textile.liquid
+++ b/doc/install/install-api-server.html.textile.liquid
@@ -4,182 +4,348 @@ 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
-
~$ 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 git arvados-api-server
+
+~$ cd arvados/services/api
-~/arvados/services/api$ bundle install
+~$ ruby -e 'puts rand(2**128).to_s(36)'
+6gqa1vu492idd7yca9tfandj3
~$ 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
+
~/arvados/services/api$ cp -i config/environments/production.rb.example config/environments/production.rb
-
~$ sudo -u postgres createdb arvados_production -T template0 -E UTF8 -O arvados
+
+
-h2. Configure the API server
+h2. Set up configuration files
-First, copy the example configuration file:
+The API server package uses configuration files that you write to @/etc/arvados/api@ and ensures they're consistently deployed. Create this directory and copy the example configuration files to it:
~/arvados/services/api$ cp -i config/application.yml.example config/application.yml
-
~$ 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
+
+
-The API server reads the @config/application.yml@ file, as well as the @config/application.defaults.yml@ file. Values in @config/application.yml@ take precedence over the defaults that are defined in @config/application.defaults.yml@. The @config/application.yml.example@ file is not read by the API server and is provided for installation convenience, only.
+h2. Configure the database connection
-Consult @config/application.default.yml@ for a full list of configuration options. Always put your local configuration in @config/application.yml@, never edit @config/application.default.yml@.
+Edit @/etc/arvados/api/database.yml@ and replace the @xxxxxxxx@ database password placeholders with the PostgreSQL password you generated above.
-h3(#uuid_prefix). uuid_prefix
+h2(#configure_application). Configure the API server
-Define your @uuid_prefix@ in @config/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).
+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.
-h3(#git_repositories_dir). git_repositories_dir
+@config/application.default.yml@ documents additional configuration settings not listed here. You can "view the current source version":https://dev.arvados.org/projects/arvados/repository/revisions/master/entry/services/api/config/application.default.yml for reference.
+
+Only put local configuration in @application.yml@. Do not edit @application.default.yml@.
+
+h3(#uuid_prefix). uuid_prefix
-This field defaults to @/var/lib/arvados/git@. You can override the value by defining it in @config/application.yml@.
+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.
-Make sure a clone of the arvados repository exists in @git_repositories_dir@.
+Example @application.yml@:
~/arvados/services/api$ sudo mkdir -p /var/lib/arvados/git
-~/arvados/services/api$ sudo git clone --bare ../../.git /var/lib/arvados/git/arvados.git
-
uuid_prefix: zzzzz
+
h3. secret_token
-Generate a new secret token for signing cookies:
+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@:
~/arvados/services/api$ rake secret
-zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
+~$ ruby -e 'puts rand(2**400).to_s(36)'
+yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
secret_token: yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
+~$ ruby -e 'puts rand(2**400).to_s(36)'
+xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
blob_signing_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+~/arvados/services/api$ ruby -e 'puts rand(2**128).to_s(36)'
-6gqa1vu492idd7yca9tfandj3
-
~/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
-
sso_app_id: arvados-server
+ sso_app_secret: wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
+ sso_provider_url: https://sso.example.com
+
+
-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.
+h3. workbench_address
-~/arvados/services/api$ cp -i config/database.yml.sample config/database.yml
-~/arvados/services/api$ edit config/database.yml
-
~/arvados/services/api$ RAILS_ENV=production bundle exec rake db:setup
-
workbench_address: https://workbench.zzzzz.example.com
+
-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.
+h3. websocket_address
-~/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
-
ERROR: must be owner of extension plpgsql
websocket_address: wss://ws.zzzzz.example.com/websocket
+
-h2(#omniauth). Set up omniauth
+h3(#git_repositories_dir). git_repositories_dir
-First copy the omniauth configuration file:
+The @git_repositories_dir@ setting specifies the directory where user git repositories will be stored.
+
+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:
~/arvados/services/api$ cp -i config/initializers/omniauth.rb.example config/initializers/omniauth.rb
+~$ 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(#set_up). Set up Web servers
-We recommend "Passenger":https://www.phusionpassenger.com/ to run the API server in production.
+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:
-Point it to the services/api directory in the source tree.
+Install runit to supervise the Puma daemon. {% include 'install_runit' %}
PassengerBufferResponse off
+Install the script below as the run script for the Puma service, modifying it as directed by the comments.
+
+#!/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`"
+
+# Change arguments below to match your deployment, "webserver-user" and
+# "webserver-group" should be changed to the user and group of the web server
+# process. This is typically "www-data:www-data" on Debian systems by default,
+# other systems may use different defaults such the name of the web server
+# software (for example, "nginx:nginx").
+exec chpst -m 1073741824 -u webserver-user:webserver-group -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;
+
+ # This value effectively limits the size of API objects users can
+ # create, especially collections. If you change this, you should
+ # also ensure the following settings match it:
+ # * `client_max_body_size` in the server section below
+ # * `client_max_body_size` in the Workbench Nginx configuration (twice)
+ # * `max_request_size` in the API server's application.yml file
+ client_max_body_size 128m;
+}
+
+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;
+
+ # Refer to the comment about this setting in the server section above.
+ 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
+
+
+
+
+
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' %}