From 3b893d17a9499705708da771ceafbd59b1259e70 Mon Sep 17 00:00:00 2001 From: Brett Smith Date: Thu, 31 Dec 2015 11:23:34 -0500 Subject: [PATCH] 8095: Make install guide bundle commands more consistent. * Always instruct the user to use `sudo -u`. This prevents the commands from generating cache files that the web server can't write later. * Always execute the command in the server's main directory. This helps people run on automatic: if they leave a shell session open at the API server directory, they can paste in a combination of Rails console and script commands without `cd`ing around. * Always give both RVM and non-RVM instructions. There might be a good way to streamline this, e.g., by telling them to use rvmsudo when available, but that can be a later optimization. --- doc/_includes/_install_rails_command.liquid | 41 +++++++++++++++++++ .../install-arv-git-httpd.html.textile.liquid | 23 ++--------- .../install-keep-web.html.textile.liquid | 11 ++--- .../install-keepproxy.html.textile.liquid | 13 ++---- doc/install/install-sso.html.textile.liquid | 22 +++++----- .../install-workbench-app.html.textile.liquid | 14 ++++--- 6 files changed, 73 insertions(+), 51 deletions(-) create mode 100644 doc/_includes/_install_rails_command.liquid diff --git a/doc/_includes/_install_rails_command.liquid b/doc/_includes/_install_rails_command.liquid new file mode 100644 index 0000000000..319f56434a --- /dev/null +++ b/doc/_includes/_install_rails_command.liquid @@ -0,0 +1,41 @@ +{% comment %} +This template recognizes four variables: +* railshost: The hostname included in the prompt, to let the user know where to run the command. If this is the empty string, no hostname will be displayed. Default "apiserver". +* railsdir: The directory included in the prompt, to let the user know where to run the command. Default "/var/www/arvados-api/current". +* railscmd: The full command to run. Default "bundle exec rails console". +* railsout: The expected output of the command, if any. +{% endcomment %} Change *@webserver-user@* to the user that runs your web server process. If you install Phusion Passenger as we recommend, this is *@www-data@* on Debian-based systems, and *@nginx@* on Red Hat-based systems. + +{% unless railshost %} + {% assign railshost = "apiserver" %} +{% endunless %} + +{% unless (railshost == "") or (railshost contains ":") %} + {% capture railshost %}{{railshost}}:{% endcapture %} +{% endunless %} + +{% unless railsdir %} + {% assign railsdir = "/var/www/arvados-api/current" %} +{% endunless %} + +{% unless railscmd %} + {% assign railscmd = "bundle exec rails console" %} +{% endunless %} + +Using RVM: + + +
{{railshost}}~$ cd {{railsdir}}
+{{railshost}}{{railsdir}}$ sudo -u webserver-user RAILS_ENV=production `which rvm-exec` default {{railscmd}}
+{% if railsout %}{{railsout}}
+{% endif %}
+ + +Not using RVM: + + +
{{railshost}}~$ cd {{railsdir}}
+{{railshost}}{{railsdir}}$ sudo -u webserver-user RAILS_ENV=production {{railscmd}}
+{% if railsout %}{{railsout}}
+{% endif %}
+ diff --git a/doc/install/install-arv-git-httpd.html.textile.liquid b/doc/install/install-arv-git-httpd.html.textile.liquid index e592afc7c2..146dbe170b 100644 --- a/doc/install/install-arv-git-httpd.html.textile.liquid +++ b/doc/install/install-arv-git-httpd.html.textile.liquid @@ -34,25 +34,10 @@ DNS and network configuration should be set up so port 443 reaches your HTTPS pr h2. Generate an API token -Use the following command to generate an API token, changing *@webserver-user@* to the user of the web server process. This is typically *@www-data@* on Debian systems by default, other systems may use different defaults such the name of the web server software (for example, *@nginx@*). - -Using RVM: - - -
gitserver:~$ cd /var/www/arvados-api/current
-gitserver:/var/www/arvados-api/current$ sudo -u webserver-user RAILS_ENV=production `which rvm-exec` default bundle exec ./script/create_superuser_token.rb
-zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
-
- - -Not using RVM: - - -
gitserver:~$ cd /var/www/arvados-api/current
-gitserver:/var/www/arvados-api/current$ sudo -u webserver-user RAILS_ENV=production bundle exec ./script/create_superuser_token.rb
-zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
-
- +{% assign railshost = "gitserver" %} +{% assign railscmd = "bundle exec ./script/create_superuser_token.rb" %} +{% assign railsout = "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz" %} +Use the following command to generate an API token. {% include 'install_rails_command' %} Copy that token; you'll need it in a minute. diff --git a/doc/install/install-keep-web.html.textile.liquid b/doc/install/install-keep-web.html.textile.liquid index 5eb4191e8c..9e271d3c27 100644 --- a/doc/install/install-keep-web.html.textile.liquid +++ b/doc/install/install-keep-web.html.textile.liquid @@ -48,18 +48,15 @@ Usage of keep-web: -If you intend to use Keep-web to serve public data to anonymous clients, configure it with an anonymous token. You can use the same one you used when you set up your Keepproxy server, or use the following command on the API server to create another: - - -
/var/www/arvados-api/current/script$ RAILS_ENV=production bundle exec ./get_anonymous_user_token.rb
-hoShoomoo2bai3Ju1xahg6aeng1siquuaZ1yae2gi2Uhaeng2r
-
 +{% assign railscmd = "bundle exec ./script/get_anonymous_user_token.rb" %} +{% assign railsout = "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz" %} +If you intend to use Keep-web to serve public data to anonymous clients, configure it with an anonymous token. You can use the same one you used when you set up your Keepproxy server, or use the following command on the API server to create another. {% include 'install_rails_command' %} We recommend running @keep-web@ under "runit":https://packages.debian.org/search?keywords=runit or a similar supervisor. The basic command to start @keep-web@ is: 
export ARVADOS_API_HOST=uuid_prefix.your.domain
-export ARVADOS_API_TOKEN="hoShoomoo2bai3Ju1xahg6aeng1siquuaZ1yae2gi2Uhaeng2r"
+export ARVADOS_API_TOKEN="{{railsout}}"
 exec sudo -u nobody keep-web \
  -listen=:9002 \
  -attachment-only-host=download.uuid_prefix.your.domain \
diff --git a/doc/install/install-keepproxy.html.textile.liquid b/doc/install/install-keepproxy.html.textile.liquid
index 5a5b66aaae..14e5ed5741 100644
--- a/doc/install/install-keepproxy.html.textile.liquid
+++ b/doc/install/install-keepproxy.html.textile.liquid
@@ -51,21 +51,16 @@ Usage of keepproxy:
 
 h3. Create an API token for the Keepproxy server
 
-The Keepproxy server needs a token to talk to the API server.
-
-On the API server, use the following command to create the token:
-
-
-
/var/www/arvados-api/current/script$ RAILS_ENV=production bundle exec ./get_anonymous_user_token.rb
-hoShoomoo2bai3Ju1xahg6aeng1siquuaZ1yae2gi2Uhaeng2r
-

+{% assign railscmd = "bundle exec ./script/get_anonymous_user_token.rb" %}
+{% assign railsout = "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz" %}
+The Keepproxy server needs a token to talk to the API server.  On the API server, use the following command to create the token.  {% include 'install_rails_command' %}
 
 h3. Set up the Keepproxy service
 
 We recommend you run Keepproxy under "runit":http://smarden.org/runit/ or a similar supervisor.  Make sure the launcher sets the envirnoment variables @ARVADOS_API_TOKEN@ (with the token you just generated), @ARVADOS_API_HOST@, and, if needed, @ARVADOS_API_HOST_INSECURE@.  The core keepproxy command to run is:
 
 
-
ARVADOS_API_TOKEN=[generated token] ARVADOS_API_HOST=uuid_prefix.your.domain exec keepproxy
+
ARVADOS_API_TOKEN={{railsout}} ARVADOS_API_HOST=uuid_prefix.your.domain exec keepproxy
 

 
 
diff --git a/doc/install/install-sso.html.textile.liquid b/doc/install/install-sso.html.textile.liquid
index ca620f478a..1a3e4b380a 100644
--- a/doc/install/install-sso.html.textile.liquid
+++ b/doc/install/install-sso.html.textile.liquid
@@ -159,17 +159,18 @@ On a Red Hat-based system, we need to reinstall the package instead:
 
 h2(#client). Create arvados-server client
 
-Use @rails console@ to create a @Client@ record that will be used by the Arvados API server.  The values of @app_id@ and @app_secret@ correspond to the values for @sso_app_id@ and @sso_app_secret@ in the "API server's SSO settings.":install-api-server.html#omniauth
+{% assign railshost = "" %}
+{% assign railsdir = "/var/www/arvados-sso/current" %}
+Use @rails console@ to create a @Client@ record that will be used by the Arvados API server.  {% include 'install_rails_command' %}
+
+Enter the following commands at the console.  The values that appear after you assign @app_id@ and @app_secret@ correspond to the values for @sso_app_id@ and @sso_app_secret@, respectively, in the "API server's SSO settings":install-api-server.html#omniauth.
 
 
-
~$ ruby -e 'puts rand(2**400).to_s(36)'
-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-~$ cd /var/www/arvados-sso/current
-/var/www/arvados-sso/current$ RAILS_ENV=production bundle exec rails console
-:001 > c = Client.new
+
:001 > c = Client.new
 :002 > c.name = "joshid"
 :003 > c.app_id = "arvados-server"
-:004 > c.app_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+:004 > c.app_secret = rand(2**400).to_s(36)
+=> "save this string for your API server's sso_app_secret"
 :005 > c.save!
 :006 > quit
 

@@ -245,11 +246,12 @@ There are two configuration options for local accounts:
 
 For more information about configuring backend support for sending email (required to send email confirmations) see "Configuring Action Mailer":http://guides.rubyonrails.org/configuring.html#configuring-action-mailer
 
-If @allow_account_registration@ is false, you may manually create local accounts on the SSO server from the rails console:
+If @allow_account_registration@ is false, you may manually create local accounts on the SSO server from the Rails console.  {% include 'install_rails_command' %}
+
+Enter the following commands at the console.
 
 
-
~$ RAILS_ENV=production bundle exec rails console
-:001 > user = User.new(:email => "test@example.com")
+
:001 > user = User.new(:email => "test@example.com")
 :002 > user.password = "passw0rd"
 :003 > user.save!
 :004 > quit
diff --git a/doc/install/install-workbench-app.html.textile.liquid b/doc/install/install-workbench-app.html.textile.liquid
index 9e8cb7f2ad..7f504a919d 100644
--- a/doc/install/install-workbench-app.html.textile.liquid
+++ b/doc/install/install-workbench-app.html.textile.liquid
@@ -183,10 +183,11 @@ h2. Trusted client setting
 
 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 API server project root, start the rails console.  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:
+In the API server project root, start the Rails console.  {% include 'install_rails_command' %}
 
-
/var/www/arvados-api/current$ RAILS_ENV=production bundle exec rails console
-irb(main):001:0> wb = ApiClient.all.last; [wb.url_prefix, wb.created_at]
+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:
+
+
irb(main):001:0> wb = ApiClient.all.last; [wb.url_prefix, wb.created_at]
 => ["https://workbench.example.com/", Sat, 19 Apr 2014 03:35:12 UTC +00:00]
 irb(main):002:0> include CurrentApiClient
 => true
@@ -197,11 +198,12 @@ irb(main):003:0> act_as_system_user do wb.update_attr
 
 h2(#admin-user). Add an admin user
 
-Next, we're going to use the rails console on the API server to activate our own account and give yourself admin privileges:
+Next, we're going to use the Rails console on the API server to activate your account and give yourself admin privileges.  {% include 'install_rails_command' %}
+
+Enter the following commands at the console:
 
 
-
/var/www/arvados-api/current$ RAILS_ENV=production bundle exec rails console
-irb(main):001:0> Thread.current[:user] = User.all.select(&:identity_url).last
+
irb(main):001:0> Thread.current[:user] = User.all.select(&:identity_url).last
 irb(main):002:0> Thread.current[:user].update_attributes is_admin: true, is_active: true
 irb(main):003:0> User.where(is_admin: true).collect &:email
 => ["root", "your_address@example.com"]
-- 
2.30.2