[arvados.git] / doc / install / install-api-server.html.textile.liquid

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

h2. Prerequisites:

# A GNU/Linux (virtual) machine
# A domain name for your api server

h2(#dependencies). Install dependencies

<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 \
    libsqlite3-dev libssl-dev libxslt1.1 postgresql sqlite3 sudo \
    wget zlib1g-dev
</span></code></pre></notextile>

h2(#ruby). Install Ruby and bundler

We recommend Ruby >= 2.1.

<notextile>
<pre><code><span class="userinput">mkdir -p ~/src
cd ~/src
wget http://cache.ruby-lang.org/pub/ruby/2.1/ruby-2.1.2.tar.gz
tar xzf ruby-2.1.2.tar.gz
cd ruby-2.1.2
./configure
make
sudo make install

sudo gem install bundler</span>
</code></pre></notextile>

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.

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. Configure the API server

Edit the main configuration:

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

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.

For a development site, use your own domain instead of arvadosapi.com.

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/cache/git</span>
~/arvados/services/api$ <span class="userinput">sudo git clone --bare ../../.git /var/cache/git/arvados.git</span>
</code></pre></notextile>

Generate a new secret token for signing cookies:

<notextile>
<pre><code>~/arvados/services/api$ <span class="userinput">rake secret</span>
zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
</code></pre></notextile>

If you want access control on your Keep server(s), you should set @blob_signing_key@ to the same value as the permission key you provided to your "Keep server(s)":install-keep.html.

Put it in @config/application.yml@ in the production or common section:

<notextile>
<pre><code><span class="userinput">    secret_token: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz</span>
</code></pre>
</notextile>

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

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 --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>
Shall the new role be a superuser? (y/n) <span class="userinput">n</span>
Shall the new role be allowed to create more new roles? (y/n) <span class="userinput">n</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.

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

Set up omniauth:

<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@, and tell your api server to use the Curoverse SSO server for authentication:

<notextile>
<pre><code>APP_ID = 'local_docker_installation'
APP_SECRET = 'yohbai4eecohshoo1Yoot7tea9zoca9Eiz3Tajahweo9eePaeshaegh9meiye2ph'
CUSTOM_PROVIDER_URL = 'https://auth.curoverse.com'
</code></pre></notextile>
</pre>

<div class="alert alert-block alert-info">
  <button type="button" class="close" data-dismiss="alert">&times;</button>
  <h4>Note!</h4>
  <p>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 <a href="https://developers.google.com/accounts/docs/OpenID2">has deprecated that protocol</a>. 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.</p>
</div>

You can now run the development server:

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

h3. Apache/Passenger (optional)

You can use "Passenger":https://www.phusionpassenger.com/ for deployment. Point it to the services/api directory in the source tree.

To enable streaming so users can monitor crunch jobs in real time, add to your Passenger configuration in Apache:

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

h2(#admin-user). Add an admin user

Point your browser to the API server's login endpoint:

<notextile>
<pre><code><span class="userinput">https://localhost:3030/login</span>
</code></pre>
</notextile>

Log in with your google account.

Use the rails console to give yourself admin privileges:

<notextile>
<pre><code>~/arvados/services/api$ <span class="userinput">bundle exec rails console</span>
irb(main):001:0&gt; <span class="userinput">Thread.current[:user] = User.all.select(&:identity_url).last</span>
irb(main):002:0&gt; <span class="userinput">Thread.current[:user].is_admin = true</span>
irb(main):003:0&gt; <span class="userinput">Thread.current[:user].update_attributes is_admin: true, is_active: true</span>
irb(main):004:0&gt; <span class="userinput">User.where(is_admin: true).collect &:email</span>
=&gt; ["root", "<b>your_address@example.com</b>"]
</code></pre></notextile>