X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/51a7226a1cf217fe4ea41f6d1b111b55d396485d..0662b235357dd40b5d27efd06b60044ddcec06f6:/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 3846e3c9aa..69ff768ee1 100644
--- a/doc/install/install-api-server.html.textile.liquid
+++ b/doc/install/install-api-server.html.textile.liquid
@@ -12,31 +12,28 @@ h3(#install_ruby_and_bundler). Install Ruby and Bundler
{% include 'install_ruby_and_bundler' %}
-h3(#install_postgres). Install Postgres
+h3(#install_postgres). Install PostgreSQL
{% include 'install_postgres' %}
-h3(#build_tools_apiserver). Build tools
-
-* Build tools and the curl and PostgreSQL development libraries, to build gem dependencies
-* Nginx
-
-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 libpq-dev libcurl4-openssl-dev postgresql git nginx arvados-api-server
+
~$ sudo apt-get install bison build-essential libcurl4-openssl-dev git arvados-api-server
~$ sudo yum install bison make automake gcc gcc-c++ libcurl-devel postgresql-server postgresql-devel nginx git arvados-api-server
+
~$ sudo yum install bison make automake gcc gcc-c++ libcurl-devel git arvados-api-server
~$ 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
@@ -85,77 +82,272 @@ 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@ 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.
+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.
-Always put your local configuration in @application.yml@ instead of editing @application.default.yml@.
+@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
-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@:
-This field defaults to @/var/lib/arvados/git@. You can override the value by defining it in @application.yml@.
+ uuid_prefix: zzzzz
+~$ sudo mkdir -p /var/lib/arvados/git
-~$ sudo git clone --bare git://git.curoverse.com/arvados.git /var/lib/arvados/git/arvados.git
+~$ ruby -e 'puts rand(2**400).to_s(36)'
+yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
secret_token: yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
+~$ ruby -e 'puts rand(2**400).to_s(36)'
-zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
+xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
blob_signing_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+ sso_app_id: arvados-server
+ sso_app_secret: wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
+ sso_provider_url: https://sso.example.com
+
+ workbench_address: https://workbench.zzzzz.example.com
+ websocket_address: wss://ws.zzzzz.example.com/websocket
+~$ sudo mkdir -p /var/lib/arvados/git/repositories
+
sso_app_id: arvados-server
- sso_app_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
- sso_provider_url: https://sso.example.com
+ git_repositories_dir: /var/lib/arvados/git/repositories
git_internal_dir: /var/lib/arvados/internal.git
+
+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`"
+
+# 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
+
+
+ERROR: must be owner of extension plpgsql
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 Web servers - -{% include 'install_nginx_apiserver' %}