---
layout: default
navsection: installguide
title: Install Workbench
...
{% comment %}
Copyright (C) The Arvados Authors. All rights reserved.

SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}

# "Install dependencies":#dependencies
# "Update config.yml":#update-config
# "Update Nginx configuration":#update-nginx
# "Install arvados-workbench":#install-packages
# "Restart the API server and controller":#restart-api
# "Confirm working installation":#confirm-working
# "Trusted client setting":#trusted_client

h2(#dependencies). Install dependencies

# "Install Ruby and Bundler":ruby.html
# "Install nginx":nginx.html
# "Install Phusion Passenger":https://www.phusionpassenger.com/library/walkthroughs/deploy/ruby/ownserver/nginx/oss/install_passenger_main.html

h2(#configure). Update config.yml

Edit @/etc/arvados/config.yml@ to set the keys below.  The full set of configuration options are in the "Workbench section of config.yml":{{site.baseurl}}/admin/config.html

<notextile>
<pre><code>    Services:
      Workbench:
        ExternalURL: <span class="userinput">"https://workbench.ClustedID.example.com"</span>
    Workbench:
      SecretKeyBase: <span class="userinput">aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa</span>
    Users:
      AutoAdminFirstUser: true
</code></pre>
</notextile>

This application needs a secret token. Generate a new secret:

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

Then put that value in the @Workbench.SecretKeyBase@ field.

You probably want to enable @Users.AutoAdminFirstUser@ .  The first user to log in when no other admin user exists will automatically be made an admin.

h2(#update-nginx). Update nginx configuration

Use a text editor to create a new file @/etc/nginx/conf.d/arvados-workbench.conf@ with the following configuration.  Options that need attention are marked with "TODO".

<notextile>
<pre><code>server {
  listen       <span class="userinput">[your public IP address]</span>:443 ssl;
  server_name  workbench.<span class="userinput">ClusterID.example.com</span>;

  ssl on;
  ssl_certificate     <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
  ssl_certificate_key <span class="userinput">/YOUR/PATH/TO/cert.key</span>;

  root /var/www/arvados-workbench/current/public;
  index  index.html;

  passenger_enabled on;
  # If you're using RVM, uncomment the line below.
  #passenger_ruby /usr/local/rvm/wrappers/default/ruby;

  # `client_max_body_size` should match the corresponding setting in
  # the API.MaxRequestSize and Controller's server's Nginx configuration.
  client_max_body_size 128m;
}
</code></pre>
</notextile>

h2(#install-packages). Install arvados-workbench

h3. Centos 7

<notextile>
<pre><code># <span class="userinput">yum install arvados-workbench</span>
</code></pre>
</notextile>

h3. Debian and Ubuntu

<notextile>
<pre><code># <span class="userinput">apt-get --no-install-recommends install arvados-workbench</span>
</code></pre>
</notextile>

h2(#restart-api). Restart the API server and controller

After adding Workbench to the Services section, make sure the cluster config file is up to date on the API server host, and restart the API server and controller processes to ensure the changes are applied.

<notextile>
<pre><code># <span class="userinput">systemctl restart nginx arvados-controller</span>
</code></pre>
</notextile>

h2(#confirm-working). Confirm working installation

Visit @https://workbench.ClusterID.example.com@ in a browser.  You should be able to log in using the login method you configured in the previous step.  If @Users.AutoAdminFirstUser@ is true, you will be an admin user.

h2(#trusted_client). Trusted client flag

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

In the <strong>API server</strong> project root, start the Rails console.  {% include 'install_rails_command' %}

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:

<notextile><pre><code>irb(main):001:0&gt; <span class="userinput">wb = ApiClient.all.last; [wb.url_prefix, wb.created_at]</span>
=&gt; ["https://workbench.example.com/", Sat, 19 Apr 2014 03:35:12 UTC +00:00]
irb(main):002:0&gt; <span class="userinput">include CurrentApiClient</span>
=&gt; true
irb(main):003:0&gt; <span class="userinput">act_as_system_user do wb.update_attributes!(is_trusted: true) end</span>
=&gt; true
</code></pre>
</notextile>