X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/cbfc8eea7f3fc96f478530c77441b7175a043a17..dc94a5b530afe42b7060d0188d04423a7cf7a205:/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 ccfc58ecf4..c3d5200b16 100644
--- a/doc/install/install-api-server.html.textile.liquid
+++ b/doc/install/install-api-server.html.textile.liquid
@@ -4,21 +4,29 @@ navsection: installguide
title: Install the API server
...
-h2. Prerequisites:
+This installation guide assumes you are on a 64 bit Debian or Ubuntu system.
-# A GNU/Linux (virtual) machine
-# A domain name for your api server
-# Ruby >= 2.0.0
-# Bundler: @gem install bundler@
-# Curl libraries: @sudo apt-get install libcurl3 libcurl3-gnutls libcurl4-openssl-dev@
+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
+
+
+Also make sure you have "Ruby and bundler":install-manual-prerequisites-ruby.html installed.
h2. Download the source tree
-~$ git clone https://github.com/curoverse/arvados.git
+~$ cd $HOME # (or wherever you want to install)
+~$ git clone https://github.com/curoverse/arvados.git
-See also: "Downloading the source code:https://arvados.org/projects/arvados/wiki/Download on the Arvados wiki.
+See also: "Downloading the source code":https://arvados.org/projects/arvados/wiki/Download on the Arvados wiki.
+
+The API server is in @services/api@ in the source tree.
h2. Install gem dependencies
@@ -27,102 +35,151 @@ h2. Install gem dependencies
~/arvados/services/api$ bundle install
+h2. Choose your environment
+
+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.
+
+Copy the example environment file for your environment. For example, if you choose @production@:
+
+
+~/arvados/services/api$ cp -i config/environments/production.rb.example config/environments/production.rb
+
+
h2. Configure the API server
-Edit the main configuration:
+First, copy the example configuration file:
~/arvados/services/api$ cp -i config/application.yml.example config/application.yml
-Choose a unique 5-character alphanumeric string to use as your @uuid_prefix@. An example is given that generates a 5-character string based on a hash of your hostname. The @uuid_prefix@ is a unique identifier for your API server. It also serves as the first part of the hostname for your API server.
+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.
+
+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@.
-For a development site, use your own domain instead of arvadosapi.com.
+h3(#uuid_prefix). uuid_prefix
-Make sure a clone of the arvados repository exists in @git_repositories_dir@:
+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.
+
+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@.
+
+Make sure a clone of the arvados repository exists in @git_repositories_dir@.
-~/arvados/services/api$ sudo mkdir -p /var/cache/git
-~/arvados/services/api$ sudo git clone --bare ../../.git /var/cache/git/arvados.git
+~/arvados/services/api$ sudo mkdir -p /var/lib/arvados/git
+~/arvados/services/api$ sudo git clone --bare ../../.git /var/lib/arvados/git/arvados.git
+h3. secret_token
+
Generate a new secret token for signing cookies:
-~/arvados/services/api$ rake secret
+~/arvados/services/api$ rake secret
zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
-Put it in @config/application.yml@ in the production or common section:
+Then put that value in the @secret_token@ field.
-
- secret_token: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
-
-
+h3. blob_signing_key
+
+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).
+
+h3. workbench_address
+
+Fill in the url of your workbench application in @workbench_address@, for example
+
+ https://workbench.@prefix_uuid@.your.domain
+
+h3. other options
Consult @application.default.yml@ for a full list of configuration options. Always put your local configuration in @application.yml@ instead of editing @application.default.yml@.
-Configure the database:
+h2. Set up the database
+
+Generate a new database password. Nobody ever needs to memorize it or type it, so we'll make a strong one:
-~/arvados/services/api$ cp -i config/database.yml.sample config/database.yml
+~/arvados/services/api$ ruby -e 'puts rand(2**128).to_s(36)'
+6gqa1vu492idd7yca9tfandj3
-By default, the development database will use the sqlite3 driver, so no configuration is necessary. If you wish to use mysql or postgres, edit @config/database.yml@ to your liking and make sure the database and db user exist. Then initialize the database:
+Create a new database user with permission to create its own databases.
-~/arvados/services/api$ RAILS_ENV=development bundle exec rake db:setup
+~/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
-Set up omniauth:
+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.
-~/arvados/services/api$ cp -i config/initializers/omniauth.rb.example config/initializers/omniauth.rb
+~/arvados/services/api$ cp -i config/database.yml.sample config/database.yml
+~/arvados/services/api$ edit config/database.yml
-Edit @config/initializers/omniauth.rb@. Set @APP_SECRET@ to the value of @app_secret@ from "installing the single sign on server":install-sso.html .
+Create and initialize the database. If you are planning a production system, choose the @production@ rails environment, otherwise use @development@.
-You can now run the development server:
+
+~/arvados/services/api$ RAILS_ENV=production bundle exec rake db:setup
+
+
+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.
-~/arvados/services/api$ rails server
+~/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
-h3. Apache/Passenger (optional)
+{% 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
+{% include 'notebox_end' %}
-You can use "Passenger":https://www.phusionpassenger.com/ for deployment. Point it to the services/api directory in the source tree.
+h2(#omniauth). Set up omniauth
-To enable streaming so users can monitor crunch jobs in real time, add to your Passenger configuration in Apache:
+First copy the omniauth configuration file:
-PassengerBufferResponse off
+~/arvados/services/api$ cp -i config/initializers/omniauth.rb.example config/initializers/omniauth.rb
+
+
+Edit @config/initializers/omniauth.rb@ to configure the SSO server for authentication. @APP_ID@ and @APP_SECRET@ correspond to the @app_id@ and @app_secret@ set in "Create arvados-server client for Single Sign On (SSO)":install-sso.html#client and @CUSTOM_PROVIDER_URL@ is the address of your SSO server.
+
+
+APP_ID = 'arvados-server'
+APP_SECRET = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+CUSTOM_PROVIDER_URL = 'https://sso.example.com/'
-h2. Add an admin user
+h2. Start the API server
-Point browser to the API endpoint. Log in with a google account.
+h3. Development environment
-In the rails console:
+If you plan to run in development mode, you can now run the development server this way:
-~/arvados/services/api$ rails console
-irb(main):001:0> Thread.current[:user] = User.find(1)
-irb(main):002:0> Thread.current[:user].is_admin = true
-irb(main):003:0> User.find(1).update_attributes is_admin: true, is_active: true
-irb(main):004:0> User.find(1).is_admin
-=> true
+~/arvados/services/api$ bundle exec rails server --port=3030
-h2. Create an API token
+h3. Production environment
+
+We recommend "Passenger":https://www.phusionpassenger.com/ to run the API server in production.
-In rails console:
+Point it to the services/api directory in the source tree.
+
+To enable streaming so users can monitor crunch jobs in real time, make sure to add the following to your Passenger configuration:
-~/arvados/services/api$ rails console
-irb(main):001:0> a = ApiClient.new(owner_uuid:'0')
-irb(main):002:0> a.save!
-irb(main):003:0> x = ApiClientAuthorization.new(api_client_id:a.id, user_id:1)
-irb(main):004:0> x.save
-irb(main):005:0> x.api_token
-
+PassengerBufferResponse off
+
+