3 navsection: installguide
4 title: Install the API server
7 Copyright (C) The Arvados Authors. All rights reserved.
9 SPDX-License-Identifier: CC-BY-SA-3.0
12 h2. Install prerequisites
14 The Arvados package repository includes an API server package that can help automate much of the deployment.
16 h3(#install_ruby_and_bundler). Install Ruby and Bundler
18 {% include 'install_ruby_and_bundler' %}
20 h2(#install_apiserver). Install API server and dependencies
22 On a Debian-based system, install the following packages:
25 <pre><code>~$ <span class="userinput">sudo apt-get install bison build-essential libcurl4-openssl-dev git arvados-api-server</span>
29 On a Red Hat-based system, install the following packages:
32 <pre><code>~$ <span class="userinput">sudo yum install bison make automake gcc gcc-c++ libcurl-devel git arvados-api-server</span>
36 {% include 'install_git' %}
38 h2(#configure). Set up the database
40 Configure the API server to connect to your database by updating @/etc/arvados/api/database.yml@. Replace the @xxxxxxxx@ database password placeholder with the "password you generated during database setup":install-postgresql.html#api. Be sure to update the @production@ section.
43 <pre><code>~$ <span class="userinput">editor /etc/arvados/api/database.yml</span>
44 </code></pre></notextile>
46 h2(#configure_application). Configure the API server
48 Edit @/etc/arvados/config.yml@ to set the keys below. Only the most important configuration options are listed here. The full set of configuration options are listed in "config.yml":{{site.baseurl}}/admin/config.html
50 h3(#uuid_prefix). ClusterID
52 The @ClusterID@ is used for all database identifiers to identify the record as originating from this site. It is the first key under @Clusters@ in @config.yml@. It must be exactly 5 lowercase ASCII letters and digits.
56 <span class="userinput">zzzzz</span>:
60 h3. API.RailsSessionSecretToken
62 The @API.RailsSessionSecretToken@ 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 @config.yml@:
65 <pre><code>~$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
66 yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
67 </code></pre></notextile>
75 RailsSessionSecretToken: <span class="userinput">yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy</span></code></pre>
78 h3(#blob_signing_key). Collections.BlobSigningKey
80 The @Collections.BlobSigningKey@ 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@:
83 <pre><code>~$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
84 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
85 </code></pre></notextile>
93 BlobSigningKey: <span class="userinput">yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy</span></code></pre>
96 h3(#omniauth). Login.ProviderAppID, Login.ProviderAppSecret, Services.SSO.ExternalURL
98 The following settings enable the API server to communicate with the "Single Sign On (SSO) server":install-sso.html to authenticate user log in.
100 Set @Services.SSO.ExternalURL@ 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.
102 Set @Login.ProviderAppID@ and @Login.ProviderAppSecret@ to the corresponding values for @app_id@ and @app_secret@ used in the "Create arvados-server client for Single Sign On (SSO)":install-sso.html#client step.
104 Example @config.yml@:
111 ExternalURL: <span class="userinput">https://sso.example.com</span>
113 ProviderAppID: <span class="userinput">arvados-server</span>
114 ProviderAppSecret: <span class="userinput">wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww</span></code></pre>
117 h3. Services.Workbench1.ExternalURL
119 Set @Services.Workbench1.ExternalURL@ to the URL of your workbench application after following "Install Workbench.":install-workbench-app.html
121 Example @config.yml@:
128 ExternalURL: <span class="userinput">https://workbench.zzzzz.example.com</span></code></pre>
131 h3. Services.Websocket.ExternalURL
133 Set @Services.Websocket.ExternalURL@ to the @wss://@ URL of the API server websocket endpoint after following "Install the websocket server":install-ws.html .
135 Example @config.yml@:
142 ExternalURL: <span class="userinput">wss://ws.zzzzz.example.com</span></code></pre>
145 h3(#git_repositories_dir). Git.Repositories
147 The @Git.Repositories@ setting specifies the directory where user git repositories will be stored.
149 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:
152 <pre><code>~$ <span class="userinput">sudo mkdir -p /var/lib/arvados/git/repositories</span>
153 </code></pre></notextile>
155 If you intend to store your git repositories in a different location, specify that location in @config.yml@. Example:
161 Repositories: <span class="userinput">/var/lib/arvados/git/repositories</span></code></pre>
164 h3(#enable_legacy_jobs_api). Containers.JobsAPI.Enable
166 Enable the legacy "Jobs API":install-crunch-dispatch.html . Note: new installations should use the "Containers API":crunch2-slurm/install-prerequisites.html
168 Disabling the jobs API means methods involving @jobs@, @job_tasks@, @pipeline_templates@ and @pipeline_instances@ are disabled. This functionality is superceded by the containers API which consists of @container_requests@, @containers@ and @workflows@. Arvados clients (such as @arvados-cwl-runner@) detect which APIs are available and adjust behavior accordingly.
170 * 'auto' -- (default) enable the Jobs API only if it has been used before (i.e., there are job records in the database), otherwise disable jobs API .
171 * 'true' -- enable the Jobs API even if there are no existing job records.
172 * 'false' -- disable the Jobs API even in the presence of existing job records.
179 Enable: <span class="userinput">'auto'</span></code></pre>
182 h4(#git_internal_dir). Containers.JobsAPI.GitInternalDir
184 Only required if the legacy "Jobs API" is enabled, otherwise you should skip this.
186 The @Containers.JobsAPI.GitInternalDir@ setting specifies the location of Arvados' internal git repository. By default this is @/var/lib/arvados/internal.git@. This repository stores git commits that have been used to run Crunch jobs. It should _not_ be a subdirectory of the directory in @Git.Repositories@.
188 Example @config.yml@:
195 GitInternalDir: <span class="userinput">/var/lib/arvados/internal.git</span></code></pre>
198 h2(#set_up). Set up Nginx and Passenger
200 The Nginx server will serve API requests using Passenger. It will also be used to proxy SSL requests to other services which are covered later in this guide.
202 First, "Install Nginx and Phusion Passenger":https://www.phusionpassenger.com/library/walkthroughs/deploy/ruby/ownserver/nginx/oss/install_passenger_main.html.
204 Edit the http section of your Nginx configuration to run the Passenger server. Add a block like the following, adding SSL and logging parameters to taste:
209 listen 127.0.0.1:8000;
210 server_name localhost-api;
212 root /var/www/arvados-api/current/public;
213 index index.html index.htm index.php;
215 passenger_enabled on;
216 # If you're using RVM, uncomment the line below.
217 #passenger_ruby /usr/local/rvm/wrappers/default/ruby;
219 # This value effectively limits the size of API objects users can
220 # create, especially collections. If you change this, you should
221 # also ensure the following settings match it:
222 # * `client_max_body_size` in the server section below
223 # * `client_max_body_size` in the Workbench Nginx configuration (twice)
224 # * `API.MaxRequestSize` in config.yml
225 client_max_body_size 128m;
229 server 127.0.0.1:8000 fail_timeout=10s;
232 proxy_http_version 1.1;
234 # When Keep clients request a list of Keep services from the API server, the
235 # server will automatically return the list of available proxies if
236 # the request headers include X-External-Client: 1. Following the example
237 # here, at the end of this section, add a line for each netmask that has
238 # direct access to Keep storage daemons to set this header value to 0.
239 geo $external_client {
241 <span class="userinput">10.20.30.0/24</span> 0;
246 Restart Nginx to apply the new configuration.
249 <pre><code>~$ <span class="userinput">sudo nginx -s reload</span>
253 h2. Prepare the API server deployment
255 {% assign railspkg = "arvados-api-server" %}
256 {% include 'install_rails_reconfigure' %}
258 {% include 'notebox_begin' %}
259 You can safely ignore the following messages if they appear while this command runs:
261 <notextile><pre>Don't run Bundler as root. Bundler can ask for sudo if it is needed, and installing your bundle as root will
262 break this application for all non-root users on this machine.</pre></notextile>
264 <notextile><pre>fatal: Not a git repository (or any of the parent directories): .git</pre></notextile>
265 {% include 'notebox_end' %}