doc/install/install-workbench-app.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Install Workbench
   5 ...
   6 {% comment %}
   7 Copyright (C) The Arvados Authors. All rights reserved.
   8
   9 SPDX-License-Identifier: CC-BY-SA-3.0
  10 {% endcomment %}
  11
  12 h2. Install prerequisites
  13
  14 The Arvados package repository includes a Workbench server package that can help automate much of the deployment.
  15
  16 h3(#install_ruby_and_bundler). Install Ruby and Bundler
  17
  18 {% include 'install_ruby_and_bundler' %}
  19
  20 h2(#install_workbench). Install Workbench and dependencies
  21
  22 Workbench doesn't need its own database, so it does not need to have PostgreSQL installed.
  23
  24 {% assign rh_version = "7" %}
  25 {% include 'note_python_sc' %}
  26
  27 On a Debian-based system, install the following packages:
  28
  29 <notextile>
  30 <pre><code>~$ <span class="userinput">sudo apt-get install bison build-essential graphviz git python-arvados-python-client arvados-workbench</span>
  31 </code></pre>
  32 </notextile>
  33
  34 On a Red Hat-based system, install the following packages:
  35
  36 <notextile>
  37 <pre><code>~$ <span class="userinput">sudo yum install bison make automake gcc gcc-c++ graphviz git python-arvados-python-client arvados-workbench</span>
  38 </code></pre>
  39 </notextile>
  40
  41 h2(#configure). Configure Workbench
  42
  43 Edit @/etc/arvados/config.yml@ following the instructions below.  Only a few of the most important configuration options are listed here.  The full set of configuration options are in the "Workbench section of config.yml":{{site.baseurl}}/admin/config.html
  44
  45 h3. Workbench.SecretKeyBase
  46
  47 This application needs a secret token. Generate a new secret:
  48
  49 <notextile>
  50 <pre><code>~$ <span class="userinput">ruby -e 'puts rand(2**400).to_s(36)'</span>
  51 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
  52 </code></pre>
  53 </notextile>
  54
  55 Then put that value in the @Workbench.SecretKeyBase@ field.
  56
  57 h3. Services.Controller.ExternalURL
  58
  59 Ensure that @Services.Controller.ExternalURL@ is configured for "Arvados Controller":install-controller.html . For example like this:
  60
  61 <notextile>
  62 <pre><code>Cluster:
  63   zzzzz:
  64     Services:
  65       Controller:
  66         ExternalURL: https://prefix_uuid.your.domain
  67 </code></pre>
  68 </notextile>
  69
  70 h3. Workbench.SiteName
  71
  72 @Workbench.SiteName@ can be set to any arbitrary string. It is used to identify this Workbench to people visiting it.
  73
  74 h3. TLS.Insecure
  75
  76 For testing only.  Allows use of self-signed certificates.  If true, workbench will not verify the TLS certificate of Arvados Controller.
  77
  78 h2. Configure Piwik
  79
  80 Piwik is optional, and can be to gather usage analytics.  In @/var/www/arvados-workbench/current/config@, copy @piwik.yml.example@ to @piwik.yml@ and edit to suit.
  81
  82 h2. Set up Web server
  83
  84 For best performance, we recommend you use Nginx as your Web server front-end, with a Passenger backend to serve Workbench.  To do that:
  85
  86 <notextile>
  87 <ol>
  88 <li><a href="https://www.phusionpassenger.com/library/walkthroughs/deploy/ruby/ownserver/nginx/oss/install_passenger_main.html">Install Nginx and Phusion Passenger</a>.</li>
  89
  90 <li><p>Edit the http section of your Nginx configuration to run the Passenger server, and act as a front-end for it.  You might add a block like the following, adding SSL and logging parameters to taste:</p>
  91
  92 <pre><code>server {
  93   listen 127.0.0.1:9000;
  94   server_name localhost-workbench;
  95
  96   root /var/www/arvados-workbench/current/public;
  97   index  index.html index.htm index.php;
  98
  99   passenger_enabled on;
 100   # If you're using RVM, uncomment the line below.
 101   #passenger_ruby /usr/local/rvm/wrappers/default/ruby;
 102
 103   # `client_max_body_size` should match the corresponding setting in
 104   # the API.MaxRequestSize and Controller's server's Nginx configuration.
 105   client_max_body_size 128m;
 106 }
 107
 108 upstream workbench {
 109   server     127.0.0.1:9000  fail_timeout=10s;
 110 }
 111
 112 proxy_http_version 1.1;
 113
 114 server {
 115   listen       <span class="userinput">[your public IP address]</span>:443 ssl;
 116   server_name  workbench.<span class="userinput">uuid-prefix.your.domain</span>;
 117
 118   ssl on;
 119   ssl_certificate     <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
 120   ssl_certificate_key <span class="userinput">/YOUR/PATH/TO/cert.key</span>;
 121
 122   index  index.html index.htm index.php;
 123   # `client_max_body_size` should match the corresponding setting in
 124   # the API.MaxRequestSize and Controller's server's Nginx configuration.
 125   client_max_body_size 128m;
 126
 127   location / {
 128     proxy_pass            http://workbench;
 129     proxy_redirect        off;
 130     proxy_connect_timeout 90s;
 131     proxy_read_timeout    300s;
 132
 133     proxy_set_header      X-Forwarded-Proto https;
 134     proxy_set_header      Host $http_host;
 135     proxy_set_header      X-Real-IP $remote_addr;
 136     proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
 137   }
 138 }
 139 </code></pre>
 140 </li>
 141
 142 <li>Restart Nginx.</li>
 143
 144 </ol>
 145 </notextile>
 146
 147 h2. Prepare the Workbench deployment
 148
 149 {% assign railspkg = "arvados-workbench" %}
 150 {% include 'install_rails_reconfigure' %}
 151
 152 {% include 'notebox_begin' %}
 153 You can safely ignore the following error message you may see when Ruby Gems are installed:
 154 <notextile>
 155 <pre><code>themes_for_rails at /usr/local/rvm/gems/ruby-2.1.1/bundler/gems/themes_for_rails-1fd2d7897d75 did not have a valid gemspec.
 156 This prevents bundler from installing bins or native extensions, but that may not affect its functionality.
 157 The validation message from Rubygems was:
 158   duplicate dependency on rails (= 3.0.11, development), (>= 3.0.0) use:
 159     add_runtime_dependency 'rails', '= 3.0.11', '>= 3.0.0'
 160 Using themes_for_rails (0.5.1) from https://github.com/holtkampw/themes_for_rails (at 1fd2d78)
 161 </code></pre>
 162 </notextile>
 163 {% include 'notebox_end' %}
 164
 165 h2. Trusted client setting
 166
 167 Log in to Workbench once to ensure that the Arvados API server has a record of the Workbench client. (It's OK if Workbench says your account hasn't been activated yet. We'll deal with that next.)
 168
 169 In the <strong>API server</strong> project root, start the Rails console.  {% include 'install_rails_command' %}
 170
 171 At the console, enter the following commands to locate the ApiClient record for your Workbench installation (typically, while you're setting this up, the @last@ one in the database is the one you want), then set the @is_trusted@ flag for the appropriate client record:
 172
 173 <notextile><pre><code>irb(main):001:0&gt; <span class="userinput">wb = ApiClient.all.last; [wb.url_prefix, wb.created_at]</span>
 174 =&gt; ["https://workbench.example.com/", Sat, 19 Apr 2014 03:35:12 UTC +00:00]
 175 irb(main):002:0&gt; <span class="userinput">include CurrentApiClient</span>
 176 =&gt; true
 177 irb(main):003:0&gt; <span class="userinput">act_as_system_user do wb.update_attributes!(is_trusted: true) end</span>
 178 =&gt; true
 179 </code></pre>
 180 </notextile>
 181
 182 h2(#admin-user). Add an admin user
 183
 184 Next, we're going to use the Rails console on the <strong>API server</strong> to activate your account and give yourself admin privileges.  {% include 'install_rails_command' %}
 185
 186 Enter the following commands at the console:
 187
 188 <notextile>
 189 <pre><code>irb(main):001:0&gt; <span class="userinput">Thread.current[:user] = User.all.select(&:identity_url).last</span>
 190 irb(main):002:0&gt; <span class="userinput">Thread.current[:user].update_attributes is_admin: true, is_active: true</span>
 191 irb(main):003:0&gt; <span class="userinput">User.where(is_admin: true).collect &:email</span>
 192 =&gt; ["root", "<b>your_address@example.com</b>"]
 193 </code></pre></notextile>
 194
 195 At this point, you should have a working Workbench login with administrator privileges. Revisit your Workbench URL in a browser and reload the page to access it.