From 98ad217a974c500506d1b42b4b636d7886230cd3 Mon Sep 17 00:00:00 2001 From: Philip Durbin Date: Thu, 21 Dec 2017 13:03:33 -0500 Subject: [PATCH] update guides from el6 to el7 #4384 --- .../source/developers/selinux.rst | 2 +- .../source/installation/installation-main.rst | 26 ++++++++----------- .../source/installation/prerequisites.rst | 23 +++++++++------- .../installation/r-rapache-tworavens.rst | 6 ++++- .../source/installation/shibboleth.rst | 8 +++++- 5 files changed, 38 insertions(+), 27 deletions(-) diff --git a/doc/sphinx-guides/source/developers/selinux.rst b/doc/sphinx-guides/source/developers/selinux.rst index 582510c5847..d7f5b0d7519 100644 --- a/doc/sphinx-guides/source/developers/selinux.rst +++ b/doc/sphinx-guides/source/developers/selinux.rst @@ -8,7 +8,7 @@ SELinux Introduction ------------ -The ``shibboleth.te`` file below that is mentioned in the :doc:`/installation/shibboleth` section of the Installation Guide was created on CentOS 6 as part of https://github.com/IQSS/dataverse/issues/3406 but may need to be revised for future versions of RHEL/CentOS. The file is versioned with the docs and can be found in the following location: +The ``shibboleth.te`` file below that is mentioned in the :doc:`/installation/shibboleth` section of the Installation Guide was created on CentOS 6 as part of https://github.com/IQSS/dataverse/issues/3406 but may need to be revised for future versions of RHEL/CentOS (pull requests welcome!). The file is versioned with the docs and can be found in the following location: ``doc/sphinx-guides/source/_static/installation/files/etc/selinux/targeted/src/policy/domains/misc/shibboleth.te`` diff --git a/doc/sphinx-guides/source/installation/installation-main.rst b/doc/sphinx-guides/source/installation/installation-main.rst index 3a4a479093c..38e0c31565a 100755 --- a/doc/sphinx-guides/source/installation/installation-main.rst +++ b/doc/sphinx-guides/source/installation/installation-main.rst @@ -13,19 +13,19 @@ Running the Dataverse Installer ------------------------------- A scripted, interactive installer is provided. This script will configure your Glassfish environment, create the database, set some required options and start the application. Some configuration tasks will still be required after you run the installer! So make sure to consult the next section. -At this point the installer only runs on RHEL 6 and similar and MacOS X (recommended as the platform for developers). -Generally, the installer has a better chance of succeeding if you run it against a freshly installed Glassfish node that still has all the default configuration settings. In any event, please make sure that it is still configured to accept http connections on port 8080 - because that's where the installer expects to find the application once it's deployed. +As mentioned in the :doc:`prerequisites` section, RHEL/CentOS is the recommended Linux distribution. (The installer is also known to work on Mac OS X for setting up a development environment.) +Generally, the installer has a better chance of succeeding if you run it against a freshly installed Glassfish node that still has all the default configuration settings. In any event, please make sure that it is still configured to accept http connections on port 8080 - because that's where the installer expects to find the application once it's deployed. You should have already downloaded the installer from https://github.com/IQSS/dataverse/releases when setting up and starting Solr under the :doc:`prerequisites` section. Again, it's a zip file with "dvinstall" in the name. Unpack the zip file - this will create the directory ``dvinstall``. -Execute the installer script like this:: +Execute the installer script like this (but first read the note below about not running the installer as root):: - # cd dvinstall - # ./install + $ cd dvinstall + $ ./install **It is no longer necessary to run the installer as root!** @@ -38,7 +38,6 @@ Just make sure the user running the installer has write permission to: The only reason to run Glassfish as root would be to allow Glassfish itself to listen on the default HTTP(S) ports 80 and 443, or any other port below 1024. However, it is simpler and more secure to run Glassfish run on its default port of 8080 and hide it behind an Apache Proxy, via AJP, running on port 80 or 443. This configuration is required if you're going to use Shibboleth authentication. See more discussion on this here: :doc:`shibboleth`.) - The script will prompt you for some configuration values. If this is a test/evaluation installation, it may be possible to accept the default values provided for most of the settings: - Internet Address of your host: localhost @@ -58,23 +57,20 @@ The script will prompt you for some configuration values. If this is a test/eval - Rserve Server Port: 6311 - Rserve User Name: rserve - Rserve User Password: rserve - -If desired, these default values can be configured by creating a ``default.config`` (example :download:`here <../_static/util/default.config>`) file in the installer's working directory with new values (if this file isn't present, the above defaults will be used). - -This allows the installer to be run in non-interactive mode (with ``./install -y -f > install.out 2> install.err``), which can allow for easier interaction with automated provisioning tools. - -**New, as of 4.3:** - - Administration Email address for the installation; - Postgres admin password - We'll need it in order to create the database and user for the Dataverse to use, without having to run the installer as root. If you don't know your Postgres admin password, you may simply set the authorization level for localhost to "trust" in the PostgreSQL ``pg_hba.conf`` file (See the PostgreSQL section in the Prerequisites). If this is a production evnironment, you may want to change it back to something more secure, such as "password" or "md5", after the installation is complete. - Network address of a remote Solr search engine service (if needed) - In most cases, you will be running your Solr server on the same host as the Dataverse application (then you will want to leave this set to the default value of ``LOCAL``). But in a serious production environment you may set it up on a dedicated separate server. - The URL of the TwoRavens application GUI, if this Dataverse node will be using a companion TwoRavens installation. Otherwise, leave it set to ``NOT INSTALLED``. -The script is to a large degree a derivative of the old installer from DVN 3.x. It is written in Perl. If someone in the community is eager to rewrite it, perhaps in a different language, please get in touch. :) +If desired, these default values can be configured by creating a ``default.config`` (example :download:`here <../_static/util/default.config>`) file in the installer's working directory with new values (if this file isn't present, the above defaults will be used). + +This allows the installer to be run in non-interactive mode (with ``./install -y -f > install.out 2> install.err``), which can allow for easier interaction with automated provisioning tools. All the Glassfish configuration tasks performed by the installer are isolated in the shell script ``dvinstall/glassfish-setup.sh`` (as ``asadmin`` commands). -**IMPORTANT:** Please note, that "out of the box" the installer will configure the Dataverse to leave unrestricted access to the administration APIs from (and only from) localhost. Please consider the security implications of this arrangement (anyone with shell access to the server can potentially mess with your Dataverse). An alternative solution would be to block open access to these sensitive API endpoints completely; and to only allow requests supplying a pre-defined "unblock token" (password). If you prefer that as a solution, please consult the supplied script ``post-install-api-block.sh`` for examples on how to set it up. +**IMPORTANT:** Please note, that "out of the box" the installer will configure the Dataverse to leave unrestricted access to the administration APIs from (and only from) localhost. Please consider the security implications of this arrangement (anyone with shell access to the server can potentially mess with your Dataverse). An alternative solution would be to block open access to these sensitive API endpoints completely; and to only allow requests supplying a pre-defined "unblock token" (password). If you prefer that as a solution, please consult the supplied script ``post-install-api-block.sh`` for examples on how to set it up. See also "Securing Your Installation" under the :doc:`config` section. + +The script is to a large degree a derivative of the old installer from DVN 3.x. It is written in Perl. If someone in the community is eager to rewrite it, perhaps in a different language, please get in touch. :) Logging In ---------- diff --git a/doc/sphinx-guides/source/installation/prerequisites.rst b/doc/sphinx-guides/source/installation/prerequisites.rst index c3d94c5fefe..2fb43ff9871 100644 --- a/doc/sphinx-guides/source/installation/prerequisites.rst +++ b/doc/sphinx-guides/source/installation/prerequisites.rst @@ -2,13 +2,20 @@ Prerequisites ============= -Before running the Dataverse installation script, you must install and configure the following software, preferably on a Linux distribution such as RHEL or CentOS. After following all the steps below (which are mostly based on CentOS 6), you can proceed to the :doc:`installation-main` section. +Before running the Dataverse installation script, you must install and configure the following software. + +After following all the steps below, you can proceed to the :doc:`installation-main` section. You **may** find it helpful to look at how the configuration is done automatically by various tools such as Vagrant, Puppet, or Ansible. See the :doc:`prep` section for pointers on diving into these scripts. .. contents:: |toctitle| :local: +Linux +----- + +We assume you plan to run Dataverse on Linux and we recommend RHEL/CentOS, which is the Linux distribution tested by the Dataverse development team. Please be aware that while el7 (RHEL/CentOS 7) is the recommended platform, the steps below were orginally written for el6 and may need to be updated (please feel free to make a pull request!). + Java ---- @@ -21,13 +28,13 @@ Dataverse should run fine with only the Java Runtime Environment (JRE) installed The Oracle JDK can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads/index.html -On a Red Hat and similar Linux distributions, install OpenJDK with something like:: +On a RHEL/CentOS, install OpenJDK (devel version) using yum:: # yum install java-1.8.0-openjdk-devel If you have multiple versions of Java installed, Java 8 should be the default when ``java`` is invoked from the command line. You can test this by running ``java -version``. -On Red Hat/CentOS you can make Java 8 the default with the ``alternatives`` command, having it prompt you to select the version of Java from a list:: +On RHEL/CentOS you can make Java 8 the default with the ``alternatives`` command, having it prompt you to select the version of Java from a list:: # alternatives --config java @@ -38,7 +45,7 @@ If you don't want to be prompted, here is an example of the non-interactive invo Glassfish --------- -Glassfish Version 4.1 is required. There are known issues with Glassfish 4.1.1 as chronicled in https://github.com/IQSS/dataverse/issues/2628 so it should be avoided until that issue is resolved. +Glassfish Version 4.1 is required. There are known issues with newer versions of the Glassfish 4.x series so it should be avoided. For details, see https://github.com/IQSS/dataverse/issues/2628 . The issue we are using the track support for Glassfish 5 is https://github.com/IQSS/dataverse/issues/4248 . Installing Glassfish ==================== @@ -86,7 +93,7 @@ Launching Glassfish on system boot The Dataverse installation script will start Glassfish if necessary, but you may find the following scripts helpful to launch Glassfish start automatically on boot. - This :download:`Systemd file<../_static/installation/files/etc/systemd/glassfish.service>` may be serve as a reference for systems using Systemd (such as RHEL/CentOS 7 or Ubuntu 16+) -- This :download:`init script<../_static/installation/files/etc/init.d/glassfish.init.service>` may be useful for RHEL/CentOS6 or Ubuntu >= 14 if you're using a Glassfish service account, or +- This :download:`init script<../_static/installation/files/etc/init.d/glassfish.init.service>` may be useful for RHEL/CentOS 6 or Ubuntu >= 14 if you're using a Glassfish service account, or - This :download:`Glassfish init script <../_static/installation/files/etc/init.d/glassfish.init.root>` may be helpful if you're just going to run Glassfish as root. It is not necessary for Glassfish to be running before you execute the Dataverse installation script; it will start Glassfish for you. @@ -101,18 +108,16 @@ Installing PostgreSQL Version 9.x is required. Previous versions have not been tested. -The version that ships with RHEL 6 and above is fine:: +The version that ships with el7 and above is fine:: # yum install postgresql-server # service postgresql initdb # service postgresql start -The standard init script that ships RHEL 6 and similar should work fine. Enable it with this command:: +The standard init script that ships with el7 should work fine. Enable it with this command:: # chkconfig postgresql on - - Configuring Database Access for the Dataverse Application (and the Dataverse Installer) ======================================================================================= diff --git a/doc/sphinx-guides/source/installation/r-rapache-tworavens.rst b/doc/sphinx-guides/source/installation/r-rapache-tworavens.rst index 4e394461e26..732987f0a75 100644 --- a/doc/sphinx-guides/source/installation/r-rapache-tworavens.rst +++ b/doc/sphinx-guides/source/installation/r-rapache-tworavens.rst @@ -140,7 +140,11 @@ EPEL distribution recommended; version 3.3.2 is **strongly** recommended. If :fixedwidthplain:`yum` isn't configured to use EPEL repositories ( https://fedoraproject.org/wiki/EPEL ): -CentOS users can install the RPM :fixedwidthplain:`epel-release`. For RHEL/CentOS 6:: +RHEL/CentOS users can install the RPM :fixedwidthplain:`epel-release`. For RHEL/CentOS 7:: + + yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm + +RHEL/CentOS users can install the RPM :fixedwidthplain:`epel-release`. For RHEL/CentOS 6:: yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-6.noarch.rpm diff --git a/doc/sphinx-guides/source/installation/shibboleth.rst b/doc/sphinx-guides/source/installation/shibboleth.rst index a883cef2826..1448acd7b97 100644 --- a/doc/sphinx-guides/source/installation/shibboleth.rst +++ b/doc/sphinx-guides/source/installation/shibboleth.rst @@ -23,7 +23,7 @@ System Requirements Support for Shibboleth in Dataverse is built on the popular `"mod_shib" Apache module, "shibd" daemon `_, and the `Embedded Discovery Service (EDS) `_ Javascript library, all of which are distributed by the `Shibboleth Consortium `_. EDS is bundled with Dataverse, but ``mod_shib`` and ``shibd`` must be installed and configured per below. -Only Red Hat Enterprise Linux (RHEL) 6 and derivatives such as CentOS have been tested (x86_64 versions) by the Dataverse team. Newer versions of RHEL and CentOS **should** work but you'll need to adjust the yum repo config accordingly. See https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxInstall for details and note that (according to that page) as of this writing Ubuntu and Debian are not offically supported by the Shibboleth project. +Only Red Hat Enterprise Linux (RHEL) and derivatives such as CentOS have been tested (x86_64 versions) by the Dataverse team. See https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxInstall for details and note that (according to that page) as of this writing Ubuntu and Debian are not offically supported by the Shibboleth project. Install Apache ~~~~~~~~~~~~~~ @@ -46,6 +46,12 @@ This yum repo is recommended at https://wiki.shibboleth.net/confluence/display/S ``cd /etc/yum.repos.d`` +If you are running el7 (RHEL/CentOS 7): + +``wget http://download.opensuse.org/repositories/security:/shibboleth/CentOS_7/security:shibboleth.repo`` + +If you are running el6 (RHEL/CentOS 6): + ``wget http://download.opensuse.org/repositories/security:/shibboleth/CentOS_CentOS-6/security:shibboleth.repo`` Install Shibboleth Via Yum