---
layout: default
navsection: installguide
title: Install the API server
...

This installation guide assumes you are on a 64 bit Debian or Ubuntu system.

h2. Install prerequisites

<notextile>
<pre><code>~$ <span class="userinput">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 git wget zlib1g-dev
</span></code></pre></notextile>

Also make sure you have "Ruby and bundler":install-manual-prerequisites-ruby.html installed.

h2. Download the source tree

<notextile>
<pre><code>~$ <span class="userinput">cd $HOME</span> # (or wherever you want to install)
~$ <span class="userinput">git clone https://github.com/curoverse/arvados.git</span>
</code></pre></notextile>

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

<notextile>
<pre><code>~$ <span class="userinput">cd arvados/services/api</span>
~/arvados/services/api$ <span class="userinput">bundle install</span>
</code></pre></notextile>

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@:

<notextile>
<pre><code>~/arvados/services/api$ <span class="userinput">cp -i config/environments/production.rb.example config/environments/production.rb</span>
</code></pre></notextile>

h2. Configure the API server

First, copy the example configuration file:

<notextile>
<pre><code>~/arvados/services/api$ <span class="userinput">cp -i config/application.yml.example config/application.yml</span>
</code></pre></notextile>

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@.

h3(#uuid_prefix). uuid_prefix

Define your @uuid_prefix@ in @config/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@.

Make sure a clone of the arvados repository exists in @git_repositories_dir@.

<notextile>
<pre><code>~/arvados/services/api$ <span class="userinput">sudo mkdir -p /var/lib/arvados/git</span>
~/arvados/services/api$ <span class="userinput">sudo git clone --bare ../../.git /var/lib/arvados/git/arvados.git</span>
</code></pre></notextile>

h3. secret_token

Generate a new secret token for signing cookies:

<notextile>
<pre><code>~/arvados/services/api$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
</code></pre></notextile>

Then put that value in the @secret_token@ field.

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

&nbsp;&nbsp;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@.

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:

<notextile>
<pre><code>~/arvados/services/api$ <span class="userinput">ruby -e 'puts rand(2**128).to_s(36)'</span>
6gqa1vu492idd7yca9tfandj3
</code></pre></notextile>

Create a new database user with permission to create its own databases.

<notextile>
<pre><code>~/arvados/services/api$ <span class="userinput">sudo -u postgres createuser --createdb --encrypted -R -S --pwprompt arvados</span>
[sudo] password for <b>you</b>: <span class="userinput">yourpassword</span>
Enter password for new role: <span class="userinput">paste-password-you-generated</span>
Enter it again: <span class="userinput">paste-password-again</span>
</code></pre></notextile>

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.

<notextile>
<pre><code>~/arvados/services/api$ <span class="userinput">cp -i config/database.yml.sample config/database.yml</span>
~/arvados/services/api$ <span class="userinput">edit config/database.yml</span>
</code></pre></notextile>

Create and initialize the database. If you are planning a production system, choose the @production@ rails environment, otherwise use @development@.

<notextile>
<pre><code>~/arvados/services/api$ <span class="userinput">RAILS_ENV=production bundle exec rake db:setup</span>
</code></pre></notextile>

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.

<notextile>
<pre><code>~/arvados/services/api$ <span class="userinput">su postgres createdb arvados_production -E UTF8 -O arvados</span>
~/arvados/services/api$ <span class="userinput">RAILS_ENV=production bundle exec rake db:structure:load</span>
~/arvados/services/api$ <span class="userinput">RAILS_ENV=production bundle exec rake db:seed</span>
</code></pre></notextile>

{% include 'notebox_begin' %}
You can safely ignore the following error message you may see when loading the database structure:
<notextile>
<pre><code>ERROR:  must be owner of extension plpgsql</code></pre></notextile>
{% include 'notebox_end' %}

h2(#omniauth). Set up omniauth

First copy the omniauth configuration file:

<notextile>
<pre><code>~/arvados/services/api$ <span class="userinput">cp -i config/initializers/omniauth.rb.example config/initializers/omniauth.rb
</code></pre></notextile>

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.

<notextile>
<pre><code>APP_ID = 'arvados-server'
APP_SECRET = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
CUSTOM_PROVIDER_URL = 'https://sso.example.com/'
</code></pre>
</notextile>

h2. Start the API server

h3. Development environment

If you plan to run in development mode, you can now run the development server this way:

<notextile>
<pre><code>~/arvados/services/api$ <span class="userinput">bundle exec rails server --port=3030
</code></pre></notextile>

h3. Production environment

We recommend "Passenger":https://www.phusionpassenger.com/ to run the API server in production.

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:

<notextile>
<pre><code><span class="userinput">PassengerBufferResponse off</span>
</code></pre>
</notextile>