at 1a6736e164d4421faade6944ced159fb1e11bde0 (commit)
commit 1a6736e164d4421faade6944ced159fb1e11bde0
Author: Brett Smith <brett at curoverse.com>
Date: Wed Jun 8 13:17:43 2016 -0400
9309: Separate PostgreSQL setup page in Install Guide.
This provides us with a few benefits:
* We have a place to discuss the different deployment options
installers have around PostgreSQL.
* PostgreSQL setup is very distro-specific (and it's going to get
worse when we add CentOS 7), so this can take some of that noise out
of the Rails server install guides.
* People who want to try new things, like cloud database services,
get a clearer separation of the install process and the database
setup process.
diff --git a/doc/_config.yml b/doc/_config.yml
index 2ee1f5d..4115bc9 100644
--- a/doc/_config.yml
+++ b/doc/_config.yml
@@ -148,6 +148,7 @@ navbar:
- install/arvbox.html.textile.liquid
- Manual installation:
- install/install-manual-prerequisites.html.textile.liquid
+ - install/install-postgresql.html.textile.liquid
- install/install-sso.html.textile.liquid
- install/install-api-server.html.textile.liquid
- install/install-arv-git-httpd.html.textile.liquid
diff --git a/doc/_includes/_install_postgres.liquid b/doc/_includes/_install_postgres.liquid
deleted file mode 100644
index 82c2c2d..0000000
--- a/doc/_includes/_install_postgres.liquid
+++ /dev/null
@@ -1,22 +0,0 @@
-On a Debian-based system, install the following packages:
-
-<notextile>
-<pre><code>~$ <span class="userinput">sudo apt-get install libpq-dev postgresql</span>
-</code></pre>
-</notextile>
-
-On a Red Hat-based system, install the following packages:
-
-<notextile>
-<pre><code>~$ <span class="userinput">sudo yum install postgresql postgresql-devel</span>
-</code></pre>
-</notextile>
-
-{% include 'notebox_begin' %}
-
-If you intend to use specific versions of these packages from Software Collections, you may have to adapt some of the package names to match. For example:
-
-<notextile>
-<pre><code>~$ <span class="userinput">sudo yum install postgresql92 postgresql92-postgresql-devel</span></code></pre></notextile>
-
-{% include 'notebox_end' %}
diff --git a/doc/_includes/_install_postgres_database.liquid b/doc/_includes/_install_postgres_database.liquid
new file mode 100644
index 0000000..b96c5a3
--- /dev/null
+++ b/doc/_includes/_install_postgres_database.liquid
@@ -0,0 +1,17 @@
+# Start a shell for the postgres user. On CentOS 6:
+ <notextile><pre>~$ <span class="userinput">sudo -u postgres scl enable rh-postgresql94 bash</span>
+</pre></notextile> On any other distribution:
+ <notextile><pre>~$ <span class="userinput">sudo -u postgres bash</span></pre></notextile>
+# Generate a new database password:
+ <notextile><pre>$ <span class="userinput">ruby -e 'puts rand(2**128).to_s(36)'</span>
+yourgeneratedpassword
+</pre></notextile> Record this. You'll need it when you set up the Rails server later.
+# Create a database user with the password you generated:
+ <notextile><pre><code>$ <span class="userinput">createuser --encrypted -R -S --pwprompt {{service_role}}</span>
+Enter password for new role: <span class="userinput">yourgeneratedpassword</span>
+Enter it again: <span class="userinput">yourgeneratedpassword</span>
+</code></pre></notextile>
+# Create a database owned by the new user:
+ <notextile><pre><code>$ <span class="userinput">createdb {{service_database}} -T template0 -E UTF8 -O {{service_role}}</span></code></pre></notextile>
+# Exit the postgres user shell:
+ <notextile><pre>$ <span class="userinput">exit</span></pre></notextile>
diff --git a/doc/_includes/_install_redhat_postgres_auth.liquid b/doc/_includes/_install_redhat_postgres_auth.liquid
deleted file mode 100644
index 35f8b79..0000000
--- a/doc/_includes/_install_redhat_postgres_auth.liquid
+++ /dev/null
@@ -1,11 +0,0 @@
-{% include 'notebox_begin' %}
-
-If you are installing on CentOS 6, you will need to modify PostgreSQL's configuration to allow password authentication for local users. The default configuration allows 'ident' authentication only. The following commands will make the configuration change, and restart PostgreSQL for it to take effect.
-
-<notextile>
-<pre><code>~$ <span class="userinput">sudo sed -ri -e 's/^(host +all +all +(127\.0\.0\.1\/32|::1\/128) +)ident$/\1md5/' {{pg_hba_path}}</span>
-~$ <span class="userinput">sudo service {{pg_service}} restart</span>
-</code></pre>
-</notextile>
-
-{% include 'notebox_end' %}
diff --git a/doc/install/install-api-server.html.textile.liquid b/doc/install/install-api-server.html.textile.liquid
index 91e2c69..b4019a4 100644
--- a/doc/install/install-api-server.html.textile.liquid
+++ b/doc/install/install-api-server.html.textile.liquid
@@ -12,10 +12,6 @@ h3(#install_ruby_and_bundler). Install Ruby and Bundler
{% include 'install_ruby_and_bundler' %}
-h3(#install_postgres). Install PostgreSQL
-
-{% include 'install_postgres' %}
-
h2(#install_apiserver). Install API server and dependencies
On a Debian-based system, install the following packages:
@@ -36,37 +32,12 @@ On a Red Hat-based system, install the following packages:
h2(#configure). Set up the database
-Generate a new database password. Nobody ever needs to memorize it or type it, so we'll make a strong one:
+Configure the API server to connect to your database by updating @/etc/arvados/api/database.yml at . Replace the @xxxxxxxx@ database password placeholder with the "password you generated during database setup":install-postgresql.html#api. Be sure to update the @production@ section.
<notextile>
-<pre><code>~$ <span class="userinput">ruby -e 'puts rand(2**128).to_s(36)'</span>
-6gqa1vu492idd7yca9tfandj3
+<pre><code>~$ <span class="userinput">editor /etc/arvados/api/database.yml</span>
</code></pre></notextile>
-Create a new database user.
-
-<notextile>
-<pre><code>~$ <span class="userinput">sudo -u postgres createuser --encrypted -R -S --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>
-</code></pre></notextile>
-
-{% assign pg_hba_path = "/opt/rh/postgresql92/root/var/lib/pgsql/data/pg_hba.conf" %}
-{% assign pg_service = "postgresql92-postgresql" %}
-{% include 'install_redhat_postgres_auth' %}
-
-Create the database:
-
-<notextile>
-<pre><code>~$ <span class="userinput">sudo -u postgres createdb arvados_production -T template0 -E UTF8 -O arvados</span>
-</code></pre>
-</notextile>
-
-h2. Configure the database connection
-
-Edit @/etc/arvados/api/database.yml@ and replace the @xxxxxxxx@ database password placeholders with the PostgreSQL password you generated above.
-
h2(#configure_application). Configure the API server
Edit @/etc/arvados/api/application.yml@ to configure the settings described in the following sections. The API server reads both @application.yml@ and its own @config/application.default.yml@ file. The settings in @application.yml@ take precedence over the defaults that are defined in @config/application.default.yml at . The @config/application.yml.example@ file is not read by the API server and is provided as a starting template only.
diff --git a/doc/install/install-postgresql.html.textile.liquid b/doc/install/install-postgresql.html.textile.liquid
new file mode 100644
index 0000000..d7fb3ce
--- /dev/null
+++ b/doc/install/install-postgresql.html.textile.liquid
@@ -0,0 +1,48 @@
+---
+layout: default
+navsection: installguide
+title: Set up PostgreSQL databases
+...
+
+Two Arvados Rails servers store data in a PostgreSQL database: the SSO server, and the API server. The API server requires at least version 9.1 of PostgreSQL. Beyond that, you have the flexibility to deploy PostgreSQL any way that the Rails servers will be able to connect to it. Our recommended deployment strategy is:
+
+* Install PostgreSQL on the the same host as the SSO server, and dedicate that install to hosting the SSO database. This provides the best security for the SSO server, because the database does not have to accept any client connections over the network. Typical load on the SSO server is light enough that deploying both it and its database on the same host does not compromise performance.
+* If you want to provide the most scalability for your Arvados cluster, install PostgreSQL for the API server on a dedicated host. This gives you the most flexibility to avoid resource contention, and tune performance separately for the API server and its database. If performance is less of a concern for your installation, you can install PostgreSQL on the API server host directly, as with the SSO server.
+
+Find the section for your distribution below, and follow it to install PostgreSQL on each host where you will deploy it. Then follow the steps in the later section(s) to set up PostgreSQL for the Arvados service(s) that need it.
+
+h2(#centos6). Install PostgreSQL on CentOS 6
+
+# Install Software Collections:
+ <notextile><pre>~$ <span class="userinput">sudo yum install centos-release-scl scl-utils</span></pre></notextile>
+# Install PostgreSQL:
+ <notextile><pre>~$ <span class="userinput">sudo yum install rh-postgresq94-postgresql-server</span></pre></notextile>
+# Initialize the database:
+ <notextile><pre>~$ <span class="userinput">sudo scl enable rh-postgresql94 "postgresql-setup initdb"</span></pre></notextile>
+# Configure the database to accept password connections:
+ <notextile><pre><code>~$ <span class="userinput">sudo sed -ri -e 's/^(host +all +all +(127\.0\.0\.1\/32|::1\/128) +)ident$/\1md5/' /var/opt/rh/rh-postgresql94/lib/pgsql/data/pg_hba.conf</span></code></pre></notextile>
+# Configure the database to launch at boot:
+ <notextile><pre>~$ <span class="userinput">sudo chkconfig rh-postgresql94-postgresql on</span></pre></notextile>
+# Start the database:
+ <notextile><pre>~$ <span class="userinput">sudo service rh-postgresql94-postgresql start</span></pre></notextile>
+# "Set up Arvados credentials and databases":#rails_setup for the services that will use this PostgreSQL install.
+
+h2(#debian). Install PostgreSQL on Debian or Ubuntu
+
+# Install PostgreSQL:
+ <notextile><pre>~$ <span class="userinput">sudo apt-get install postgresql</span></pre></notextile>
+# "Set up Arvados credentials and databases":#rails_setup for the services that will use this PostgreSQL install.
+
+<a name="rails_setup"></a>
+
+h2(#sso). Set up SSO server credentials and database
+
+{% assign service_role = "arvados_sso" %}
+{% assign service_database = "arvados_sso_production" %}
+{% include 'install_postgres_database' %}
+
+h2(#api). Set up API server credentials and database
+
+{% assign service_role = "arvados" %}
+{% assign service_database = "arvados_production" %}
+{% include 'install_postgres_database' %}
diff --git a/doc/install/install-sso.html.textile.liquid b/doc/install/install-sso.html.textile.liquid
index aaa6211..86a48c9 100644
--- a/doc/install/install-sso.html.textile.liquid
+++ b/doc/install/install-sso.html.textile.liquid
@@ -77,59 +77,12 @@ There are other configuration options in @/etc/arvados/sso/application.yml at . See
h2(#database). Set up the database
-If PostgreSQL was newly installed as a dependency of the @arvados-sso-server@ package, you will need to start the service.
-
-On a Debian-based system:
-
-<notextile>
-<pre><code>~$ <span class="userinput">sudo service postgresql start</span>
-</code></pre>
-</notextile>
-
-On a Red Hat-based system, we also need to initialize the database system:
-
-<notextile>
-<pre><code>~$ <span class="userinput">sudo service postgresql initdb</span>
-~$ <span class="userinput">sudo service postgresql start</span>
-</code></pre>
-</notextile>
-
-{% assign pg_service = "postgresql" %}
-{% assign pg_hba_path = "/var/lib/pgsql/data/pg_hba.conf" %}
-{% include 'install_redhat_postgres_auth' %}
-
-Next, generate a new database password. Nobody ever needs to memorize it or type it, so make a strong one:
-
-<notextile>
-<pre><code>~$ <span class="userinput">ruby -e 'puts rand(2**128).to_s(36)'</span>
-abcdefghijklmnopqrstuvwxyz012345689
-</code></pre></notextile>
-
-Configure the SSO server to connect to your database by updating @/etc/arvados/sso/database.yml at . Replace the @xxxxxxxx@ database password placeholder with the new password you generated above. Be sure to update the @production@ section.
+Configure the SSO server to connect to your database by updating @/etc/arvados/sso/database.yml at . Replace the @xxxxxxxx@ database password placeholder with the "password you generated during database setup":install-postgresql.html#sso. Be sure to update the @production@ section.
<notextile>
<pre><code>~$ <span class="userinput">editor /etc/arvados/sso/database.yml</span>
</code></pre></notextile>
-Create a new database user with permission to create its own databases.
-
-<notextile>
-<pre><code>~$ <span class="userinput">sudo -u postgres createuser --createdb --encrypted -R -S --pwprompt arvados_sso</span>
-Enter password for new role: <span class="userinput">paste-database-password-you-generated</span>
-Enter it again: <span class="userinput">paste-database-password-you-generated</span>
-</code></pre></notextile>
-
-Rails will take care of creating the database, based on the information from @/etc/arvados/sso/database.yml at .
-
-Alternatively, if the database user you intend to use for the SSO server should not be allowed to create new databases, the user and the database can be created like this:
-
-<notextile>
-<pre><code>~$ <span class="userinput">sudo -u postgres createuser --encrypted -R -S --pwprompt arvados_sso</span>
-Enter password for new role: <span class="userinput">paste-database-password-you-generated</span>
-Enter it again: <span class="userinput">paste-database-password-you-generated</span>
-~$ <span class="userinput">sudo -u postgres createdb arvados_sso_production -E UTF8 -O arvados_sso -T template0</span>
-</code></pre></notextile>
-
h2(#reconfigure_package). Reconfigure the package
{% assign railspkg = "arvados-sso-server" %}
-----------------------------------------------------------------------
hooks/post-receive
--