X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/27b534ddd7d2b56ff63cd2ca100fa3119df51a2f..2b41829bf0a889558c320121710ef3fd2e90ef7e:/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 f29b2cf1d1..77a90e0f52 100644
--- a/doc/install/install-api-server.html.textile.liquid
+++ b/doc/install/install-api-server.html.textile.liquid
@@ -4,72 +4,105 @@ 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 libpq-dev libcurl4-openssl-dev postgresql git nginx arvados-api-server
+
+
+
+On a Red Hat-based system, install the following packages:
-See also: "Downloading the source code":https://arvados.org/projects/arvados/wiki/Download on the Arvados wiki.
+~$ sudo yum install bison make automake gcc gcc-c++ libcurl-devel postgresql-server postgresql-devel nginx 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/initializers/omniauth.rb.example /etc/arvados/api/omniauth.rb
+/var/www/arvados-api/current$ sudo cp config/database.yml.sample /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.
+
+h2. 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.
+
+Always put your local configuration in @application.yml@ instead of editing @application.default.yml@.
h3(#uuid_prefix). uuid_prefix
-It is recommended to explicitly define your @uuid_prefix@ in @config/application.yml@, by setting the 'uuid_prefix' field in the section for your environment.
+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).
h3(#git_repositories_dir). git_repositories_dir
-This field defaults to @/var/lib/arvados/git@. You can override the value by defining it in @config/application.yml@.
+This field defaults to @/var/lib/arvados/git@. You can override the value by defining it in @application.yml@.
Make sure a clone of the arvados repository exists in @git_repositories_dir@.
~/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 /var/lib/arvados/git
+~$ sudo git clone --bare git://git.curoverse.com/arvados.git /var/lib/arvados/git/arvados.git
~/arvados/services/api$ rake secret
+~$ ruby -e 'puts rand(2**400).to_s(36)'
zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
~/arvados/services/api$ ruby -e 'puts rand(2**128).to_s(36)'
-6gqa1vu492idd7yca9tfandj3
-
sso_app_id: arvados-server
+ sso_app_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+ sso_provider_url: https://sso.example.com
+
+
-Create a new database user with permission to create its own databases.
+h3. Other options
-~/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
-
~/arvados/services/api$ cp -i config/database.yml.sample config/database.yml
-~/arvados/services/api$ edit config/database.yml
-
ERROR: must be owner of extension plpgsql
+{% include 'notebox_end' %}
-Create and initialize the database. If you are planning a production system, choose the @production@ rails environment, otherwise use @development@.
+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.
-~/arvados/services/api$ RAILS_ENV=production bundle exec rake db:setup
-
~/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
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:
-First copy the omniauth configuration file: +#!/bin/bash
-
-~/arvados/services/api$ cp -i config/initializers/omniauth.rb.example config/initializers/omniauth.rb
-
+set -e
+# Uncomment the line below if you're using RVM.
+#source /etc/profile.d/rvm.sh
-Edit @config/initializers/omniauth.rb@, and tell your api server to use the Curoverse SSO server for authentication. Use the @APP_SECRET@ specified in the snippet below.
+envdir="/etc/sv/puma/env"
+root=/etc/sv/puma
+echo "Starting puma from ${root}"
+cd $root
+mkdir -p "${envdir}"
+exec 2>&1
+cd /var/www/arvados-api/current
+# You may need to change arguments below to match your deployment, especially -u.
+exec chpst -e "${envdir}" -m 1073741824 -u www-data:www-data bundle exec puma -t 0:512 -e production -b tcp://127.0.0.1:8100
+
+APP_ID = 'local_docker_installation'
-APP_SECRET = 'yohbai4eecohshoo1Yoot7tea9zoca9Eiz3Tajahweo9eePaeshaegh9meiye2ph'
-CUSTOM_PROVIDER_URL = 'https://auth.curoverse.com'
-
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:
-You can also run your own SSO server. However, the SSO server codebase currently uses OpenID 2.0 to talk to Google's authentication service. Google has deprecated that protocol. This means that new clients will not be allowed to talk to Google's authentication services anymore over OpenID 2.0, and they will phase out the use of OpenID 2.0 completely in the coming monts. We are working on upgrading the SSO server codebase to a newer protocol. That work should be complete by the end of November 2014. In the mean time, anyone is free to use the existing Curoverse SSO server for any local Arvados installation.
-server {
+ listen 127.0.0.1:8000;
+ server_name localhost-api;
-h2. Start the API server
+ root /var/www/arvados-api/current/public;
+ index index.html index.htm index.php;
-h3. Development environment
+ passenger_enabled on;
+ # If you're using RVM, uncomment the line below.
+ #passenger_ruby /usr/local/rvm/wrappers/default/ruby;
+}
-If you plan to run in development mode, you can now run the development server this way:
+upstream api {
+ server 127.0.0.1:8000 fail_timeout=10s;
+}
-
-~/arvados/services/api$ bundle exec rails server --port=3030
-
+upstream websockets {
+ # The address below must match the one specified in puma's -b option.
+ server 127.0.0.1:8100 fail_timeout=10s;
+}
-h3. Production environment
+proxy_http_version 1.1;
-We recommend "Passenger":https://www.phusionpassenger.com/ to run the API server in production.
+server {
+ listen [your public IP address]:443 ssl;
+ server_name uuid-prefix.your.domain;
-Point it to the services/api directory in the source tree.
+ ssl on;
-To enable streaming so users can monitor crunch jobs in real time, make sure to add the following to your Passenger configuration:
+ index index.html index.htm index.php;
-
-PassengerBufferResponse off
+ location / {
+ proxy_pass http://api;
+ proxy_redirect off;
+
+ 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;
+
+ index index.html index.htm index.php;
+
+ location / {
+ proxy_pass http://websockets;
+ proxy_redirect off;
+
+ 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;
+ }
+}
+