doc/install/install-api-server.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Install the API server
   5 ...
   6
   7 This installation guide assumes you are on a 64 bit Debian or Ubuntu system.
   8
   9 h2. Install prerequisites
  10
  11 <notextile>
  12 <pre><code>~$ <span class="userinput">sudo apt-get install \
  13     bison build-essential gettext libcurl3 libcurl3-gnutls \
  14     libcurl4-openssl-dev libpcre3-dev libpq-dev libreadline-dev \
  15     libssl-dev libxslt1.1 postgresql sudo wget zlib1g-dev
  16 </span></code></pre></notextile>
  17
  18 Also make sure you have "Ruby and bundler":install-manual-prerequisites-ruby.html installed.
  19
  20 h2. Download the source tree
  21
  22 <notextile>
  23 <pre><code>~$ <span class="userinput">cd $HOME</span> # (or wherever you want to install)
  24 ~$ <span class="userinput">git clone https://github.com/curoverse/arvados.git</span>
  25 </code></pre></notextile>
  26
  27 See also: "Downloading the source code":https://arvados.org/projects/arvados/wiki/Download on the Arvados wiki.
  28
  29 The API server is in @services/api@ in the source tree.
  30
  31 h2. Install gem dependencies
  32
  33 <notextile>
  34 <pre><code>~$ <span class="userinput">cd arvados/services/api</span>
  35 ~/arvados/services/api$ <span class="userinput">bundle install</span>
  36 </code></pre></notextile>
  37
  38 h2. Choose your environment
  39
  40 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.
  41
  42 Copy the example environment file for your environment. For example, if you choose @production@:
  43
  44 <notextile>
  45 <pre><code>~/arvados/services/api$ <span class="userinput">cp -i config/environments/production.rb.example config/environments/production.rb</span>
  46 </code></pre></notextile>
  47
  48 h2. Configure the API server
  49
  50 First, copy the example configuration file:
  51
  52 <notextile>
  53 <pre><code>~/arvados/services/api$ <span class="userinput">cp -i config/application.yml.example config/application.yml</span>
  54 </code></pre></notextile>
  55
  56 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.
  57
  58 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@.
  59
  60 h3(#uuid_prefix). uuid_prefix
  61
  62 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.
  63
  64 h3(#git_repositories_dir). git_repositories_dir
  65
  66 This field defaults to @/var/lib/arvados/git@. You can override the value by defining it in @config/application.yml@.
  67
  68 Make sure a clone of the arvados repository exists in @git_repositories_dir@.
  69
  70 <notextile>
  71 <pre><code>~/arvados/services/api$ <span class="userinput">sudo mkdir -p /var/lib/arvados/git</span>
  72 ~/arvados/services/api$ <span class="userinput">sudo git clone --bare ../../.git /var/lib/arvados/git/arvados.git</span>
  73 </code></pre></notextile>
  74
  75 h3. secret_token
  76
  77 Generate a new secret token for signing cookies:
  78
  79 <notextile>
  80 <pre><code>~/arvados/services/api$ <span class="userinput">rake secret</span>
  81 zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
  82 </code></pre></notextile>
  83
  84 Then put that value in the @secret_token@ field.
  85
  86 h3. blob_signing_key
  87
  88 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).
  89
  90 h3. workbench_address
  91
  92 Fill in the url of your workbench application in in @workbench_address@, for example
  93
  94 &nbsp;&nbsp;https://workbench.@prefix_uuid@.your.domain
  95
  96 h3. other options
  97
  98 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@.
  99
 100 h2. Set up the database
 101
 102 Generate a new database password. Nobody ever needs to memorize it or type it, so we'll make a strong one:
 103
 104 <notextile>
 105 <pre><code>~/arvados/services/api$ <span class="userinput">ruby -e 'puts rand(2**128).to_s(36)'</span>
 106 6gqa1vu492idd7yca9tfandj3
 107 </code></pre></notextile>
 108
 109 Create a new database user with permission to create its own databases.
 110
 111 <notextile>
 112 <pre><code>~/arvados/services/api$ <span class="userinput">sudo -u postgres createuser --createdb --encrypted --pwprompt arvados</span>
 113 [sudo] password for <b>you</b>: <span class="userinput">yourpassword</span>
 114 Enter password for new role: <span class="userinput">paste-password-you-generated</span>
 115 Enter it again: <span class="userinput">paste-password-again</span>
 116 Shall the new role be a superuser? (y/n) <span class="userinput">n</span>
 117 Shall the new role be allowed to create more new roles? (y/n) <span class="userinput">n</span>
 118 </code></pre></notextile>
 119
 120 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.
 121
 122 <notextile>
 123 <pre><code>~/arvados/services/api$ <span class="userinput">cp -i config/database.yml.sample config/database.yml</span>
 124 ~/arvados/services/api$ <span class="userinput">edit config/database.yml</span>
 125 </code></pre></notextile>
 126
 127 Create and initialize the database. If you are planning a production system, choose the @production@ rails environment, otherwise use @development@.
 128
 129 <notextile>
 130 <pre><code>~/arvados/services/api$ <span class="userinput">RAILS_ENV=production bundle exec rake db:setup</span>
 131 </code></pre></notextile>
 132
 133 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.
 134
 135 <notextile>
 136 <pre><code>~/arvados/services/api$ <span class="userinput">su postgres createdb arvados_production -E UTF8 -O arvados</span>
 137 ~/arvados/services/api$ <span class="userinput">RAILS_ENV=production bundle exec rake db:structure:load</span>
 138 ~/arvados/services/api$ <span class="userinput">RAILS_ENV=production bundle exec rake db:seed</span>
 139 </code></pre></notextile>
 140
 141 <div class="alert alert-block alert-info">
 142   <button type="button" class="close" data-dismiss="alert">&times;</button>
 143   <h4>Note!</h4>
 144 You can safely ignore the following error message you may see when loading the database structure:
 145 <notextile>
 146 <pre><code>ERROR:  must be owner of extension plpgsql</code></pre></notextile>
 147 </div>
 148
 149 h2. Set up omniauth
 150
 151 First copy the omniauth configuration file:
 152
 153 <notextile>
 154 <pre><code>~/arvados/services/api$ <span class="userinput">cp -i config/initializers/omniauth.rb.example config/initializers/omniauth.rb
 155 </code></pre></notextile>
 156
 157 Edit @config/initializers/omniauth.rb@, and tell your api server to use the Curoverse SSO server for authentication. Use the @APP_SECRET@ specified in the snippet below.
 158
 159 <notextile>
 160 <pre><code>APP_ID = 'local_docker_installation'
 161 APP_SECRET = 'yohbai4eecohshoo1Yoot7tea9zoca9Eiz3Tajahweo9eePaeshaegh9meiye2ph'
 162 CUSTOM_PROVIDER_URL = 'https://auth.curoverse.com'
 163 </code></pre></notextile>
 164 </pre>
 165
 166 <div class="alert alert-block alert-info">
 167   <button type="button" class="close" data-dismiss="alert">&times;</button>
 168   <h4>Note!</h4>
 169   <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>
 170 </div>
 171
 172 h2. Start the API server
 173
 174 h3. Development environment
 175
 176 If you plan to run in development mode, you can now run the development server this way:
 177
 178 <notextile>
 179 <pre><code>~/arvados/services/api$ <span class="userinput">bundle exec rails server --port=3030
 180 </code></pre></notextile>
 181
 182 h3. Production environment
 183
 184 We recommend "Passenger":https://www.phusionpassenger.com/ to run the API server in production.
 185
 186 Point it to the services/api directory in the source tree.
 187
 188 To enable streaming so users can monitor crunch jobs in real time, make sure to add the following to your Passenger configuration:
 189
 190 <notextile>
 191 <pre><code><span class="userinput">PassengerBufferResponse off</span>
 192 </code></pre>
 193 </notextile>