Mercurial > hg > LGDataverses
diff DVN-web/installer/dvninstall/doc/guides/dataverse-installer-main.html @ 6:1b2188262ae9
adding the installer.
| author | "jurzua <jurzua@mpiwg-berlin.mpg.de>" |
|---|---|
| date | Wed, 13 May 2015 11:50:21 +0200 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/DVN-web/installer/dvninstall/doc/guides/dataverse-installer-main.html Wed May 13 11:50:21 2015 +0200 @@ -0,0 +1,1209 @@ + + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + + <title>Installers Guide — The Harvard Dataverse Network 3.6.1 documentation</title> + + <link rel="stylesheet" href="_static/agogo.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: './', + VERSION: '3.6.1', + COLLAPSE_INDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/underscore.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script> + <link rel="top" title="The Harvard Dataverse Network 3.6.1 documentation" href="index.html" /> + <link rel="next" title="DVN Developers Guide" href="dataverse-developer-main.html" /> + <link rel="prev" title="User Guide" href="dataverse-user-main.html" /> + </head> + <body> + <div class="header-wrapper"> + <div class="header"> + <div class="headertitle"><a + href="index.html">The Harvard Dataverse Network 3.6.1 documentation</a></div> + <div class="rel"> + <a href="dataverse-user-main.html" title="User Guide" + accesskey="P">previous</a> | + <a href="dataverse-developer-main.html" title="DVN Developers Guide" + accesskey="N">next</a> | + <a href="genindex.html" title="General Index" + accesskey="I">index</a> + </div> + </div> + </div> + + <div class="content-wrapper"> + <div class="content"> + <div class="document"> + + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="installers-guide"> +<h1>Installers Guide<a class="headerlink" href="#installers-guide" title="Permalink to this headline">¶</a></h1> +<p id="introduction"><strong>Introduction</strong></p> +<p>This is our “new and improved” installation guide, it was first +released with the Dataverse Network application versions 2.2.4, when we +introduced the new, automated and much simplified installation process. +As of February 2012, it has been updated to reflect the changes made in +the newly released version 3.0 of the software. (Our existing users will +notice however, that the changes in the installation process have been +fairly minimal).</p> +<p>The guide is intended for anyone who needs to install the DVN app, +developers and Dataverse Network administrators alike.</p> +<p>The top-down organization of the chapters and sections is that of +increasing complexity. First a very basic, simple installation scenario +is presented. The instructions are straightforward and only the required +components are discussed. This use case will in fact be sufficient for +most DVN developers and many Dataverse Network administrators. Chances +are you are one of such users, so if brave by nature, you may stop +reading this section and go straight to the <a class="reference internal" href="#quick-install"><em>“Quick Install”</em></a> chapter.</p> +<p>The “basic” installation process described in the first chapter is +fully automated, everything is performed by a single interactive script. +This process has its limitations. It will likely work only on the +supported platforms. Optional components need to be configured outside +of the Installer (these are described in the “Optional Components” +section).</p> +<p>For an advanced user, we provide the detailed explanations of all the +steps performed by the Installer. This way he or she can experiment with +individual configuration options, having maximum flexibility and control +over the process. Yet we tried to organize the advanced information in +such a way that those who only need the most basic instructions would +not have to read through it unnecessarily. Instead we provide them with +an easy way to get a bare-bones configuration of the DVN up and running.</p> +<p>If you are interested in practicing a DVN installation in a Vagrant +environment you can later throw away, please follow the instructions at +<a class="reference external" href="https://github.com/dvn/dvn-install-demo">https://github.com/dvn/dvn-install-demo</a> to spin up a Linux virtual +machine on your laptop with <tt class="docutils literal"><span class="pre">vagrant</span> <span class="pre">up</span></tt>. When you are finished with +this temporary DVN installation, you can delete the virtual machine with +<tt class="docutils literal"><span class="pre">vagrant</span> <span class="pre">destroy</span></tt>.</p> +<p>If you encounter any problems during installation, please contact the +development team +at <a class="reference external" href="mailto:support%40thedata.org">support<span>@</span>thedata<span>.</span>org</a> +or our <a class="reference external" href="https://groups.google.com/forum/?fromgroups#!forum/dataverse-community">Dataverse Users +Community</a>.</p> +<div class="section" id="quick-install"> +<span id="id1"></span><h2>Quick Install<a class="headerlink" href="#quick-install" title="Permalink to this headline">¶</a></h2> +<p>For an experienced and/or rather bold user, this is a 1 +paragraph version of the installation instructions:</p> +<p>This should work on RedHat and its derivatives, and MacOS X. If this +does not describe your case, you will very likely have to install and +configure at least some of the components manually. Meaning, you may +consider reading through the chapters that follow! Still here? Great. +Prerequisites: Sun/Oracle Java JDK 1.6_31+ and a “virgin” installation +of Glassfish v3.1.2; PostgreSQL v8.3+, configured to listen to network +connections and support password authentication on the localhost +interface; you may need R as well. See the corresponding sections under +“2. Prerequisites”, if necessary. Download the installer package from +SourceForge:</p> +<p><a class="reference external" href="http://sourceforge.net/projects/dvn/files/dvn">http://sourceforge.net/projects/dvn/files/dvn</a></p> +<p>Choose the latest version and download the dvninstall zip file.</p> +<p>Unzip the package in a temp location of your choice (this will create +the directory <tt class="docutils literal"><span class="pre">dvninstall</span></tt>). Run the installer, as root:</p> +<blockquote> +<div><dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">dvninstall</span></tt></dt> +<dd>./ <tt class="docutils literal"><span class="pre">install</span></tt></dd> +</dl> +</div></blockquote> +<p>Follow the installation prompts. If it all works as it should, you +will have a working DVN instance running in about a minute from now.</p> +<p>Has it worked? Awesome! Now you may read the rest of the guide +chapters at your own leisurely pace, to see if you need any of the +optional components described there. And/or if you want to understand +what exactly has just been done to your system.</p> +</div> +<div class="section" id="system-requirements"> +<h2>SYSTEM REQUIREMENTS<a class="headerlink" href="#system-requirements" title="Permalink to this headline">¶</a></h2> +<p>Or rather, recommendations. The closer your configuration is to what’s +outlined below, the easier it will be for the DVN team to provide +support and answer your questions.</p> +<ul class="simple"> +<li>Operating system - The production version of the Dataverse Network at +IQSS (dvn.iq.harvard.edu) runs on RedHat Linux 5. Most of the DVN +development is currently done on MacOS X. Because of our experience +with RedHat and MacOS X these are the recommended platforms. You +should be able to deploy the application .ear file on any other +platform that supports Java. However, the automated installer we +provide will likely work on RedHat and MacOS only. Some information +provided in this guide is specific to these 2 operating systems. (Any +OS-specific instructions/examples will be clearly marked, for +example:<tt class="docutils literal"><span class="pre">[MacOS-specific:]</span></tt>)</li> +<li>CPU - The production IQSS Dataverse Network runs on generic, +multi-core 64-bit processors.</li> +<li>Memory - The application servers currently in production at the IQSS +have 64 GB of memory each. Development and testing systems require a +minimum of 2 gigabyte of memory.</li> +<li>Disk space - How much disk space is required depends on the amount of +data that you expect to serve. The IQSS Dataverse Network file system +is a standalone NetApp with 2 TB volume dedicated to the DVN data.</li> +<li>Multiple servers – All the DVN components can run on the same server. +On a busy, hard-working production network the load can be split +across multiple servers. The 3 main components, the application +server (Glassfish), the database (Postgres) and R can each run on its +own host. Furthermore, multiple application servers sharing the same +database and R server(s) can be set up behind a load balancer. +Developers would normally run Glassfish and Postgres on their +workstations locally and use a shared R server.</li> +<li>If it actually becomes a practical necessity to bring up more servers +to handle your production load, there are no universal instructions +on how to best spread it across extra CPUs. It will depend on the +specifics of your site, the nature of the data you serve and the +needs of your users, whether you’ll benefit most from dedicating +another server to run the database, or to serve R requests. Please +see the discussion in the corresponding sections of the Prerequisites +chapter.</li> +</ul> +</div> +<div class="section" id="prerequisites"> +<span id="id2"></span><h2>PREREQUISITES<a class="headerlink" href="#prerequisites" title="Permalink to this headline">¶</a></h2> +<p>In this chapter, an emphasis is made on clearly identifying those +components that are absolutely required for every installation and +marking any advanced, optional instructions as such.</p> +<div class="section" id="glassfish"> +<h3>Glassfish<a class="headerlink" href="#glassfish" title="Permalink to this headline">¶</a></h3> +<p>Version 3.1.2 is required.</p> +<p>Make sure you have <strong>Sun/Oracle</strong><strong>Java JDK version 1.6, build 31</strong> +or newer. It is available from +<a class="reference external" href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">http://www.oracle.com/technetwork/java/javase/downloads/index.html</a>.</p> +<p><strong>[note for developers:]</strong></p> +<p>If you are doing this installation as part of your DVN software +development setup: The version of NetBeans currently in use by the DVN +team is 7.0.1, and it is recommended that you use this same version if +you want to participate in the development. As of writing of this +manual, NetBeans 7.0.1 installer bundle comes with an older version of +Glassfish. So you will have to install Glassfish version 3.1.2 +separately, and then select it as the default server for your NetBeans +project.</p> +<p><strong>[/note for developers]</strong></p> +<p>We <strong>strongly</strong> recommend that you install GlassFish Server 3.1.2, +Open Source Edition, <strong>Full Platform</strong>. You are very likely to run into +installation issues if you attempt to run the installer and get the +application to work with a different version! Simply transitioning from +3.1.1 to 3.1.2 turned out to be a surprisingly complex undertaking, +hence this recommendation to all other installers and developers to stay +with the same version.</p> +<p>It can be obtained from</p> +<p><a class="reference external" href="http://glassfish.java.net/downloads/3.1.2-final.html">http://glassfish.java.net/downloads/3.1.2-final.html</a></p> +<p>The page contains a link to the installation instructions. However, +the process is completely straightforward. You are given 2 options for +the format of the installer package. We recommend that you choose to +download it as a shell archive; you will need to change its executable +permission, with <strong>chmod +x</strong>, and then run it, as root:</p> +<p>./<strong>installer-filename.sh</strong></p> +<p>[<strong>Important:]</strong></p> +<p>Leave the admin password fields blank. This is not a security risk, +since out of the box, Glassfish will only be accepting admin connections +on the localhost interface. Choosing password at this stage however will +complicate the installation process unnecessarily<strong>.</strong>If this is a +developers installation, you can probably keep this configuration +unchanged (admin on localhost only). If you need to be able to connect +to the admin console remotely, please see the note in the Appendix +section of the manual.</p> +<p><strong>[/Important]</strong></p> +<div class="line-block"> +<div class="line"><strong>[Advanced:]</strong></div> +<div class="line"><strong>[Unix-specific:`]</strong></div> +</div> +<p>The installer shell script will normally attempt to run in a graphic +mode. If you are installing this on a remote Unix server, this will +require X Windows support on your local workstation. If for whatever +reason it’s not available, you have an option of running it in a <em>silent +mode</em> - check the download page, above, for more information.</p> +<div class="line-block"> +<div class="line"><strong>[/Unix-specific]</strong></div> +<div class="line"><strong>[/Advanced]</strong></div> +</div> +</div> +<div class="section" id="postgresql"> +<span id="id3"></span><h3>PostgreSQL<a class="headerlink" href="#postgresql" title="Permalink to this headline">¶</a></h3> +<div class="line-block"> +<div class="line"><strong>Version 8.3 or higher is required.</strong></div> +<div class="line">Installation instructions specific to RedHat Linux and MacOS X are</div> +<div class="line">provided below.</div> +<div class="line">Once the database server is installed, you’ll need to configure access</div> +<div class="line">control to suit your installation.</div> +<div class="line">Note that any modifications to the configuration files above require you to restart Postgres:</div> +<div class="line"><tt class="docutils literal"><span class="pre">service</span> <span class="pre">postgresql</span> <span class="pre">restart</span></tt> (RedHat)</div> +</div> +<div class="line-block"> +<div class="line">or</div> +<div class="line">“Restart Server” under Applications -> PostgreSQL (MacOS X)</div> +</div> +<p>By default, most Postgres distributions are configured to listen to network connections on the localhost interface only; and to only support ident for authentication. (The MacOS installer may ask you if network connections should be allowed - answer “yes”). At a minimum, if GlassFish is running on the same host, it will also need to allow password authentication on localhost. So you will need to modify the “<tt class="docutils literal"><span class="pre">host</span> <span class="pre">all</span> <span class="pre">all</span> <span class="pre">127.0.0.1</span></tt>” line in your <tt class="docutils literal"><span class="pre">/var/lib/pgsq1/data/pg_hba.conf</span></tt> so that it looks like this:</p> +<div class="line-block"> +<div class="line"><tt class="docutils literal"><span class="pre">host</span> <span class="pre">all</span> <span class="pre">all</span> <span class="pre">127.0.0.1/32</span> <span class="pre">password</span></tt></div> +</div> +<p>Also, the installer script needs to have direct access to the local PostgresQL server via Unix domain sockets. So this needs to be set to either “trust” or “ident”. I.e., your <strong>pg_hba.conf</strong> must contain either of the 2 lines below:</p> +<div class="line-block"> +<div class="line"><strong>local all all ident sameuser</strong></div> +<div class="line">or</div> +<div class="line"><strong>local all all trust</strong></div> +</div> +<p>(“ident” is the default setting; but if it has been changed to +“password” or “md5”, etc. on your system, Postgres will keep prompting +you for the master password throughout the installation)</p> +<p><strong>[optional:]</strong></p> +<p>If GlassFish will be accessing the database remotely, add or modify the following line in your <tt class="docutils literal"><span class="pre"><POSTGRES</span> <span class="pre">DIR>/data/postgresql.conf</span></tt>:</p> +<div class="line-block"> +<div class="line"><tt class="docutils literal"><span class="pre">listen_addresses='*'</span></tt></div> +</div> +<p>to enable network connections on all interfaces; and add the following +line to <tt class="docutils literal"><span class="pre">pg_hba.conf</span></tt>:</p> +<div class="line-block"> +<div class="line">host all all <tt class="docutils literal"><span class="pre">[ADDRESS]</span> <span class="pre">255.255.255.255</span> <span class="pre">password</span></tt></div> +</div> +<div class="line-block"> +<div class="line">where <tt class="docutils literal"><span class="pre">[ADDRESS]</span></tt> is the numeric IP address of the GlassFish server.</div> +<div class="line">Using the subnet notation above you can enable authorization for multiple hosts on | your network. For example,</div> +</div> +<div class="line-block"> +<div class="line"><tt class="docutils literal"><span class="pre">host</span> <span class="pre">all</span> <span class="pre">all</span> <span class="pre">140.247.115.0</span> <span class="pre">255.255.255.0</span> <span class="pre">password</span></tt></div> +</div> +<div class="line-block"> +<div class="line">will permit password-authenticated connections from all hosts on the <tt class="docutils literal"><span class="pre">140.247.115.*</span></tt> subnet.</div> +<div class="line"><strong>[/optional:]</strong></div> +</div> +<div class="line-block"> +<div class="line"><br /></div> +<div class="line"><strong>[RedHat-specific:]</strong></div> +<div class="line"><strong>[Advanced:]</strong></div> +</div> +<p>Please note that the instructions below are meant for users who have some experience with basic RedHat admin tasks. You should be safe to proceed if an instruction such as “uninstall the postgres rpms” makes sense to you immediately. I.e., if you already know how to install or uninstall an rpm package. Otherwise we recommend that you contact your systems administrator.</p> +<p>For RedHat (and relatives), version 8.4 is now part of the distribution. As of RedHat 5, the default <tt class="docutils literal"><span class="pre">postgresql</span></tt> rpm is still version 8.1. So you may have to un-install the <tt class="docutils literal"><span class="pre">postgresql</span></tt> rpms, then get the ones for version 8.4:</p> +<div class="line-block"> +<div class="line"><tt class="docutils literal"><span class="pre">yum</span> <span class="pre">install</span> <span class="pre">postgresql84</span> <span class="pre">postgresql84-server</span></tt></div> +</div> +<p>Before you start the server for the first time with</p> +<div class="line-block"> +<div class="line"><tt class="docutils literal"><span class="pre">service</span> <span class="pre">postgresql</span> <span class="pre">start</span></tt></div> +</div> +<p>You will need to populate the initial database with</p> +<div class="line-block"> +<div class="line"><tt class="docutils literal"><span class="pre">service</span> <span class="pre">postgresql</span> <span class="pre">initdb</span></tt></div> +</div> +<div class="line-block"> +<div class="line"><strong>[/advanced]</strong></div> +<div class="line"><strong>[/RedHat-specific]</strong></div> +</div> +<p><strong>[MacOS-specific:]</strong></p> +<p>Postgres Project provides a one click installer for Mac OS X 10.4 and +above at +<a class="reference external" href="http://www.postgresql.org/download/macosx">http://www.postgresql.org/download/macosx</a>. +Fink and MacPorts packages are also available.</p> +<p><strong>[/MacOS-specific]`</strong></p> +<div class="line-block"> +<div class="line"><strong>[advanced:]</strong></div> +<div class="line"><strong>[optional:]</strong></div> +</div> +<p>See the section <a class="reference internal" href="#postgresql-setup"><em>PostgresQL setup</em></a> in the Appendix for the description of the steps that the automated installer takes to set up PostgresQL for use with the DVN.</p> +<div class="line-block"> +<div class="line"><strong>[/optional]</strong></div> +<div class="line"><strong>[/advanced]</strong></div> +</div> +</div> +<div class="section" id="r-and-rserve"> +<span id="id4"></span><h3>R and RServe<a class="headerlink" href="#r-and-rserve" title="Permalink to this headline">¶</a></h3> +<p>Strictly speaking, R is an optional component. You can bring up a +running DVN instance without it. The automated installer will allow such +an installation, with a warning. Users of this Dataverse Network will be +able to upload and share some data. Only the advanced modes of serving +quantitative data to the users require R <tt class="docutils literal"><span class="pre">[style?]</span></tt>. Please consult +the <a class="reference internal" href="#do-you-need-r"><em>“Do you need R?”</em></a> section in the Appendix for an extended discussion of this.</p> +<div class="line-block"> +<div class="line"><strong>Installation instructions:</strong></div> +</div> +<p>Install the latest version of R from your favorite CRAN mirror (refer to <a class="reference external" href="http://cran.r-project.org/">http://cran.r-project.org/</a> for more information). Depending on your OS distribution, this may be as simple as typing</p> +<div class="line-block"> +<div class="line"><strong>[RedHat/Linux-specific:]</strong></div> +</div> +<p><tt class="docutils literal"><span class="pre">yum</span> <span class="pre">install</span> <span class="pre">R</span> <span class="pre">R-devel</span></tt></p> +<p>(for example, the above line will work in CentOS out of the box; in RedHat, you will have to add support for EPEL repository – see +<a class="reference external" href="http://fedoraproject.org/wiki/EPEL">http://fedoraproject.org/wiki/EPEL</a> +– then run the <tt class="docutils literal"><span class="pre">yum</span> <span class="pre">install</span></tt> command)</p> +<div class="line-block"> +<div class="line"><strong>[/RedHat/Linux-specific]</strong></div> +</div> +<p>Please make sure to install the “devel” package too! you will need it +to build the extra R modules.</p> +<p>Once you have R installed, download the package <tt class="docutils literal"><span class="pre">dvnextra.tar</span></tt> from this location:</p> +<p><a class="reference external" href="http://dvn.iq.harvard.edu/dist/R/dvnextra.tar">http://dvn.iq.harvard.edu/dist/R/dvnextra.tar</a></p> +<p>Unpack the archive:</p> +<p><tt class="docutils literal"><span class="pre">tar</span> <span class="pre">xvf</span> <span class="pre">dvnextra.tar</span></tt></p> +<p>then run the supplied installation shell script as root:</p> +<div class="line-block"> +<div class="line-block"> +<div class="line"><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">dvnextra</span></tt></div> +</div> +<div class="line"><tt class="docutils literal"><span class="pre">./installModules.sh</span></tt></div> +</div> +<p>This will install a number of R modules needed by the DVN to run statistics and analysis, some from CRAN and some supplied in the bundle; it will also configure Rserve to run locally on your system and install some startup files that the DVN will need.</p> +<p><strong>Please note that the DVN application requires specific versions of the 3rd-party R packages. For example, if you obtain and install the version of Zelig package currently available from CRAN, it will not work with the application. This is why we distribute the sources of the correct versions in this tar package.</strong></p> +<div class="line-block"> +<div class="line"><strong>[advanced:]</strong></div> +<div class="line">We haven’t had much experience with R on any platforms other than RedHat-and-the-like. Our developers use MacOS X, but point their DVN instances to a shared server running Rserve under RedHat.</div> +</div> +<p>The R project ports their distribution to a wide range of platforms. However, the installer shell script above will only run on Unix; and is not really guaranteed to work on anything other than RedHat. If you have some experience with either R or system administration, you should be able to use the script as a guide to re-create the configuration steps on any other platform quite easily. You will, however, be entirely on your own while embarking on that adventure. +<strong>[/advanced]</strong></p> +</div> +<div class="section" id="system-configuration"> +<h3>System Configuration<a class="headerlink" href="#system-configuration" title="Permalink to this headline">¶</a></h3> +<p><strong>[Advanced/optional:]</strong></p> +<p>Many modern OS distributions come pre-configured so that all the +network ports are firewalled off by default.</p> +<p>Depending on the configuration of your server, you may need to open some +of the following ports.</p> +<p>On a developers personal workstation, the user would normally access his +or her DVN instance on the localhost interface. So no open ports are +required unless you want to give access to your DVN to another +user/developer.</p> +<p>When running a DVN that is meant to be accessible by network users: At a +minimum, if all the components are running on the same server, the HTTP +port 80 needs to be open. You may also want to open TCP 443, to be able +to access Glassfish admin console remotely.</p> +<p>If the DVN is running its own HANDLE.NET server (see Chapter 4. +“Optional Components”), the TCP port 8000 and TCP/UDP ports 2641 are +also needed.</p> +<p>If the DVN application needs to talk to PostgreSQL and/or Rserve running +on remote hosts, the TCP ports 5432 and 6311, respectively, need to be +open there.</p> +<p><strong>[/Advanced/optional]</strong></p> +</div> +</div> +<div class="section" id="running-the-installer"> +<h2>RUNNING THE INSTALLER<a class="headerlink" href="#running-the-installer" title="Permalink to this headline">¶</a></h2> +<p>Once the <a class="reference internal" href="#prerequisites"><em>Prerequisites</em></a> have been take care of, the DVN application can be installed.</p> +<p>The installer package can be downloaded from our repository on SourceForge at</p> +<p><a class="reference external" href="http://sourceforge.net/projects/dvn/files/dvn/3.0/dvninstall_v3_0.zip">http://sourceforge.net/projects/dvn/files/dvn/3.0/dvninstall_v3_0.zip</a></p> +<div class="line-block"> +<div class="line">Unzip the package in a temp location of your choice (this will create the directory | <tt class="docutils literal"><span class="pre">dvninstall</span></tt>). Run the installer, as root:</div> +<div class="line-block"> +<div class="line"><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">dvninstall</span></tt></div> +<div class="line"><tt class="docutils literal"><span class="pre">./install</span></tt></div> +</div> +</div> +<p>Follow the installation prompts. The installer will first verify the contents of the package and check if the required components +(in <a class="reference internal" href="#prerequisites"><em>Prerequisites</em></a>) are present on the system. Then it will lead you through the application setup.</p> +<div class="line-block"> +<div class="line"><strong>[Advanced:]</strong></div> +</div> +<p>The limitations of the installer package:</p> +<p>Some extra configuration steps will be required if the PostgreSQL database is being set up on a remote server.</p> +<p>It will most likely only work on the supported platforms, RedHat and Mac OS X.</p> +<p>It is only guaranteed to work on a fresh Glassfish installation. If you already have more than one Glassfish domains created and/or have applications other than the DVN running under Glassfish, please consult the <a class="reference internal" href="#what-does-the-intstaller-do"><em>“What does the Installer do?”</em></a> section.</p> +<p>It does not install any of the optional components (<a class="reference internal" href="#optional-components"><em>see Chapter 4</em></a>.)</p> +<p>For the detailed explanation of the tasks performed by the Installer, see the <a class="reference internal" href="#what-does-the-intstaller-do"><em>“What does the Installer do?”</em></a> section.</p> +<div class="line-block"> +<div class="line"><strong>[/Advanced]</strong></div> +</div> +</div> +<div class="section" id="optional-components"> +<span id="id5"></span><h2>Optional Components<a class="headerlink" href="#optional-components" title="Permalink to this headline">¶</a></h2> +<p><tt class="docutils literal"><span class="pre">[The</span> <span class="pre">sections</span> <span class="pre">on</span> <span class="pre">ImageMagick,</span> <span class="pre">Google</span> <span class="pre">Analytics</span> <span class="pre">and</span> <span class="pre">Captcha</span> <span class="pre">have</span> <span class="pre">been</span> <span class="pre">rewritten</span> <span class="pre">and,</span> <span class="pre">hopefully,</span> <span class="pre">made</span> <span class="pre">less</span> <span class="pre">confusing.</span> <span class="pre">The</span> <span class="pre">Handles</span> <span class="pre">instructions</span> <span class="pre">have</span> <span class="pre">also</span> <span class="pre">been</span> <span class="pre">modified,</span> <span class="pre">but</span> <span class="pre">I</span> <span class="pre">would</span> <span class="pre">like</span> <span class="pre">to</span> <span class="pre">work</span> <span class="pre">on</span> <span class="pre">it</span> <span class="pre">some</span> <span class="pre">more.</span> <span class="pre">Namely</span> <span class="pre">I'd</span> <span class="pre">like</span> <span class="pre">to</span> <span class="pre">read</span> <span class="pre">their</span> <span class="pre">own</span> <span class="pre">technical</span> <span class="pre">manual,</span> <span class="pre">and</span> <span class="pre">see</span> <span class="pre">if</span> <span class="pre">we</span> <span class="pre">should</span> <span class="pre">provide</span> <span class="pre">our</span> <span class="pre">own</span> <span class="pre">version</span> <span class="pre">of</span> <span class="pre">installation</span> <span class="pre">instructions,</span> <span class="pre">similarly</span> <span class="pre">to</span> <span class="pre">what</span> <span class="pre">we</span> <span class="pre">do</span> <span class="pre">with</span> <span class="pre">some</span> <span class="pre">other</span> <span class="pre">packages;</span> <span class="pre">we've</span> <span class="pre">heard</span> <span class="pre">complaints</span> <span class="pre">from</span> <span class="pre">users</span> <span class="pre">about</span> <span class="pre">their</span> <span class="pre">manual</span> <span class="pre">not</span> <span class="pre">being</span> <span class="pre">very</span> <span class="pre">easy</span> <span class="pre">to</span> <span class="pre">follow]</span></tt></p> +<div class="section" id="recaptcha-bot-blocker"> +<h3>reCAPTCHA bot blocker<a class="headerlink" href="#recaptcha-bot-blocker" title="Permalink to this headline">¶</a></h3> +<p>We found that our “email us” feature can be abused to send spam +messages. You can choose to use the reCAPTCHA filter to help prevent +this. Configure the filter as follows:</p> +<ol class="arabic"> +<li><div class="first line-block"> +<div class="line">Go to reCAPTCHA web site at</div> +<div class="line"><a class="reference external" href="http://recaptcha.net/">http://recaptcha.net/</a></div> +<div class="line">and sign up for an account.</div> +<div class="line">Register your website domain to acquire a public/private CAPTCHA key pair.</div> +<div class="line">Record this information in a secure location.</div> +</div> +</li> +<li><p class="first">Insert the the public/private key pair and domain for your reCAPTCHA +account into the <tt class="docutils literal"><span class="pre">captcha</span></tt> table of the DVN PostgreSQL database. +Use <tt class="docutils literal"><span class="pre">psql</span></tt>, <tt class="docutils literal"><span class="pre">pgadmin</span></tt> or any other database utility; the SQL +query will look like this: +<tt class="docutils literal"><span class="pre">INSERT</span> <span class="pre">INTO</span> <span class="pre">captcha</span> <span class="pre">(publickey,</span> <span class="pre">domainname,</span> <span class="pre">privatekey)</span> <span class="pre">VALUES</span> <span class="pre">('sample',</span> <span class="pre">'sample.edu',</span> <span class="pre">'sample')</span></tt></p> +</li> +<li><p class="first">Verify that the Report Issue page is now showing the reCAPTCHA +challenge.</p> +</li> +</ol> +</div> +<div class="section" id="google-analytics"> +<h3>Google Analytics<a class="headerlink" href="#google-analytics" title="Permalink to this headline">¶</a></h3> +<p>Network Admins can use the Google Analytics tools to view Dataverse Network website usage statistics.</p> +<p>Note: It takes about 24 hours for Google Analytics to start monitoring +your website after the registration.</p> +<div class="line-block"> +<div class="line"><br /></div> +<div class="line">To enable the use of Google Analytics:</div> +</div> +<ol class="arabic"> +<li><p class="first">Go to the Google Analytics homepage at +<a class="reference external" href="http://www.google.com/analytics/indexu.html">http://www.google.com/analytics/indexu.html</a>.</p> +</li> +<li><p class="first">Set up a Google Analytics account and obtain a tracking code for your Dataverse Network installation.</p> +</li> +<li><p class="first">Use the Google Analytics Help Center to find how to add the tracking code to the content you serve.</p> +</li> +<li><dl class="first docutils"> +<dt>Configure the DVN to use the tracking key (obtained in Step 2,</dt> +<dd><p class="first">above), by setting | the <tt class="docutils literal"><span class="pre">dvn.googleanalytics.key</span></tt> JVM option in +Glassfish.</p> +<p>This can be done by adding the following directly to the +<tt class="docutils literal"><span class="pre">domain.xml</span></tt> config file (for example: <tt class="docutils literal"><span class="pre">/usr/local/glassfish/domains/domain1/confi/domain.xml</span></tt>): +<tt class="docutils literal"><span class="pre"><jvm-options>-Ddvn.googleanalytics.key=XX-YYY</jvm-options></span></tt> (this will require Glassfish restart)</p> +<p class="last">Or by using the Glassfish Admin Console configuration GUI. Consult the “Glassfish Configuration” section in the Appendix.</p> +</dd> +</dl> +</li> +</ol> +<p>Once installed and activated, the usage statistics can be accessed from +the Network Options of the DVN.</p> +</div> +<div class="section" id="imagemagick"> +<h3>ImageMagick<a class="headerlink" href="#imagemagick" title="Permalink to this headline">¶</a></h3> +<p>When image files are ingested into a DVN, the application +automatically creates small “thumbnail” versions to display on the +Files View page. These thumbnails are generated once, then cached for +future use.</p> +<p>Normally, the standard Java image manipulation libraries are used to +do the scaling. If you have studies with large numbers of large +images, generating the thumbnails may become a time-consuming task. If +you notice that the Files view takes a long time to load for the first +time because of the images, it is possible | to improve the +performance by installing the <tt class="docutils literal"><span class="pre">ImageMagick</span></tt> package. If it is +installed, the application will automatically use its +<tt class="docutils literal"><span class="pre">/usr/bin/convert</span></tt> utility to do the resizing, which appears to be +significantly faster than the Java code.</p> +<p><tt class="docutils literal"><span class="pre">ImageMagick</span></tt> is available for, or even comes with most of the popular OS distributions.</p> +<div class="line-block"> +<div class="line"><strong><RedHat-Specific:></strong></div> +</div> +<p>It is part of the full RedHat Linux distribution, although it is not +included in the default “server” configuration. It can be installed on a +RedHat server with the <tt class="docutils literal"><span class="pre">yum</span> <span class="pre">install</span> <span class="pre">ImageMagick</span></tt> command.</p> +<p><strong></RedHat-Specific></strong></p> +</div> +<div class="section" id="handle-system"> +<h3>Handle System<a class="headerlink" href="#handle-system" title="Permalink to this headline">¶</a></h3> +<p>DVN administrators may choose to set up a <a class="reference external" href="http://www.handle.net/">HANDLE.NET</a> server to issue and register persistent, global identifiers for their studies. The DVN app can be modified to support other naming services, but as of now it comes +pre-configured to use Handles.</p> +<p>To install and set up a local HANDLE.NET server:</p> +<ol class="arabic simple"> +<li>Download HANDLE.NET. +Refer to the HANDLE.NET software download page at +<a class="reference external" href="http://handle.net/download.html">http://handle.net/download.html</a>.</li> +<li>Install the server on the same host as GlassFish. +Complete the installation and setup process as described in the +HANDLE.NET Technical Manual: +<a class="reference external" href="http://www.handle.net/tech_manual/Handle_Technical_Manual.pdf">http://www.handle.net/tech_manual/Handle_Technical_Manual.pdf</a>.</li> +<li>Accept the default settings during installation, <strong>with one +exception:</strong> do not encrypt private keys (this will make it easier to +manage the service). <strong>Note</strong> that this means answer ‘n’ when +prompted “Would you like to encrypt your private key?(y/n). [y]:” If +you accept the default ‘y’ and then hit return when prompted for +passphrase, this <strong>will</strong> encrypt the key, with a blank pass phrase!</li> +<li>During the installation you will be issued an “authority prefix”. +This is an equivalent of a domain name. For example, the prefix +registered to the IQSS DVN is “1902.1”. The IDs issued to IQSS +studies are of a form “1902.1/XXXX”, where “XXXX” is some unique +identifier.</li> +<li>Use <tt class="docutils literal"><span class="pre">psql</span></tt> or <tt class="docutils literal"><span class="pre">pgAdmin</span></tt> to execute the following SQL command: +<tt class="docutils literal"><span class="pre">insert</span> <span class="pre">into</span> <span class="pre">handleprefix</span> <span class="pre">(prefix)</span> <span class="pre">values(</span> <span class="pre">'<your</span> <span class="pre">HANDLE.NET</span> <span class="pre">prefix>')</span></tt>;</li> +<li><tt class="docutils literal"><span class="pre">(Optional/advanced)</span></tt> If you are going to be assigning HANDLE.NET +ids in more than 1 authority prefix (to register studies harvested +from remote sources): Once you obtain the additional HANDLE.NET +prefixes, add each to the <tt class="docutils literal"><span class="pre">handleprefix</span></tt> table, using the SQL +command from step 3.</li> +<li>Use <tt class="docutils literal"><span class="pre">psql</span></tt> or <tt class="docutils literal"><span class="pre">pgAdmin</span></tt> to execute the following SQL +command: <tt class="docutils literal"><span class="pre">update</span> <span class="pre">vdcnetwork</span> <span class="pre">set</span> <span class="pre">handleregistration=true,</span> <span class="pre">authority='<your</span> <span class="pre">HANDLE.NET</span> <span class="pre">prefix>';</span></tt></li> +</ol> +<p>Note: The DVN app comes bundled with the HANDLE.NET client libraries. +You do not need to install these separately.</p> +</div> +<div class="section" id="twitter-setup"> +<h3>Twitter setup<a class="headerlink" href="#twitter-setup" title="Permalink to this headline">¶</a></h3> +<p>To set up the ability for users to enable Automatic Tweets in your +Dataverse Network:</p> +<ol class="arabic"> +<li><p class="first">You will first need to tell twitter about you Dataverse Network Application. Go to <a class="reference external" href="https://dev.twitter.com/apps">https://dev.twitter.com/apps</a> and login (or create a new Twitter account).</p> +</li> +<li><p class="first">Click “Create a new application”.</p> +</li> +<li><p class="first">Fill out all the fields. For callback URL, use your Dataverse Network Home Page URL.</p> +</li> +<li><p class="first">Once created, go to settings tab and set Application Type to “Read and Write”. You can optionally also upload an Application +Icon and fill out Organization details (the end user will see these.</p> +</li> +<li><dl class="first docutils"> +<dt>Click details again. You will need both the Consumer key and secret as JVM Options. Add via Glassfish console:</dt> +<dd><p class="first">-Dtwitter4j.oauth.consumerKey=***</p> +<p class="last">-Dtwitter4j.oauth.consumerSecret=***</p> +</dd> +</dl> +</li> +<li><p class="first">Restart Glassfish.</p> +</li> +<li><p class="first">To verify that Automatic Tweets are now properly set up, you can go to the Dataverse Network Options page or any Dataverse Options page and see that their is a new option, “Enable Twitter”.</p> +</li> +</ol> +</div> +<div class="section" id="digital-object-identifiers"> +<h3>Digital Object Identifiers<a class="headerlink" href="#digital-object-identifiers" title="Permalink to this headline">¶</a></h3> +<p>Beginning with version 3.6, DVN will support the use of Digital Object Identifiers. Similar to the currently enabled Handle System, these DOIs will enable a permanent link to studies in a DVN network.</p> +<p>DVN uses the EZID API (<a class="reference external" href="http://www.n2t.net/ezid">www.n2t.net/ezid</a>) to facilitate the creation and maintenance of DOIs. Network administrators will have to arrange to get their own account with EZID in order to implement creation of DOIs. Once an account has been set up the following settings must be made in your DVN set-up:</p> +<p>Update your database with the following query:</p> +<p>Use <tt class="docutils literal"><span class="pre">psql</span></tt> or <tt class="docutils literal"><span class="pre">pgAdmin</span></tt> to execute the following SQL command: +<tt class="docutils literal"><span class="pre">update</span> <span class="pre">vdcnetwork</span> <span class="pre">set</span> <span class="pre">handleregistration=true,</span> <span class="pre">protocol</span> <span class="pre">=</span> <span class="pre">'doi',</span> <span class="pre">authority='<the</span> <span class="pre">namespace</span> <span class="pre">associated</span> <span class="pre">with</span> <span class="pre">your</span> <span class="pre">EZID</span> <span class="pre">account></span> <span class="pre">where</span> <span class="pre">id</span> <span class="pre">=</span> <span class="pre">0;</span></tt></p> +<p>Add the following JVM options:</p> +<p><tt class="docutils literal"><span class="pre">-Ddoi.username=<username</span> <span class="pre">of</span> <span class="pre">your</span> <span class="pre">EZID</span> <span class="pre">account></span></tt></p> +<p><tt class="docutils literal"><span class="pre">-Ddoi.password=<password</span> <span class="pre">of</span> <span class="pre">your</span> <span class="pre">EZID</span> <span class="pre">account></span></tt></p> +<p><tt class="docutils literal"><span class="pre">-Ddoi.baseurlstring=https://ezid.cdlib.org</span></tt></p> +<p>Note: The DVN app comes bundled with the EZID API client libraries. You do not need to install these separately.</p> +</div> +</div> +<div class="section" id="appendix"> +<h2>Appendix<a class="headerlink" href="#appendix" title="Permalink to this headline">¶</a></h2> +<div class="section" id="do-you-need-r"> +<span id="id6"></span><h3>Do you need R?<a class="headerlink" href="#do-you-need-r" title="Permalink to this headline">¶</a></h3> +<p>This is a more detailed explanation of the statement made earlier in the “Prerequisites” section: “Only the advanced modes of serving quantitative data to the users require R.” <tt class="docutils literal"><span class="pre">[style?]</span></tt></p> +<p>In this context, by “quantitative data” we mean data sets for which +machine-readable, variable-level metadata has been defined in the DVN +database. “Subsettable data” is another frequently used term, in the +DVN parlance. The currently supported sources of subsettable data are +SPSS and STATA files, as well as row tabulated or CSV files, with +extra control cards defining the data structure and variable +metadata. (See full documentation in User Guide for <a class="reference internal" href="dataverse-user-main.html#finding-and-using-data"><em>Finding and Using Data</em></a></p> +<p>Once a “subsettable” data set is create, users can run online statistics and analysis on it. That’s where R is used. In our experience, most of the institutions who have installed the DVN did so primarily in order to share and process quantitative data. When this is the case, R must be considered a required component. But a DVN network built to serve a collection of strictly human-readable (text, image, etc.) data, R will not be necessary at all.</p> +</div> +<div class="section" id="what-does-the-installer-do"> +<span id="what-does-the-intstaller-do"></span><h3>What does the Installer do?<a class="headerlink" href="#what-does-the-installer-do" title="Permalink to this headline">¶</a></h3> +<p>The Installer script (chapters Quick Install, Running the Installer.) automates the following tasks:</p> +<ol class="arabic simple"> +<li>Checks the system for required components;</li> +<li>Prompts the user for the following information:<ol class="loweralpha"> +<li>Location of the Glassfish directory;</li> +<li>Access information (host, port, database name, username, password) for PostgresQL;</li> +<li>Access information (host, port, username, password) for Rserve;</li> +</ol> +</li> +<li>Attempts to create the PostgreSQL user (role) and database, from <a class="reference internal" href="#postgresql"><em>prerequisiste PostgreSQL setup step</em></a> above; see the <a class="reference internal" href="#postgresql-setup"><em>“PostgreSQL configuration”</em></a> Appendix section for details.</li> +<li>Using the <a class="reference internal" href="#glassfish-configuration-template"><em>Glassfish configuration template (section the Appendix)</em></a> and the information collected in step 2.b. above, creates the config file domain.xml and installs it the Glassfish domain directory.</li> +<li>Copies additional configuration files (supplied in the dvninstall/config directory of the Installer package) into the config directory of the Glassfish domain.</li> +<li>Installs Glassfish Postgres driver (supplied in the dvninstall/pgdriver directory of the Installer package) into the lib directory in the Glassfish installation tree.</li> +<li>Attempts to start Glassfish. The config file at this point contains the configuration settings that the DVN will need to run (see section <a class="reference internal" href="#glassfish-configuration-individual-settings"><em>Glassfish Configuration, individual settings section</em></a> of the Appendix), but otherwise it is a “virgin”, fresh config. Glassfish will perform some initialization tasks on this first startup and deploy some internal apps.</li> +<li>If step 5. succeeds, the Installer attempts to deploy the DVN application (the Java archive DVN-EAR.ear supplied with the installer).</li> +<li>Stops Glassfish, populates the DVN database with the initial content (section <a class="reference internal" href="#postgresql-setup"><em>“PostgreSQL configuration”</em></a>” of the Appendix), starts Glassfish.</li> +<li>Attempts to establish connection to Rserve, using the access information obtained during step 2.c. If this fails, prints a warning message and points the user to the Prerequisites section of this guide where R installation is discussed.</li> +<li>Finally, prints a message informing the user that their new DVN should be up and running, provides them with the server URL and suggests that they visit it, to change the default passwords and perhaps start setting up their Dataverse Network.</li> +</ol> +<p>Throughout the steps above, the Installer attempts to diagnose any +potential issues and give the user clear error messages when things go +wrong (“version of Postgres too old”, “you must run this as root”, +etc.).</p> +<p>Enough information is supplied in this manual to enable a user (a +skilled and rather patient user, we may add) to perform all the steps +above without the use of the script.</p> +</div> +<div class="section" id="glassfish-configuration-template"> +<span id="id7"></span><h3>Glassfish configuration template<a class="headerlink" href="#glassfish-configuration-template" title="Permalink to this headline">¶</a></h3> +<p>The configuration template (<tt class="docutils literal"><span class="pre">domain.xml.TEMPLATE</span></tt>) is part of the +installer zip package. The installer replaces the placeholder +configuration tokens (for example, <tt class="docutils literal"><span class="pre">%POSTGRES_DATABASE%</span></tt>) with the +real values provided by the user to create the Glassfish configuration +file <tt class="docutils literal"><span class="pre">domain.xml</span></tt>.</p> +<p><tt class="docutils literal"><span class="pre">[I</span> <span class="pre">was</span> <span class="pre">thinking</span> <span class="pre">of</span> <span class="pre">copy-and-pasting</span> <span class="pre">the</span> <span class="pre">entire</span> <span class="pre">template</span> <span class="pre">file</span> <span class="pre">here;</span> +<span class="pre">but</span> <span class="pre">it</span> <span class="pre">is</span> <span class="pre">30K</span> <span class="pre">of</span> <span class="pre">XML,</span> <span class="pre">so</span> <span class="pre">I</span> <span class="pre">decided</span> <span class="pre">not</span> <span class="pre">to.</span> <span class="pre">The</span> <span class="pre">above</span> <span class="pre">explains</span> <span class="pre">where</span> <span class="pre">it</span> +<span class="pre">can</span> <span class="pre">be</span> <span class="pre">found,</span> <span class="pre">if</span> <span class="pre">anyone</span> <span class="pre">wants</span> <span class="pre">to</span> <span class="pre">look</span> <span class="pre">at</span> <span class="pre">it,</span> <span class="pre">for</span> <span class="pre">reference</span> <span class="pre">or</span> +<span class="pre">whatever]</span></tt></p> +</div> +<div class="section" id="glassfish-configuration-individual-settings"> +<span id="id8"></span><h3>Glassfish Configuration, individual settings<a class="headerlink" href="#glassfish-configuration-individual-settings" title="Permalink to this headline">¶</a></h3> +<p>As explained earlier in the Appendix, the Installer configures Glassfish +by cooking a complete domain configuration file (<tt class="docutils literal"><span class="pre">domain.xml</span></tt>) and +installing it in the domain directory.</p> +<p>All of the settings and options however can be configured individually +by an operator, using the Glassfish Admin Console.</p> +<p>The Console can be accessed at the network port 4848 when Glassfish is +running, by pointing a browser at</p> +<blockquote> +<div><tt class="docutils literal"><span class="pre">http://[your</span> <span class="pre">host</span> <span class="pre">name]:4848/</span></tt></div></blockquote> +<p>and logging in as <tt class="docutils literal"><span class="pre">admin</span></tt>. The initial password is <tt class="docutils literal"><span class="pre">adminadmin</span></tt>. It +is of course strongly recommended to log in and change it first thing +after you run the Installer.</p> +<p>The sections below describe all the configuration settings that would +need to be done through the GUI in order to replicate the configuration +file produced by the Installer. This information is provided for the +benefit of an advanced user who may want to experiment with individual +options. Or to attempt to install DVN on a platform not supported by our +installer; although we wish sincerely that nobody is driven to such +desperate measures ever.</p> +<div class="section" id="jvm-options"> +<span id="id9"></span><h4>JVM options<a class="headerlink" href="#jvm-options" title="Permalink to this headline">¶</a></h4> +<p>Under Application Server->JVM Settings->JVM Options:</p> +<p>If you are installing Glassfish in a production environment, follow +these steps:</p> +<ol class="arabic"> +<li><div class="first line-block"> +<div class="line">Delete the following options: -Dsun.rmi.dgc.server.gcInterval=3600000</div> +<div class="line">-Dsun.rmi.dgc.client.gcInterval=3600000</div> +</div> +</li> +<li><div class="first line-block"> +<div class="line">Add the following options:</div> +<div class="line">-XX:MaxPermSize=192m</div> +<div class="line">-XX:+AggressiveHeap</div> +<div class="line">-Xss128l</div> +<div class="line">-XX:+DisableExplicitGC</div> +<div class="line">-Dcom.sun.enterprise.ss.ASQuickStartup=false</div> +</div> +</li> +<li><div class="first line-block"> +<div class="line">To install on a multi-processor machine, add the following:</div> +<div class="line"><tt class="docutils literal"><span class="pre">-XX:+UseParallelOldGC</span></tt></div> +</div> +</li> +<li><div class="first line-block"> +<div class="line">To enable the optional HANDLE.NET installation and provide access to</div> +<div class="line">study ID registration, add the following (see the “Handles System”</div> +<div class="line">section in the “Optional Components” for</div> +<div class="line">details):</div> +<div class="line"><tt class="docutils literal"><span class="pre">-Ddvn.handle.baseUrl=<-Dataverse</span> <span class="pre">Network</span> <span class="pre">host</span> <span class="pre">URL>/dvn/study?globalId=hdl:</span></tt></div> +<div class="line"><tt class="docutils literal"><span class="pre">-Ddvn.handle.auth=<authority></span></tt></div> +<div class="line"><tt class="docutils literal"><span class="pre">-Ddvn.handle.admcredfile=/hs/svr_1/admpriv.bin</span></tt></div> +</div> +</li> +<li><div class="first line-block"> +<div class="line">To enable the optional Google Analytics option on the Network Options</div> +<div class="line">page and provide access to site usage reports, add the following (see</div> +<div class="line">the “Google Analytics” section in the “Optional Components” for</div> +<div class="line">details):</div> +<div class="line-block"> +<div class="line"><tt class="docutils literal"><span class="pre">-Ddvn.googleanalytics.key=<googleAnalyticsTrackingCode></span></tt></div> +</div> +</div> +</li> +<li><div class="first line-block"> +<div class="line">Configure the following option only if you run multiple instances</div> +<div class="line">of the GlassFish server for load balancing. This option controls</div> +<div class="line">which GlassFish instance runs scheduled jobs, such as harvest or</div> +<div class="line">export.</div> +<div class="line">For the server instance that will run scheduled jobs, include the</div> +<div class="line">following JVM option:</div> +<div class="line"><tt class="docutils literal"><span class="pre">-Ddvn.timerServer=true</span></tt></div> +<div class="line">For all other server instances, include this JVM option:</div> +<div class="line"><tt class="docutils literal"><span class="pre">-Ddvn.timerServer=false</span></tt></div> +<div class="line">If you are installing Glassfish in either a production or development</div> +<div class="line">environment, follow these steps:</div> +</div> +<ul> +<li><div class="first line-block"> +<div class="line">Change the following options’ settings:</div> +<div class="line">Change <tt class="docutils literal"><span class="pre">-client</span></tt> to <tt class="docutils literal"><span class="pre">-server</span></tt>.</div> +<div class="line">Change <tt class="docutils literal"><span class="pre">-Xmx512m</span></tt> to whatever size you can allot for the maximum</div> +<div class="line">Java heap space.</div> +<div class="line">Set `` –Xms512m`` to the same value to which you set <tt class="docutils literal"><span class="pre">–Xmx512m</span></tt>.</div> +</div> +</li> +<li><div class="first line-block"> +<div class="line">To configure permanent file storage (data and documentation files</div> +<div class="line">uploaded to studies) set the following:</div> +<div class="line"><tt class="docutils literal"><span class="pre">-Dvdc.study.file.dir=${com.sun.aas.instanceRoot}/config/files/studies</span></tt></div> +</div> +</li> +<li><div class="first line-block"> +<div class="line">To configure the temporary location used in file uploads add the</div> +<div class="line">following:</div> +<div class="line"><tt class="docutils literal"><span class="pre">-Dvdc.temp.file.dir=${com.sun.aas.instanceRoot}/config/files/temp</span></tt></div> +</div> +</li> +<li><div class="first line-block"> +<div class="line">To configure export and import logs (harvesting and importing),</div> +<div class="line">add the following:</div> +<div class="line">-Dvdc.export.log.dir=${com.sun.aas.instanceRoot}/logs/export</div> +<div class="line">-Dvdc.import.log.dir=${com.sun.aas.instanceRoot}/logs/import</div> +</div> +</li> +<li><div class="first line-block"> +<div class="line">Add the following:</div> +<div class="line">-Djhove.conf.dir=${com.sun.aas.instanceRoot}/config</div> +<div class="line">-Ddvn.inetAddress=<host or fully qualified domain name of server</div> +<div class="line">on which Dataverse Network runs></div> +<div class="line">-Ddvn.networkData.libPath=${com.sun.aas.instanceRoot}/applications/j2ee-</div> +<div class="line-block"> +<div class="line">apps/DVN-EAR</div> +</div> +</div> +</li> +<li><div class="first line-block"> +<div class="line">To manage calls to RServe and the R host (analysis and file upload), add</div> +<div class="line">the following:</div> +<div class="line"><tt class="docutils literal"><span class="pre">-Dvdc.dsb.host=<RServe</span> <span class="pre">server</span> <span class="pre">hostname></span></tt></div> +<div class="line"><tt class="docutils literal"><span class="pre">-Dvdc.dsb.rserve.user=<account></span></tt></div> +<div class="line"><tt class="docutils literal"><span class="pre">-Dvdc.dsb.rserve.pwrd=<password></span></tt></div> +<div class="line"><tt class="docutils literal"><span class="pre">-Dvdc.dsb.rserve.port=<port</span> <span class="pre">number></span></tt></div> +</div> +<div class="line-block"> +<div class="line">For Installing R, see:</div> +<div class="line"><a class="reference internal" href="#r-and-rserve"><em>R and R-Serve</em></a></div> +<div class="line">for information about configuring these values in the <tt class="docutils literal"><span class="pre">Rserv.conf</span></tt></div> +<div class="line">file.</div> +<div class="line">These settings must be configured for subsetting and analysis to</div> +<div class="line">work.</div> +</div> +</li> +<li><div class="first line-block"> +<div class="line">To configure search index files set the following:</div> +<div class="line"><tt class="docutils literal"><span class="pre">-Ddvn.index.location=${com.sun.aas.instanceRoot}/config</span></tt></div> +</div> +</li> +<li><div class="first line-block"> +<div class="line">To use the optional customized error logging and add more information</div> +<div class="line">to your log files, set the following:</div> +<div class="line"><tt class="docutils literal"><span class="pre">-Djava.util.logging.config.file=</span> <span class="pre">${com.sun.aas.instanceRoot}</span> <span class="pre">/config/logging.properties</span></tt></div> +<div class="line"><strong>Note</strong>: To customize the logging, edit the <tt class="docutils literal"><span class="pre">logging.properties</span></tt> file</div> +</div> +</li> +<li><div class="first line-block"> +<div class="line">The default size limit for file downloads is 100MB. To override this</div> +<div class="line">default add the following JVM option:</div> +<div class="line"><tt class="docutils literal"><span class="pre">-Ddvn.batchdownload.limit=<max</span> <span class="pre">download</span> <span class="pre">bytes></span></tt></div> +</div> +</li> +</ul> +</li> +</ol> +</div> +<div class="section" id="ejb-container"> +<h4>EJB Container<a class="headerlink" href="#ejb-container" title="Permalink to this headline">¶</a></h4> +<p>Under Configuration->EJB Container->EJB Timer Service:</p> +<ol class="arabic"> +<li><div class="first line-block"> +<div class="line">Set the Timer Datasource to the following:</div> +<div class="line"><tt class="docutils literal"><span class="pre">jdbc/VDCNetDS</span></tt></div> +</div> +</li> +<li><div class="first line-block"> +<div class="line">Save the configuration.</div> +</div> +</li> +</ol> +</div> +<div class="section" id="http-service"> +<h4>HTTP Service<a class="headerlink" href="#http-service" title="Permalink to this headline">¶</a></h4> +<p>The HTTP Service configuration settings described in this section are suggested defaults. These settings are very important. There are no right values to define; the values depend on the specifics of your web traffic, how many requests you get, how long they take to process on average, and your hardware. For detailed the +| Sun Microsystems Documentation web site at the following URL:</p> +<p><a class="reference external" href="http://docs.sun.com/">http://docs.sun.com/</a></p> +<div class="line-block"> +<div class="line"><strong>Note</strong>: If your server becomes so busy that it drops connections,</div> +<div class="line">adjust the Thread Counts to improve performance.</div> +</div> +<ol class="arabic"> +<li><p class="first">Under Configuration->HTTP Service->HTTP +Listeners-><tt class="docutils literal"><span class="pre">http-listener-1</span></tt>:</p> +<ul class="simple"> +<li>Listener Port: 80</li> +<li>Acceptor Threads: The number of CPUs (cores) on your server</li> +</ul> +</li> +<li><p class="first">Under Configuration->HTTP Service, in the RequestProcessing tab:</p> +<ul class="simple"> +<li>Thread Count: Four times the number of CPUs (cores) on your server</li> +<li>Initial Thread Count: The number of CPUs (cores)</li> +</ul> +</li> +<li><p class="first">Under Configuration->HTTP Service->Virtual Servers->server: add new property <tt class="docutils literal"><span class="pre">allowLinking</span></tt> with the value <tt class="docutils literal"><span class="pre">true</span></tt>.</p> +<blockquote> +<div><ol class="arabic"> +<li><div class="first line-block"> +<div class="line">Under Configuration->HTTP Service, configure Access Logging:</div> +</div> +</li> +</ol> +<div class="line-block"> +<div class="line">format=%client.name% %auth-user-name% %datetime% %request% %status%</div> +<div class="line">%response.length%</div> +<div class="line">rotation-enabled=true</div> +<div class="line">rotation-interval-in-minutes=15</div> +<div class="line">rotation-policy=time</div> +<div class="line">rotation-suffix=yyyy-MM-dd</div> +</div> +</div></blockquote> +</li> +</ol> +</div> +<div class="section" id="javamail-session"> +<h4>JavaMail Session<a class="headerlink" href="#javamail-session" title="Permalink to this headline">¶</a></h4> +<p>Under Resources->JavaMail Sessions<tt class="docutils literal"><span class="pre">->mail/notifyMailSession:</span></tt></p> +<ul> +<li><div class="first line-block"> +<div class="line">Mail Host: <tt class="docutils literal"><span class="pre"><your</span> <span class="pre">mail</span> <span class="pre">server></span></tt></div> +<div class="line"><strong>Note</strong>: The Project recommends that you install a mail server on the same machine as GlassFish and use <tt class="docutils literal"><span class="pre">localhost</span></tt> for this entry. Since email notification is used for workflow events such as creating a dataverse or study, these functions may not work properly if a valid mail server is not configured.</div> +</div> +</li> +<li><dl class="first docutils"> +<dt>Default User: <tt class="docutils literal"><span class="pre">dataversenotify</span></tt></dt> +<dd><p class="first last">This does not need to be a real mail account.</p> +</dd> +</dl> +</li> +<li><p class="first">Default Return Address: <tt class="docutils literal"><span class="pre">do-not-reply@<your</span> <span class="pre">mail</span> <span class="pre">server></span></tt></p> +</li> +</ul> +</div> +<div class="section" id="jdbc-resources"> +<h4>JDBC Resources<a class="headerlink" href="#jdbc-resources" title="Permalink to this headline">¶</a></h4> +<p><strong>Under Resources->JDBC->Connection Pools:</strong></p> +<div class="line-block"> +<div class="line">Add a new Connection Pool entry:</div> +</div> +<ul class="simple"> +<li>entryName: <tt class="docutils literal"><span class="pre">dvnDbPool</span></tt></li> +<li>Resource Type: <tt class="docutils literal"><span class="pre">javax.sql.DataSource</span></tt></li> +<li>Database Vendor: <tt class="docutils literal"><span class="pre">PostgreSQL</span></tt></li> +<li>DataSource ClassName: <tt class="docutils literal"><span class="pre">org.postgresql.ds.PGPoolingDataSource</span></tt></li> +<li>Additional Properties:<ul> +<li>ConnectionAttributes: <tt class="docutils literal"><span class="pre">;create=true</span></tt></li> +<li>User: <tt class="docutils literal"><span class="pre">dvnApp</span></tt></li> +<li>PortNumber: <tt class="docutils literal"><span class="pre">5432</span></tt> (Port 5432 is the PostgreSQL default port.)</li> +<li>Password: <tt class="docutils literal"><span class="pre"><Dataverse</span> <span class="pre">Network</span> <span class="pre">application</span> <span class="pre">database</span> <span class="pre">password></span></tt></li> +<li>DatabaseName: <tt class="docutils literal"><span class="pre"><your</span> <span class="pre">database</span> <span class="pre">name></span></tt></li> +<li>ServerName: <tt class="docutils literal"><span class="pre"><your</span> <span class="pre">database</span> <span class="pre">host></span></tt></li> +<li>JDBC30DataSource: <tt class="docutils literal"><span class="pre">true</span></tt></li> +</ul> +</li> +</ul> +<div class="line-block"> +<div class="line"><br /></div> +</div> +<p><strong>Under Resources->JDBC->JDBC Resources:</strong></p> +<div class="line-block"> +<div class="line">Add a new JDBC Resources entry:</div> +</div> +<ul class="simple"> +<li>JNDI Name: <tt class="docutils literal"><span class="pre">jdbc/VDCNetDS</span></tt></li> +<li>Pool Name: <tt class="docutils literal"><span class="pre">dvnDbPool</span></tt></li> +</ul> +</div> +<div class="section" id="jms-resources"> +<h4>JMS Resources<a class="headerlink" href="#jms-resources" title="Permalink to this headline">¶</a></h4> +<p>Under Resources->JMS Resources:</p> +<ol class="arabic simple"> +<li>Add a new Connection Factory for the DSB Queue:<ul> +<li>JNDI Name: <tt class="docutils literal"><span class="pre">jms/DSBQueueConnectionFactory</span></tt></li> +<li>Resource Type: <tt class="docutils literal"><span class="pre">javax.jms.QueueConnectionFactory</span></tt></li> +</ul> +</li> +<li>Add a new Connection Factory for the Index Message:<ul> +<li>JNDI Name: <tt class="docutils literal"><span class="pre">jms/IndexMessageFactory</span></tt></li> +<li>Resource Type: <tt class="docutils literal"><span class="pre">javax.jms.QueueConnectionFactory</span></tt></li> +</ul> +</li> +<li>Add a new Destination Resource for the DSB Queue:<ul> +<li>JNDI Name: <tt class="docutils literal"><span class="pre">jms/DSBIngest</span></tt></li> +<li>Physical Destination Name: <tt class="docutils literal"><span class="pre">DSBIngest</span></tt></li> +<li>Resource Type: <tt class="docutils literal"><span class="pre">javax.jms.Queue</span></tt></li> +</ul> +</li> +<li>Add a new Destination Resource for the Index Message:<ul> +<li>JNDI Name: <tt class="docutils literal"><span class="pre">jms/IndexMessage</span></tt></li> +<li>Physical Destination Name: <tt class="docutils literal"><span class="pre">IndexMessage</span></tt></li> +<li>Resource Type: <tt class="docutils literal"><span class="pre">javax.jms.Queue</span></tt></li> +</ul> +</li> +</ol> +</div> +</div> +<div class="section" id="postgresql-setup"> +<span id="id10"></span><h3>PostgreSQL setup<a class="headerlink" href="#postgresql-setup" title="Permalink to this headline">¶</a></h3> +<p>The following actions are normally performed by the automated installer +script. These steps are explained here for reference, and/or in case +your need to perform them manually:</p> +<ol class="arabic"> +<li><p class="first">Start as root, then change to user postgres:</p> +<p><tt class="docutils literal"><span class="pre">su</span> <span class="pre">postgres</span></tt></p> +</li> +</ol> +<blockquote> +<div><p>Create DVN database usert (role):</p> +<p><tt class="docutils literal"><span class="pre">createuser</span> <span class="pre">-SrdPE</span> <span class="pre">[DB_USERNAME]</span></tt></p> +<p>(you will be prompted to choose a user password).</p> +<p>Create DVN database:</p> +<p><tt class="docutils literal"><span class="pre">createdb</span> <span class="pre">[DB_NAME]</span> <span class="pre">--owner=[DB_USERNAME]</span></tt></p> +<p><tt class="docutils literal"><span class="pre">[DB_NAME]</span></tt> and <tt class="docutils literal"><span class="pre">[USER_NAME]</span></tt> are the names you choose for your DVN database and database user. These, together with the password you have assigned, will be used in the Glassfish configuration so that the application can talk to the database.</p> +</div></blockquote> +<ol class="arabic simple" start="2"> +<li>Before Glassfish can be configured for the DVN app, the Postgres driver needs to be installed in the <GLASSFISH ROOT>/lib directory. We supply a version of the driver known to work with the DVN in the dvninstall/pgdriver directory of the Installer bundle. (This is the <a class="reference internal" href="#what-does-the-intstaller-do"><em>“What does the Installer do?”</em></a> section of this appendix) An example of the installed location of the driver:</li> +</ol> +<blockquote> +<div><tt class="docutils literal"><span class="pre">/usr/local/glassfish/lib/postgresql-8.3-603.jdbc4.jar</span></tt></div></blockquote> +<ol class="arabic simple" start="3"> +<li>Finally, after the DVN application is deployed under Glassfish for the first time, the database needs to be populated with the initial content:</li> +</ol> +<blockquote> +<div><p><tt class="docutils literal"><span class="pre">su</span> <span class="pre">postgres</span></tt> +<tt class="docutils literal"><span class="pre">psql</span> <span class="pre">-d</span> <span class="pre">[DB_NAME]</span> <span class="pre">-f</span> <span class="pre">referenceData.sql</span></tt></p> +<p>The file referenceData.sql is provided as part of the installer zip package.</p> +</div></blockquote> +</div> +<div class="section" id="redhat-startup-file-for-glassfish-example"> +<h3>RedHat startup file for glassfish, example<a class="headerlink" href="#redhat-startup-file-for-glassfish-example" title="Permalink to this headline">¶</a></h3> +<p>Below is an example of a glassfish startup file that you may want to +install on your RedHat (or similar) system to have glassfish start +automatically on boot.</p> +<div class="line-block"> +<div class="line">Install the file as <tt class="docutils literal"><span class="pre">/etc/init.d/glassfish</span></tt>, then run <tt class="docutils literal"><span class="pre">chkconfig</span> <span class="pre">glassfish</span> <span class="pre">on</span></tt></div> +</div> +<p>Note that the extra configuration steps before the domain start line, +for increasing the file limit and allowing “memory overcommit”. These +are useful settings to have on a production server.</p> +<div class="line-block"> +<div class="line">You may of course add extra custom configuration specific to your +setup.</div> +</div> +<div class="highlight-guess"><div class="highlight"><pre><span class="c">#! /bin/sh</span> +<span class="c"># chkconfig: 2345 99 01</span> +<span class="c"># description: GlassFish App Server</span> +<span class="nb">set</span> -e +<span class="nv">ASADMIN</span><span class="o">=</span>/usr/local/glassfish/bin/asadmin +<span class="k">case</span> <span class="s2">"$1"</span> in + start<span class="o">)</span> + <span class="nb">echo</span> -n <span class="s2">"Starting GlassFish server: glassfish"</span> + <span class="c"># Increase file descriptor limit:</span> + <span class="nb">ulimit</span> -n 32768 + <span class="c"># Allow "memory overcommit":</span> + <span class="c"># (basically, this allows to run exec() calls from inside the</span> + <span class="c"># app, without the Unix fork() call physically hogging 2X</span> + <span class="c"># the amount of memory glassfish is already using)</span> + <span class="nb">echo </span>1 > /proc/sys/vm/overcommit_memory + <span class="nv">$ASADMIN</span> start-domain domain1 <span class="nb">echo</span> <span class="s2">"."</span> + ;; + stop<span class="o">)</span> + <span class="nb">echo</span> -n <span class="s2">"Stopping GlassFish server: glassfish"</span> + <span class="nv">$ASADMIN</span> stop-domain domain1 + <span class="nb">echo</span> <span class="s2">"."</span> + ;; + *<span class="o">)</span> + <span class="nb">echo</span> <span class="s2">"Usage: /etc/init.d/glassfish {start|stop}"</span> + + <span class="nb">exit </span>1 +<span class="k">esac</span> +<span class="nb">exit </span>0 +</pre></div> +</div> +</div> +<div class="section" id="enabling-secure-remote-access-to-asadmin"> +<h3>Enabling secure remote access to Asadmin<a class="headerlink" href="#enabling-secure-remote-access-to-asadmin" title="Permalink to this headline">¶</a></h3> +<p>As was mentioned in the Glassfish section of the manual, in version +3.1.2 admin interface (asadmin) is configured to be accessible on the +localhost interface only. If you need to be able to access the admin +console remotely, you will have to enable secure access to it. (It will +be accessible over https only, at <tt class="docutils literal"><span class="pre">https://<YOUR</span> <span class="pre">HOST>:4848</span></tt>; connections +to <tt class="docutils literal"><span class="pre">http://<YOUR</span> <span class="pre">HOST>:4848</span></tt> will be automatically redirected to the https +interface)</p> +<p>The following must be done as root:</p> +<ol class="arabic"> +<li><p class="first">First you need to configure the admin password:</p> +<p><tt class="docutils literal"><span class="pre"><GF</span> <span class="pre">LOCATION>/glassfish3/bin/asadmin</span> <span class="pre">change-admin-password</span></tt></p> +<p>(since you didn’t create one when you were installing Glassfish, leave the “current password” blank, i.e., hit ENTER)</p> +</li> +<li><p class="first">Enable the secure access:</p> +</li> +</ol> +<blockquote> +<div><p><tt class="docutils literal"><span class="pre"><GF</span> <span class="pre">LOCATION>/glassfish3/bin/asadmin</span> <span class="pre">enable-secure-admin</span></tt></p> +<p>(Note that you will need to restart Glassfish after step 2. above)</p> +</div></blockquote> +</div> +<div class="section" id="using-lockss-with-dvn"> +<span id="id11"></span><h3>Using LOCKSS with DVN<a class="headerlink" href="#using-lockss-with-dvn" title="Permalink to this headline">¶</a></h3> +<p>DVN holdings can be crawled by LOCKSS servers (<a class="reference external" href="http://www.lockss.org">www.lockss.org</a>). It is made possible by the special plugin developed and maintained by the DVN project, which a LOCKSS daemon utilizes to crawl and access materials served by a Dataverse network.</p> +<p>The current stable version of the plugin is available at the following location:</p> +<p><a class="reference external" href="http://lockss.hmdc.harvard.edu/lockss/plugin/DVNOAIPlugin.jar">http://lockss.hmdc.harvard.edu/lockss/plugin/DVNOAIPlugin.jar</a></p> +<p>As of January 2013 and DVN version 3.3, the plugin is compatible with the LOCKSS daemon version 1.55. The plugin sources can be found in the main DVN source tree in <a class="reference external" href="https://dvn.svn.sourceforge.net/svnroot/dvn/dvn-app/trunk/src/DVN-lockss">https://dvn.svn.sourceforge.net/svnroot/dvn/dvn-app/trunk/src/DVN-lockss</a> (please note that the DVN project is currently <strong>in the process of moving to gitHub!</strong> The preserved copy of the 3.3 source will be left at the URL above, together with the information on the current location of the source repository).</p> +<p>In order to crawl a DVN, the following steps need to be performed:</p> +<ol class="arabic"> +<li><p class="first">Point your LOCKSS daemon to the plugin repository above. (Refer to the LOCKSS documentation for details);</p> +</li> +<li><p class="first">Create a LOCKSS Archival Unit for your target DVN:</p> +<p>In the LOCKSS Admin Console, go to <strong>Journal Configuration</strong> -> <strong>Manual Add/Edit</strong> and click on <strong>Add Archival Unit</strong>.</p> +<p>On the next form, select <strong>DVNOAI</strong> in the pull down menu under <strong>Choose a publisher plugin</strong> and click <strong>Continue</strong>.</p> +<p>Next configure the parameters that define your DVN Archival Unit. LOCKSS daemon can be configured to crawl either the entire holdings of a DVN (no OAI set specified), or a select Dataverse.</p> +</li> +</ol> +<p>Note that LOCKSS crawling must be authorized on the DVN side. Refer to +the <a class="reference internal" href="dataverse-user-main.html#edit-lockss-harvest-settings"><em>“Edit LOCKSS Settings”</em></a> +section of the DVN Network Administrator Guide for the instructions on +enabling LOCKSS crawling on the network level, and/or to the +<a class="reference internal" href="dataverse-user-main.html#enabling-lockss-access-to-the-dataverse"><em>Enabling LOCKSS access to the Dataverse</em></a> +of the Dataverse Administration Guide. Once you allow LOCKSS crawling of +your Dataverse(s), you will need to enter the URL of the “LOCKSS +Manifest” page provided by the DVN in the configuration above. For the +network-wide archival unit this URL will be +<tt class="docutils literal"><span class="pre">http</span></tt><tt class="docutils literal"><span class="pre">://<YOUR</span> <span class="pre">SERVER>/dvn/faces/ManifestPage.xhtml</span></tt>; for an +individual dataverse it is +<tt class="docutils literal"><span class="pre">http</span></tt><tt class="docutils literal"><span class="pre">://<YOUR</span> <span class="pre">SERVER>/dvn/dv/<DV</span> <span class="pre">ALIAS>/faces/ManifestPage.xhtml.</span></tt></p> +<div class="line-block"> +<div class="line">The URL of the DVN OAI server is <tt class="docutils literal"><span class="pre">http</span></tt><tt class="docutils literal"><span class="pre">://<YOUR</span> <span class="pre">DVN</span> <span class="pre">HOST>/dvn/OAIHandler</span></tt>.</div> +</div> +</div> +<div class="section" id="read-only-mode"> +<h3>Read Only Mode<a class="headerlink" href="#read-only-mode" title="Permalink to this headline">¶</a></h3> +<p>A Read Only Mode has been established in DVN to allow the application to remain available while deploying new versions or patches. Users will be able to view data and metadata, but will not be able to add or edit anything. Currently there is no way to switch to Read Only Mode through the application. +In order to change the application mode you must apply the following queries through <tt class="docutils literal"><span class="pre">psql</span></tt> or <tt class="docutils literal"><span class="pre">pgAdmin</span></tt>:</p> +<p>To set to Read Only Mode:</p> +<blockquote> +<div><div class="line-block"> +<div class="line"><tt class="docutils literal"><span class="pre">BEGIN;</span></tt></div> +<div class="line"><tt class="docutils literal"><span class="pre">SET</span> <span class="pre">TRANSACTION</span> <span class="pre">READ</span> <span class="pre">WRITE;</span></tt></div> +<div class="line"><tt class="docutils literal"><span class="pre">--</span> <span class="pre">Note</span> <span class="pre">database</span> <span class="pre">and</span> <span class="pre">user</span> <span class="pre">strings</span> <span class="pre">may</span> <span class="pre">have</span> <span class="pre">to</span> <span class="pre">be</span> <span class="pre">modified</span> <span class="pre">for</span> <span class="pre">your</span> <span class="pre">particular</span> <span class="pre">installation;</span></tt></div> +<div class="line"><tt class="docutils literal"><span class="pre">--</span> <span class="pre">You</span> <span class="pre">may</span> <span class="pre">also</span> <span class="pre">customize</span> <span class="pre">the</span> <span class="pre">status</span> <span class="pre">notice</span> <span class="pre">which</span> <span class="pre">will</span> <span class="pre">appear</span> <span class="pre">on</span> <span class="pre">all</span> <span class="pre">pages</span> <span class="pre">of</span> <span class="pre">the</span> <span class="pre">application;</span></tt></div> +<div class="line"><tt class="docutils literal"><span class="pre">update</span> <span class="pre">vdcnetwork</span> <span class="pre">set</span> <span class="pre">statusnotice</span> <span class="pre">=</span> <span class="pre">"This</span> <span class="pre">network</span> <span class="pre">is</span> <span class="pre">currently</span> <span class="pre">in</span> <span class="pre">Read</span> <span class="pre">Only</span> <span class="pre">state.</span> <span class="pre">No</span> <span class="pre">saving</span> <span class="pre">of</span> <span class="pre">data</span> <span class="pre">will</span> <span class="pre">be</span> <span class="pre">allowed.";</span></tt></div> +<div class="line"><tt class="docutils literal"><span class="pre">ALTER</span> <span class="pre">DATABASE</span> <span class="pre">"dvnDb"</span> <span class="pre">set</span> <span class="pre">default_transaction_read_only=on;</span></tt></div> +<div class="line"><tt class="docutils literal"><span class="pre">Alter</span> <span class="pre">user</span> <span class="pre">"dvnApp"</span> <span class="pre">set</span> <span class="pre">default_transaction_read_only=on;</span></tt></div> +<div class="line"><tt class="docutils literal"><span class="pre">update</span> <span class="pre">vdcnetwork</span> <span class="pre">set</span> <span class="pre">statusnotice</span> <span class="pre">=</span> <span class="pre">"";</span></tt></div> +<div class="line"><tt class="docutils literal"><span class="pre">END;</span></tt></div> +</div> +</div></blockquote> +<p>To return to regular service:</p> +<blockquote> +<div><div class="line-block"> +<div class="line"><tt class="docutils literal"><span class="pre">BEGIN;</span></tt></div> +<div class="line"><tt class="docutils literal"><span class="pre">SET</span> <span class="pre">TRANSACTION</span> <span class="pre">READ</span> <span class="pre">WRITE;</span></tt></div> +<div class="line"><tt class="docutils literal"><span class="pre">--</span> <span class="pre">Note</span> <span class="pre">database</span> <span class="pre">and</span> <span class="pre">user</span> <span class="pre">strings</span> <span class="pre">may</span> <span class="pre">have</span> <span class="pre">to</span> <span class="pre">be</span> <span class="pre">modified</span> <span class="pre">for</span> <span class="pre">your</span> <span class="pre">particular</span> <span class="pre">installation;</span></tt></div> +<div class="line"><tt class="docutils literal"><span class="pre">ALTER</span> <span class="pre">DATABASE</span> <span class="pre">"dvnDb"</span> <span class="pre">set</span> <span class="pre">default_transaction_read_only=off;</span></tt></div> +<div class="line"><tt class="docutils literal"><span class="pre">Alter</span> <span class="pre">user</span> <span class="pre">"dvnApp"</span> <span class="pre">set</span> <span class="pre">default_transaction_read_only=off;</span></tt></div> +<div class="line"><tt class="docutils literal"><span class="pre">update</span> <span class="pre">vdcnetwork</span> <span class="pre">set</span> <span class="pre">statusnotice</span> <span class="pre">=</span> <span class="pre">"";</span></tt></div> +<div class="line"><tt class="docutils literal"><span class="pre">END;</span></tt></div> +</div> +</div></blockquote> +</div> +<div class="section" id="backup-and-restore"> +<h3>Backup and Restore<a class="headerlink" href="#backup-and-restore" title="Permalink to this headline">¶</a></h3> +<p><strong>Backup</strong></p> +<div class="line-block"> +<div class="line">The PostgreSQL database and study files (contained within the Glassfish directory by default but this is <a class="reference internal" href="#jvm-options"><em>configurable via JVM options</em></a>) are the most critical components to back up. The use of standard PostgreSQL tools (i.e. pg_dump) is recommended.</div> +</div> +<p>Glassfish configuration files (i.e. domain.xml, robots.txt) and local +customizations (i.e. images in the docroot) should be backed up as well. +In practice, it is best to simply back up the entire Glassfish directory +as other files such as logs may be of interest.</p> +<div class="line-block"> +<div class="line"><strong>Restore</strong></div> +</div> +<p>Restoring DVN consists of restoring the PostgreSQL database and the +Glassfish directory.</p> +</div> +</div> +</div> + + + </div> + </div> + </div> + </div> + <div class="sidebar"> + <h3>Table Of Contents</h3> + <ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="dataverse-user-main.html">User Guide</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="">Installers Guide</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#quick-install">Quick Install</a></li> +<li class="toctree-l2"><a class="reference internal" href="#system-requirements">SYSTEM REQUIREMENTS</a></li> +<li class="toctree-l2"><a class="reference internal" href="#prerequisites">PREREQUISITES</a><ul> +<li class="toctree-l3"><a class="reference internal" href="#glassfish">Glassfish</a></li> +<li class="toctree-l3"><a class="reference internal" href="#postgresql">PostgreSQL</a></li> +<li class="toctree-l3"><a class="reference internal" href="#r-and-rserve">R and RServe</a></li> +<li class="toctree-l3"><a class="reference internal" href="#system-configuration">System Configuration</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="#running-the-installer">RUNNING THE INSTALLER</a></li> +<li class="toctree-l2"><a class="reference internal" href="#optional-components">Optional Components</a><ul> +<li class="toctree-l3"><a class="reference internal" href="#recaptcha-bot-blocker">reCAPTCHA bot blocker</a></li> +<li class="toctree-l3"><a class="reference internal" href="#google-analytics">Google Analytics</a></li> +<li class="toctree-l3"><a class="reference internal" href="#imagemagick">ImageMagick</a></li> +<li class="toctree-l3"><a class="reference internal" href="#handle-system">Handle System</a></li> +<li class="toctree-l3"><a class="reference internal" href="#twitter-setup">Twitter setup</a></li> +<li class="toctree-l3"><a class="reference internal" href="#digital-object-identifiers">Digital Object Identifiers</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="#appendix">Appendix</a><ul> +<li class="toctree-l3"><a class="reference internal" href="#do-you-need-r">Do you need R?</a></li> +<li class="toctree-l3"><a class="reference internal" href="#what-does-the-installer-do">What does the Installer do?</a></li> +<li class="toctree-l3"><a class="reference internal" href="#glassfish-configuration-template">Glassfish configuration template</a></li> +<li class="toctree-l3"><a class="reference internal" href="#glassfish-configuration-individual-settings">Glassfish Configuration, individual settings</a><ul> +<li class="toctree-l4"><a class="reference internal" href="#jvm-options">JVM options</a></li> +<li class="toctree-l4"><a class="reference internal" href="#ejb-container">EJB Container</a></li> +<li class="toctree-l4"><a class="reference internal" href="#http-service">HTTP Service</a></li> +<li class="toctree-l4"><a class="reference internal" href="#javamail-session">JavaMail Session</a></li> +<li class="toctree-l4"><a class="reference internal" href="#jdbc-resources">JDBC Resources</a></li> +<li class="toctree-l4"><a class="reference internal" href="#jms-resources">JMS Resources</a></li> +</ul> +</li> +<li class="toctree-l3"><a class="reference internal" href="#postgresql-setup">PostgreSQL setup</a></li> +<li class="toctree-l3"><a class="reference internal" href="#redhat-startup-file-for-glassfish-example">RedHat startup file for glassfish, example</a></li> +<li class="toctree-l3"><a class="reference internal" href="#enabling-secure-remote-access-to-asadmin">Enabling secure remote access to Asadmin</a></li> +<li class="toctree-l3"><a class="reference internal" href="#using-lockss-with-dvn">Using LOCKSS with DVN</a></li> +<li class="toctree-l3"><a class="reference internal" href="#read-only-mode">Read Only Mode</a></li> +<li class="toctree-l3"><a class="reference internal" href="#backup-and-restore">Backup and Restore</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="dataverse-developer-main.html">DVN Developers Guide</a></li> +<li class="toctree-l1"><a class="reference internal" href="dataverse-api-main.html">APIs Guide</a></li> +</ul> + + <h3 style="margin-top: 1.5em;">Search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms. + </p> + </div> + <div class="clearer"></div> + </div> + </div> + + <div class="footer-wrapper"> + <div class="footer"> + <div class="left"> + <a href="dataverse-user-main.html" title="User Guide" + >previous</a> | + <a href="dataverse-developer-main.html" title="DVN Developers Guide" + >next</a> | + <a href="genindex.html" title="General Index" + >index</a> + <br/> + <a href="_sources/dataverse-installer-main.txt" + rel="nofollow">Show Source</a> + </div> + + <div class="right"> + + <div class="footer"> + © Copyright 1997-2013, President & Fellows Harvard University. + Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1. + </div> + </div> + <div class="clearer"></div> + </div> + </div> + + </body> +</html> \ No newline at end of file