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/api/application.yml@ to configure the settings described in the following sections. 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.
50 @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.
52 Only put local configuration in @application.yml@. Do not edit @application.default.yml@.
54 h3(#uuid_prefix). uuid_prefix
56 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.
58 Example @application.yml@:
61 <pre><code> uuid_prefix: <span class="userinput">zzzzz</span></code></pre>
66 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@:
69 <pre><code>~$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
70 yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
71 </code></pre></notextile>
73 Example @application.yml@:
76 <pre><code> secret_token: <span class="userinput">yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy</span></code></pre>
79 h3(#blob_signing_key). blob_signing_key
81 The @blob_signing_key@ 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@:
84 <pre><code>~$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
85 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
86 </code></pre></notextile>
88 Example @application.yml@:
91 <pre><code> blob_signing_key: <span class="userinput">xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</span></code></pre>
94 h3(#omniauth). sso_app_secret, sso_app_id, sso_provider_url
96 The following settings enable the API server to communicate with the "Single Sign On (SSO) server":install-sso.html to authenticate user log in.
98 Set @sso_provider_url@ 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.
100 Set @sso_app_secret@ and @sso_app_id@ to the corresponding values for @app_secret@ and @app_id@ used in the "Create arvados-server client for Single Sign On (SSO)":install-sso.html#client step.
102 Example @application.yml@:
105 <pre><code> sso_app_id: <span class="userinput">arvados-server</span>
106 sso_app_secret: <span class="userinput">wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww</span>
107 sso_provider_url: <span class="userinput">https://sso.example.com</span>
111 h3. workbench_address
113 Set @workbench_address@ to the URL of your workbench application after following "Install Workbench.":install-workbench-app.html
115 Example @application.yml@:
118 <pre><code> workbench_address: <span class="userinput">https://workbench.zzzzz.example.com</span></code></pre>
121 h3. websocket_address
123 Set @websocket_address@ to the @wss://@ URL of the API server websocket endpoint after following "Set up Web servers":#set_up. The path of the default endpoint is @/websocket@.
125 Example @application.yml@:
128 <pre><code> websocket_address: <span class="userinput">wss://ws.zzzzz.example.com</span>/websocket</code></pre>
131 h3(#git_repositories_dir). git_repositories_dir
133 The @git_repositories_dir@ setting specifies the directory where user git repositories will be stored.
135 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:
138 <pre><code>~$ <span class="userinput">sudo mkdir -p /var/lib/arvados/git/repositories</span>
139 </code></pre></notextile>
141 If you intend to store your git repositories in a different location, specify that location in @application.yml@.
143 Default setting in @application.default.yml@:
146 <pre><code> git_repositories_dir: <span class="userinput">/var/lib/arvados/git/repositories</span>
150 h3(#git_internal_dir). git_internal_dir
152 The @git_internal_dir@ 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 @git_repositories_dir@.
154 Example @application.yml@:
157 <pre><code> git_internal_dir: <span class="userinput">/var/lib/arvados/internal.git</span>
161 h3(#disable_api_methods). disable_api_methods
163 Set the @disable_api_methods@ configuration option to disable the deprecated @jobs@ API. This will prevent users from accidentally submitting jobs that won't run. "All new installations should use the containers API.":crunch2-slurm/install-prerequisites.html
169 - pipeline_instances.create
170 - pipeline_templates.create
172 - pipeline_instances.get
173 - pipeline_templates.get
175 - pipeline_instances.list
176 - pipeline_templates.list
178 - pipeline_instances.index
179 - pipeline_templates.index
181 - pipeline_instances.update
182 - pipeline_templates.update
191 - pipeline_instances.show
192 - pipeline_templates.show
197 h2(#set_up). Set up Nginx and Passenger
199 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.
201 First, "Install Nginx and Phusion Passenger":https://www.phusionpassenger.com/library/walkthroughs/deploy/ruby/ownserver/nginx/oss/install_passenger_main.html.
203 Edit the http section of your Nginx configuration to run the Passenger server, and serve SSL requests. Add a block like the following, adding SSL and logging parameters to taste:
207 listen 127.0.0.1:8000;
208 server_name localhost-api;
210 root /var/www/arvados-api/current/public;
211 index index.html index.htm index.php;
213 passenger_enabled on;
214 # If you're using RVM, uncomment the line below.
215 #passenger_ruby /usr/local/rvm/wrappers/default/ruby;
217 # This value effectively limits the size of API objects users can
218 # create, especially collections. If you change this, you should
219 # also ensure the following settings match it:
220 # * `client_max_body_size` in the server section below
221 # * `client_max_body_size` in the Workbench Nginx configuration (twice)
222 # * `max_request_size` in the API server's application.yml file
223 client_max_body_size 128m;
227 server 127.0.0.1:8000 fail_timeout=10s;
230 proxy_http_version 1.1;
232 # When Keep clients request a list of Keep services from the API server, the
233 # server will automatically return the list of available proxies if
234 # the request headers include X-External-Client: 1. Following the example
235 # here, at the end of this section, add a line for each netmask that has
236 # direct access to Keep storage daemons to set this header value to 0.
237 geo $external_client {
239 <span class="userinput">10.20.30.0/24</span> 0;
243 listen <span class="userinput">[your public IP address]</span>:443 ssl;
244 server_name <span class="userinput">uuid_prefix.your.domain</span>;
247 ssl_certificate <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
248 ssl_certificate_key <span class="userinput">/YOUR/PATH/TO/cert.key</span>;
250 index index.html index.htm index.php;
252 # Refer to the comment about this setting in the server section above.
253 client_max_body_size 128m;
256 proxy_pass http://api;
258 proxy_connect_timeout 90s;
259 proxy_read_timeout 300s;
261 proxy_set_header X-Forwarded-Proto https;
262 proxy_set_header Host $http_host;
263 proxy_set_header X-External-Client $external_client;
264 proxy_set_header X-Real-IP $remote_addr;
265 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
271 Restart Nginx to apply the new configuration.
274 <pre><code>~$ <span class="userinput">sudo nginx -s reload</span>
278 h2. Prepare the API server deployment
280 {% assign railspkg = "arvados-api-server" %}
281 {% include 'install_rails_reconfigure' %}
283 {% include 'notebox_begin' %}
284 You can safely ignore the following messages if they appear while this command runs:
286 <notextile><pre>Don't run Bundler as root. Bundler can ask for sudo if it is needed, and installing your bundle as root will
287 break this application for all non-root users on this machine.</pre></notextile>
289 <notextile><pre>fatal: Not a git repository (or any of the parent directories): .git</pre></notextile>
290 {% include 'notebox_end' %}