comparison 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
comparison
equal deleted inserted replaced
5:dd9adfc73390 6:1b2188262ae9
1
2
3 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
6
7 <html xmlns="http://www.w3.org/1999/xhtml">
8 <head>
9 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
10
11 <title>Installers Guide &mdash; The Harvard Dataverse Network 3.6.1 documentation</title>
12
13 <link rel="stylesheet" href="_static/agogo.css" type="text/css" />
14 <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
15
16 <script type="text/javascript">
17 var DOCUMENTATION_OPTIONS = {
18 URL_ROOT: './',
19 VERSION: '3.6.1',
20 COLLAPSE_INDEX: false,
21 FILE_SUFFIX: '.html',
22 HAS_SOURCE: true
23 };
24 </script>
25 <script type="text/javascript" src="_static/jquery.js"></script>
26 <script type="text/javascript" src="_static/underscore.js"></script>
27 <script type="text/javascript" src="_static/doctools.js"></script>
28 <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
29 <link rel="top" title="The Harvard Dataverse Network 3.6.1 documentation" href="index.html" />
30 <link rel="next" title="DVN Developers Guide" href="dataverse-developer-main.html" />
31 <link rel="prev" title="User Guide" href="dataverse-user-main.html" />
32 </head>
33 <body>
34 <div class="header-wrapper">
35 <div class="header">
36 <div class="headertitle"><a
37 href="index.html">The Harvard Dataverse Network 3.6.1 documentation</a></div>
38 <div class="rel">
39 <a href="dataverse-user-main.html" title="User Guide"
40 accesskey="P">previous</a> |
41 <a href="dataverse-developer-main.html" title="DVN Developers Guide"
42 accesskey="N">next</a> |
43 <a href="genindex.html" title="General Index"
44 accesskey="I">index</a>
45 </div>
46 </div>
47 </div>
48
49 <div class="content-wrapper">
50 <div class="content">
51 <div class="document">
52
53 <div class="documentwrapper">
54 <div class="bodywrapper">
55 <div class="body">
56
57 <div class="section" id="installers-guide">
58 <h1>Installers Guide<a class="headerlink" href="#installers-guide" title="Permalink to this headline">¶</a></h1>
59 <p id="introduction"><strong>Introduction</strong></p>
60 <p>This is our &#8220;new and improved&#8221; installation guide, it was first
61 released with the Dataverse Network application versions 2.2.4, when we
62 introduced the new, automated and much simplified installation process.
63 As of February 2012, it has been updated to reflect the changes made in
64 the newly released version 3.0 of the software. (Our existing users will
65 notice however, that the changes in the installation process have been
66 fairly minimal).</p>
67 <p>The guide is intended for anyone who needs to install the DVN app,
68 developers and Dataverse Network administrators alike.</p>
69 <p>The top-down organization of the chapters and sections is that of
70 increasing complexity. First a very basic, simple installation scenario
71 is presented. The instructions are straightforward and only the required
72 components are discussed. This use case will in fact be sufficient for
73 most DVN developers and many Dataverse Network administrators. Chances
74 are you are one of such users, so if brave by nature, you may stop
75 reading this section and go straight to the <a class="reference internal" href="#quick-install"><em>“Quick Install”</em></a> chapter.</p>
76 <p>The “basic” installation process described in the first chapter is
77 fully automated, everything is performed by a single interactive script.
78 This process has its limitations. It will likely work only on the
79 supported platforms. Optional components need to be configured outside
80 of the Installer (these are described in the &#8220;Optional Components&#8221;
81 section).</p>
82 <p>For an advanced user, we provide the detailed explanations of all the
83 steps performed by the Installer. This way he or she can experiment with
84 individual configuration options, having maximum flexibility and control
85 over the process. Yet we tried to organize the advanced information in
86 such a way that those who only need the most basic instructions would
87 not have to read through it unnecessarily. Instead we provide them with
88 an easy way to get a bare-bones configuration of the DVN up and running.</p>
89 <p>If you are interested in practicing a DVN installation in a Vagrant
90 environment you can later throw away, please follow the instructions at
91 <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
92 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
93 this temporary DVN installation, you can delete the virtual machine with
94 <tt class="docutils literal"><span class="pre">vagrant</span> <span class="pre">destroy</span></tt>.</p>
95 <p>If you encounter any problems during installation, please contact the
96 development team
97 at <a class="reference external" href="mailto:support&#37;&#52;&#48;thedata&#46;org">support<span>&#64;</span>thedata<span>&#46;</span>org</a>
98 or our <a class="reference external" href="https://groups.google.com/forum/?fromgroups#!forum/dataverse-community">Dataverse Users
99 Community</a>.</p>
100 <div class="section" id="quick-install">
101 <span id="id1"></span><h2>Quick Install<a class="headerlink" href="#quick-install" title="Permalink to this headline">¶</a></h2>
102 <p>For an experienced and/or rather bold user, this is a 1
103 paragraph version of the installation instructions:</p>
104 <p>This should work on RedHat and its derivatives, and MacOS X. If this
105 does not describe your case, you will very likely have to install and
106 configure at least some of the components manually. Meaning, you may
107 consider reading through the chapters that follow! Still here? Great.
108 Prerequisites: Sun/Oracle Java JDK 1.6_31+ and a “virgin” installation
109 of Glassfish v3.1.2; PostgreSQL v8.3+, configured to listen to network
110 connections and support password authentication on the localhost
111 interface; you may need R as well. See the corresponding sections under
112 “2. Prerequisites”, if necessary. Download the installer package from
113 SourceForge:</p>
114 <p><a class="reference external" href="http://sourceforge.net/projects/dvn/files/dvn">http://sourceforge.net/projects/dvn/files/dvn</a></p>
115 <p>Choose the latest version and download the dvninstall zip file.</p>
116 <p>Unzip the package in a temp location of your choice (this will create
117 the directory <tt class="docutils literal"><span class="pre">dvninstall</span></tt>). Run the installer, as root:</p>
118 <blockquote>
119 <div><dl class="docutils">
120 <dt><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">dvninstall</span></tt></dt>
121 <dd>./ <tt class="docutils literal"><span class="pre">install</span></tt></dd>
122 </dl>
123 </div></blockquote>
124 <p>Follow the installation prompts. If it all works as it should, you
125 will have a working DVN instance running in about a minute from now.</p>
126 <p>Has it worked? Awesome! Now you may read the rest of the guide
127 chapters at your own leisurely pace, to see if you need any of the
128 optional components described there. And/or if you want to understand
129 what exactly has just been done to your system.</p>
130 </div>
131 <div class="section" id="system-requirements">
132 <h2>SYSTEM REQUIREMENTS<a class="headerlink" href="#system-requirements" title="Permalink to this headline">¶</a></h2>
133 <p>Or rather, recommendations. The closer your configuration is to what’s
134 outlined below, the easier it will be for the DVN team to provide
135 support and answer your questions.</p>
136 <ul class="simple">
137 <li>Operating system - The production version of the Dataverse Network at
138 IQSS (dvn.iq.harvard.edu) runs on RedHat Linux 5. Most of the DVN
139 development is currently done on MacOS X. Because of our experience
140 with RedHat and MacOS X these are the recommended platforms. You
141 should be able to deploy the application .ear file on any other
142 platform that supports Java. However, the automated installer we
143 provide will likely work on RedHat and MacOS only. Some information
144 provided in this guide is specific to these 2 operating systems. (Any
145 OS-specific instructions/examples will be clearly marked, for
146 example:<tt class="docutils literal"><span class="pre">[MacOS-specific:]</span></tt>)</li>
147 <li>CPU - The production IQSS Dataverse Network runs on generic,
148 multi-core 64-bit processors.</li>
149 <li>Memory - The application servers currently in production at the IQSS
150 have 64 GB of memory each. Development and testing systems require a
151 minimum of 2 gigabyte of memory.</li>
152 <li>Disk space - How much disk space is required depends on the amount of
153 data that you expect to serve. The IQSS Dataverse Network file system
154 is a standalone NetApp with 2 TB volume dedicated to the DVN data.</li>
155 <li>Multiple servers – All the DVN components can run on the same server.
156 On a busy, hard-working production network the load can be split
157 across multiple servers. The 3 main components, the application
158 server (Glassfish), the database (Postgres) and R can each run on its
159 own host. Furthermore, multiple application servers sharing the same
160 database and R server(s) can be set up behind a load balancer.
161 Developers would normally run Glassfish and Postgres on their
162 workstations locally and use a shared R server.</li>
163 <li>If it actually becomes a practical necessity to bring up more servers
164 to handle your production load, there are no universal instructions
165 on how to best spread it across extra CPUs. It will depend on the
166 specifics of your site, the nature of the data you serve and the
167 needs of your users, whether you’ll benefit most from dedicating
168 another server to run the database, or to serve R requests. Please
169 see the discussion in the corresponding sections of the Prerequisites
170 chapter.</li>
171 </ul>
172 </div>
173 <div class="section" id="prerequisites">
174 <span id="id2"></span><h2>PREREQUISITES<a class="headerlink" href="#prerequisites" title="Permalink to this headline">¶</a></h2>
175 <p>In this chapter, an emphasis is made on clearly identifying those
176 components that are absolutely required for every installation and
177 marking any advanced, optional instructions as such.</p>
178 <div class="section" id="glassfish">
179 <h3>Glassfish<a class="headerlink" href="#glassfish" title="Permalink to this headline">¶</a></h3>
180 <p>Version 3.1.2 is required.</p>
181 <p>Make sure you have <strong>Sun/Oracle</strong><strong>Java JDK version 1.6, build 31</strong>
182 or newer. It is available from
183 <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>
184 <p><strong>[note for developers:]</strong></p>
185 <p>If you are doing this installation as part of your DVN software
186 development setup: The version of NetBeans currently in use by the DVN
187 team is 7.0.1, and it is recommended that you use this same version if
188 you want to participate in the development. As of writing of this
189 manual, NetBeans 7.0.1 installer bundle comes with an older version of
190 Glassfish. So you will have to install Glassfish version 3.1.2
191 separately, and then select it as the default server for your NetBeans
192 project.</p>
193 <p><strong>[/note for developers]</strong></p>
194 <p>We <strong>strongly</strong> recommend that you install GlassFish Server 3.1.2,
195 Open Source Edition, <strong>Full Platform</strong>. You are very likely to run into
196 installation issues if you attempt to run the installer and get the
197 application to work with a different version! Simply transitioning from
198 3.1.1 to 3.1.2 turned out to be a surprisingly complex undertaking,
199 hence this recommendation to all other installers and developers to stay
200 with the same version.</p>
201 <p>It can be obtained from</p>
202 <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>
203 <p>The page contains a link to the installation instructions. However,
204 the process is completely straightforward. You are given 2 options for
205 the format of the installer package. We recommend that you choose to
206 download it as a shell archive; you will need to change its executable
207 permission, with <strong>chmod +x</strong>, and then run it, as root:</p>
208 <p>./<strong>installer-filename.sh</strong></p>
209 <p>[<strong>Important:]</strong></p>
210 <p>Leave the admin password fields blank. This is not a security risk,
211 since out of the box, Glassfish will only be accepting admin connections
212 on the localhost interface. Choosing password at this stage however will
213 complicate the installation process unnecessarily<strong>.</strong>If this is a
214 developers installation, you can probably keep this configuration
215 unchanged (admin on localhost only). If you need to be able to connect
216 to the admin console remotely, please see the note in the Appendix
217 section of the manual.</p>
218 <p><strong>[/Important]</strong></p>
219 <div class="line-block">
220 <div class="line"><strong>[Advanced:]</strong></div>
221 <div class="line"><strong>[Unix-specific:`]</strong></div>
222 </div>
223 <p>The installer shell script will normally attempt to run in a graphic
224 mode. If you are installing this on a remote Unix server, this will
225 require X Windows support on your local workstation. If for whatever
226 reason it&#8217;s not available, you have an option of running it in a <em>silent
227 mode</em> - check the download page, above, for more information.</p>
228 <div class="line-block">
229 <div class="line"><strong>[/Unix-specific]</strong></div>
230 <div class="line"><strong>[/Advanced]</strong></div>
231 </div>
232 </div>
233 <div class="section" id="postgresql">
234 <span id="id3"></span><h3>PostgreSQL<a class="headerlink" href="#postgresql" title="Permalink to this headline">¶</a></h3>
235 <div class="line-block">
236 <div class="line"><strong>Version 8.3 or higher is required.</strong></div>
237 <div class="line">Installation instructions specific to RedHat Linux and MacOS X are</div>
238 <div class="line">provided below.</div>
239 <div class="line">Once the database server is installed, you&#8217;ll need to configure access</div>
240 <div class="line">control to suit your installation.</div>
241 <div class="line">Note that any modifications to the configuration files above require you to restart Postgres:</div>
242 <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>
243 </div>
244 <div class="line-block">
245 <div class="line">or</div>
246 <div class="line">&#8220;Restart Server&#8221; under Applications -&gt; PostgreSQL (MacOS X)</div>
247 </div>
248 <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 &#8220;yes&#8221;). 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 &#8220;<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>&#8221; 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>
249 <div class="line-block">
250 <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>
251 </div>
252 <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 &#8220;trust&#8221; or &#8220;ident&#8221;. I.e., your <strong>pg_hba.conf</strong> must contain either of the 2 lines below:</p>
253 <div class="line-block">
254 <div class="line"><strong>local all all ident sameuser</strong></div>
255 <div class="line">or</div>
256 <div class="line"><strong>local all all trust</strong></div>
257 </div>
258 <p>(&#8220;ident&#8221; is the default setting; but if it has been changed to
259 &#8220;password&#8221; or &#8220;md5&#8221;, etc. on your system, Postgres will keep prompting
260 you for the master password throughout the installation)</p>
261 <p><strong>[optional:]</strong></p>
262 <p>If GlassFish will be accessing the database remotely, add or modify the following line in your <tt class="docutils literal"><span class="pre">&lt;POSTGRES</span> <span class="pre">DIR&gt;/data/postgresql.conf</span></tt>:</p>
263 <div class="line-block">
264 <div class="line"><tt class="docutils literal"><span class="pre">listen_addresses='*'</span></tt></div>
265 </div>
266 <p>to enable network connections on all interfaces; and add the following
267 line to <tt class="docutils literal"><span class="pre">pg_hba.conf</span></tt>:</p>
268 <div class="line-block">
269 <div class="line">host all all <tt class="docutils literal"><span class="pre">[ADDRESS]</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span class="pre">255.255.255.255</span> <span class="pre">password</span></tt></div>
270 </div>
271 <div class="line-block">
272 <div class="line">where <tt class="docutils literal"><span class="pre">[ADDRESS]</span></tt> is the numeric IP address of the GlassFish server.</div>
273 <div class="line">Using the subnet notation above you can enable authorization for multiple hosts on | your network. For example,</div>
274 </div>
275 <div class="line-block">
276 <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>
277 </div>
278 <div class="line-block">
279 <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>
280 <div class="line"><strong>[/optional:]</strong></div>
281 </div>
282 <div class="line-block">
283 <div class="line"><br /></div>
284 <div class="line"><strong>[RedHat-specific:]</strong></div>
285 <div class="line"><strong>[Advanced:]</strong></div>
286 </div>
287 <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>
288 <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>
289 <div class="line-block">
290 <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>
291 </div>
292 <p>Before you start the server for the first time with</p>
293 <div class="line-block">
294 <div class="line"><tt class="docutils literal"><span class="pre">service</span> <span class="pre">postgresql</span> <span class="pre">start</span></tt></div>
295 </div>
296 <p>You will need to populate the initial database with</p>
297 <div class="line-block">
298 <div class="line"><tt class="docutils literal"><span class="pre">service</span> <span class="pre">postgresql</span> <span class="pre">initdb</span></tt></div>
299 </div>
300 <div class="line-block">
301 <div class="line"><strong>[/advanced]</strong></div>
302 <div class="line"><strong>[/RedHat-specific]</strong></div>
303 </div>
304 <p><strong>[MacOS-specific:]</strong></p>
305 <p>Postgres Project provides a one click installer for Mac OS X 10.4 and
306 above at
307 <a class="reference external" href="http://www.postgresql.org/download/macosx">http://www.postgresql.org/download/macosx</a>.
308 Fink and MacPorts packages are also available.</p>
309 <p><strong>[/MacOS-specific]`</strong></p>
310 <div class="line-block">
311 <div class="line"><strong>[advanced:]</strong></div>
312 <div class="line"><strong>[optional:]</strong></div>
313 </div>
314 <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>
315 <div class="line-block">
316 <div class="line"><strong>[/optional]</strong></div>
317 <div class="line"><strong>[/advanced]</strong></div>
318 </div>
319 </div>
320 <div class="section" id="r-and-rserve">
321 <span id="id4"></span><h3>R and RServe<a class="headerlink" href="#r-and-rserve" title="Permalink to this headline">¶</a></h3>
322 <p>Strictly speaking, R is an optional component. You can bring up a
323 running DVN instance without it. The automated installer will allow such
324 an installation, with a warning. Users of this Dataverse Network will be
325 able to upload and share some data. Only the advanced modes of serving
326 quantitative data to the users require R <tt class="docutils literal"><span class="pre">[style?]</span></tt>. Please consult
327 the <a class="reference internal" href="#do-you-need-r"><em>&#8220;Do you need R?&#8221;</em></a> section in the Appendix for an extended discussion of this.</p>
328 <div class="line-block">
329 <div class="line"><strong>Installation instructions:</strong></div>
330 </div>
331 <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>
332 <div class="line-block">
333 <div class="line"><strong>[RedHat/Linux-specific:]</strong></div>
334 </div>
335 <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>
336 <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 &#8211; see
337 <a class="reference external" href="http://fedoraproject.org/wiki/EPEL">http://fedoraproject.org/wiki/EPEL</a>
338 &#8211; then run the <tt class="docutils literal"><span class="pre">yum</span> <span class="pre">install</span></tt> command)</p>
339 <div class="line-block">
340 <div class="line"><strong>[/RedHat/Linux-specific]</strong></div>
341 </div>
342 <p>Please make sure to install the &#8220;devel&#8221; package too! you will need it
343 to build the extra R modules.</p>
344 <p>Once you have R installed, download the package <tt class="docutils literal"><span class="pre">dvnextra.tar</span></tt> from this location:</p>
345 <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>
346 <p>Unpack the archive:</p>
347 <p><tt class="docutils literal"><span class="pre">tar</span> <span class="pre">xvf</span> <span class="pre">dvnextra.tar</span></tt></p>
348 <p>then run the supplied installation shell script as root:</p>
349 <div class="line-block">
350 <div class="line-block">
351 <div class="line"><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">dvnextra</span></tt></div>
352 </div>
353 <div class="line"><tt class="docutils literal"><span class="pre">./installModules.sh</span></tt></div>
354 </div>
355 <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>
356 <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>
357 <div class="line-block">
358 <div class="line"><strong>[advanced:]</strong></div>
359 <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>
360 </div>
361 <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.
362 <strong>[/advanced]</strong></p>
363 </div>
364 <div class="section" id="system-configuration">
365 <h3>System Configuration<a class="headerlink" href="#system-configuration" title="Permalink to this headline">¶</a></h3>
366 <p><strong>[Advanced/optional:]</strong></p>
367 <p>Many modern OS distributions come pre-configured so that all the
368 network ports are firewalled off by default.</p>
369 <p>Depending on the configuration of your server, you may need to open some
370 of the following ports.</p>
371 <p>On a developers personal workstation, the user would normally access his
372 or her DVN instance on the localhost interface. So no open ports are
373 required unless you want to give access to your DVN to another
374 user/developer.</p>
375 <p>When running a DVN that is meant to be accessible by network users: At a
376 minimum, if all the components are running on the same server, the HTTP
377 port 80 needs to be open. You may also want to open TCP 443, to be able
378 to access Glassfish admin console remotely.</p>
379 <p>If the DVN is running its own HANDLE.NET server (see Chapter 4.
380 &#8220;Optional Components&#8221;), the TCP port 8000 and TCP/UDP ports 2641 are
381 also needed.</p>
382 <p>If the DVN application needs to talk to PostgreSQL and/or Rserve running
383 on remote hosts, the TCP ports 5432 and 6311, respectively, need to be
384 open there.</p>
385 <p><strong>[/Advanced/optional]</strong></p>
386 </div>
387 </div>
388 <div class="section" id="running-the-installer">
389 <h2>RUNNING THE INSTALLER<a class="headerlink" href="#running-the-installer" title="Permalink to this headline">¶</a></h2>
390 <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>
391 <p>The installer package can be downloaded from our repository on SourceForge at</p>
392 <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>
393 <div class="line-block">
394 <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>
395 <div class="line-block">
396 <div class="line"><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">dvninstall</span></tt></div>
397 <div class="line"><tt class="docutils literal"><span class="pre">./install</span></tt></div>
398 </div>
399 </div>
400 <p>Follow the installation prompts. The installer will first verify the contents of the package and check if the required components
401 (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>
402 <div class="line-block">
403 <div class="line"><strong>[Advanced:]</strong></div>
404 </div>
405 <p>The limitations of the installer package:</p>
406 <p>Some extra configuration steps will be required if the PostgreSQL database is being set up on a remote server.</p>
407 <p>It will most likely only work on the supported platforms, RedHat and Mac OS X.</p>
408 <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>&#8220;What does the Installer do?&#8221;</em></a> section.</p>
409 <p>It does not install any of the optional components (<a class="reference internal" href="#optional-components"><em>see Chapter 4</em></a>.)</p>
410 <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>&#8220;What does the Installer do?&#8221;</em></a> section.</p>
411 <div class="line-block">
412 <div class="line"><strong>[/Advanced]</strong></div>
413 </div>
414 </div>
415 <div class="section" id="optional-components">
416 <span id="id5"></span><h2>Optional Components<a class="headerlink" href="#optional-components" title="Permalink to this headline">¶</a></h2>
417 <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>
418 <div class="section" id="recaptcha-bot-blocker">
419 <h3>reCAPTCHA bot blocker<a class="headerlink" href="#recaptcha-bot-blocker" title="Permalink to this headline">¶</a></h3>
420 <p>We found that our “email us” feature can be abused to send spam
421 messages. You can choose to use the reCAPTCHA filter to help prevent
422 this. Configure the filter as follows:</p>
423 <ol class="arabic">
424 <li><div class="first line-block">
425 <div class="line">Go to reCAPTCHA web site at</div>
426 <div class="line"><a class="reference external" href="http://recaptcha.net/">http://recaptcha.net/</a></div>
427 <div class="line">and sign up for an account.</div>
428 <div class="line">Register your website domain to acquire a public/private CAPTCHA key pair.</div>
429 <div class="line">Record this information in a secure location.</div>
430 </div>
431 </li>
432 <li><p class="first">Insert the the public/private key pair and domain for your reCAPTCHA
433 account into the <tt class="docutils literal"><span class="pre">captcha</span></tt> table of the DVN PostgreSQL database.
434 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
435 query will look like this:
436 <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>
437 </li>
438 <li><p class="first">Verify that the Report Issue page is now showing the reCAPTCHA
439 challenge.</p>
440 </li>
441 </ol>
442 </div>
443 <div class="section" id="google-analytics">
444 <h3>Google Analytics<a class="headerlink" href="#google-analytics" title="Permalink to this headline">¶</a></h3>
445 <p>Network Admins can use the Google Analytics tools to view Dataverse Network website usage statistics.</p>
446 <p>Note: It takes about 24 hours for Google Analytics to start monitoring
447 your website after the registration.</p>
448 <div class="line-block">
449 <div class="line"><br /></div>
450 <div class="line">To enable the use of Google Analytics:</div>
451 </div>
452 <ol class="arabic">
453 <li><p class="first">Go to the Google Analytics homepage at
454 <a class="reference external" href="http://www.google.com/analytics/indexu.html">http://www.google.com/analytics/indexu.html</a>.</p>
455 </li>
456 <li><p class="first">Set up a Google Analytics account and obtain a tracking code for your Dataverse Network installation.</p>
457 </li>
458 <li><p class="first">Use the Google Analytics Help Center to find how to add the tracking code to the content you serve.</p>
459 </li>
460 <li><dl class="first docutils">
461 <dt>Configure the DVN to use the tracking key (obtained in Step 2,</dt>
462 <dd><p class="first">above), by setting | the <tt class="docutils literal"><span class="pre">dvn.googleanalytics.key</span></tt> JVM option in
463 Glassfish.</p>
464 <p>This can be done by adding the following directly to the
465 <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>):
466 <tt class="docutils literal"><span class="pre">&lt;jvm-options&gt;-Ddvn.googleanalytics.key=XX-YYY&lt;/jvm-options&gt;</span></tt> (this will require Glassfish restart)</p>
467 <p class="last">Or by using the Glassfish Admin Console configuration GUI. Consult the “Glassfish Configuration” section in the Appendix.</p>
468 </dd>
469 </dl>
470 </li>
471 </ol>
472 <p>Once installed and activated, the usage statistics can be accessed from
473 the Network Options of the DVN.</p>
474 </div>
475 <div class="section" id="imagemagick">
476 <h3>ImageMagick<a class="headerlink" href="#imagemagick" title="Permalink to this headline">¶</a></h3>
477 <p>When image files are ingested into a DVN, the application
478 automatically creates small &#8220;thumbnail&#8221; versions to display on the
479 Files View page. These thumbnails are generated once, then cached for
480 future use.</p>
481 <p>Normally, the standard Java image manipulation libraries are used to
482 do the scaling. If you have studies with large numbers of large
483 images, generating the thumbnails may become a time-consuming task. If
484 you notice that the Files view takes a long time to load for the first
485 time because of the images, it is possible | to improve the
486 performance by installing the <tt class="docutils literal"><span class="pre">ImageMagick</span></tt> package. If it is
487 installed, the application will automatically use its
488 <tt class="docutils literal"><span class="pre">/usr/bin/convert</span></tt> utility to do the resizing, which appears to be
489 significantly faster than the Java code.</p>
490 <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>
491 <div class="line-block">
492 <div class="line"><strong>&lt;RedHat-Specific:&gt;</strong></div>
493 </div>
494 <p>It is part of the full RedHat Linux distribution, although it is not
495 included in the default &#8220;server&#8221; configuration. It can be installed on a
496 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>
497 <p><strong>&lt;/RedHat-Specific&gt;</strong></p>
498 </div>
499 <div class="section" id="handle-system">
500 <h3>Handle System<a class="headerlink" href="#handle-system" title="Permalink to this headline">¶</a></h3>
501 <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
502 pre-configured to use Handles.</p>
503 <p>To install and set up a local HANDLE.NET server:</p>
504 <ol class="arabic simple">
505 <li>Download HANDLE.NET.
506 Refer to the HANDLE.NET software download page at
507 <a class="reference external" href="http://handle.net/download.html">http://handle.net/download.html</a>.</li>
508 <li>Install the server on the same host as GlassFish.
509 Complete the installation and setup process as described in the
510 HANDLE.NET Technical Manual:
511 <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>
512 <li>Accept the default settings during installation, <strong>with one
513 exception:</strong> do not encrypt private keys (this will make it easier to
514 manage the service). <strong>Note</strong> that this means answer &#8216;n&#8217; when
515 prompted &#8220;Would you like to encrypt your private key?(y/n). [y]:&#8221; If
516 you accept the default &#8216;y&#8217; and then hit return when prompted for
517 passphrase, this <strong>will</strong> encrypt the key, with a blank pass phrase!</li>
518 <li>During the installation you will be issued an &#8220;authority prefix&#8221;.
519 This is an equivalent of a domain name. For example, the prefix
520 registered to the IQSS DVN is &#8220;1902.1&#8221;. The IDs issued to IQSS
521 studies are of a form &#8220;1902.1/XXXX&#8221;, where &#8220;XXXX&#8221; is some unique
522 identifier.</li>
523 <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:
524 <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">'&lt;your</span> <span class="pre">HANDLE.NET</span> <span class="pre">prefix&gt;')</span></tt>;</li>
525 <li><tt class="docutils literal"><span class="pre">(Optional/advanced)</span></tt> If you are going to be assigning HANDLE.NET
526 ids in more than 1 authority prefix (to register studies harvested
527 from remote sources): Once you obtain the additional HANDLE.NET
528 prefixes, add each to the <tt class="docutils literal"><span class="pre">handleprefix</span></tt> table, using the SQL
529 command from step 3.</li>
530 <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
531 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='&lt;your</span> <span class="pre">HANDLE.NET</span> <span class="pre">prefix&gt;';</span></tt></li>
532 </ol>
533 <p>Note: The DVN app comes bundled with the HANDLE.NET client libraries.
534 You do not need to install these separately.</p>
535 </div>
536 <div class="section" id="twitter-setup">
537 <h3>Twitter setup<a class="headerlink" href="#twitter-setup" title="Permalink to this headline">¶</a></h3>
538 <p>To set up the ability for users to enable Automatic Tweets in your
539 Dataverse Network:</p>
540 <ol class="arabic">
541 <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>
542 </li>
543 <li><p class="first">Click &#8220;Create a new application&#8221;.</p>
544 </li>
545 <li><p class="first">Fill out all the fields. For callback URL, use your Dataverse Network Home Page URL.</p>
546 </li>
547 <li><p class="first">Once created, go to settings tab and set Application Type to &#8220;Read and Write&#8221;. You can optionally also upload an Application
548 Icon and fill out Organization details (the end user will see these.</p>
549 </li>
550 <li><dl class="first docutils">
551 <dt>Click details again. You will need both the Consumer key and secret as JVM Options. Add via Glassfish console:</dt>
552 <dd><p class="first">-Dtwitter4j.oauth.consumerKey=***</p>
553 <p class="last">-Dtwitter4j.oauth.consumerSecret=***</p>
554 </dd>
555 </dl>
556 </li>
557 <li><p class="first">Restart Glassfish.</p>
558 </li>
559 <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, &#8220;Enable Twitter&#8221;.</p>
560 </li>
561 </ol>
562 </div>
563 <div class="section" id="digital-object-identifiers">
564 <h3>Digital Object Identifiers<a class="headerlink" href="#digital-object-identifiers" title="Permalink to this headline">¶</a></h3>
565 <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>
566 <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>
567 <p>Update your database with the following query:</p>
568 <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:
569 <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>&nbsp; <span class="pre">protocol</span> <span class="pre">=</span> <span class="pre">'doi',</span> <span class="pre">authority='&lt;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&gt;</span> <span class="pre">where</span> <span class="pre">id</span> <span class="pre">=</span> <span class="pre">0;</span></tt></p>
570 <p>Add the following JVM options:</p>
571 <p><tt class="docutils literal"><span class="pre">-Ddoi.username=&lt;username</span> <span class="pre">of</span> <span class="pre">your</span> <span class="pre">EZID</span> <span class="pre">account&gt;</span></tt></p>
572 <p><tt class="docutils literal"><span class="pre">-Ddoi.password=&lt;password</span> <span class="pre">of</span> <span class="pre">your</span> <span class="pre">EZID</span> <span class="pre">account&gt;</span></tt></p>
573 <p><tt class="docutils literal"><span class="pre">-Ddoi.baseurlstring=https://ezid.cdlib.org</span></tt></p>
574 <p>Note: The DVN app comes bundled with the EZID API client libraries. You do not need to install these separately.</p>
575 </div>
576 </div>
577 <div class="section" id="appendix">
578 <h2>Appendix<a class="headerlink" href="#appendix" title="Permalink to this headline">¶</a></h2>
579 <div class="section" id="do-you-need-r">
580 <span id="id6"></span><h3>Do you need R?<a class="headerlink" href="#do-you-need-r" title="Permalink to this headline">¶</a></h3>
581 <p>This is a more detailed explanation of the statement made earlier in the &#8220;Prerequisites&#8221; section: &#8220;Only the advanced modes of serving quantitative data to the users require R.&#8221; <tt class="docutils literal"><span class="pre">[style?]</span></tt></p>
582 <p>In this context, by “quantitative data” we mean data sets for which
583 machine-readable, variable-level metadata has been defined in the DVN
584 database. “Subsettable data” is another frequently used term, in the
585 DVN parlance. The currently supported sources of subsettable data are
586 SPSS and STATA files, as well as row tabulated or CSV files, with
587 extra control cards defining the data structure and variable
588 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>
589 <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>
590 </div>
591 <div class="section" id="what-does-the-installer-do">
592 <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>
593 <p>The Installer script (chapters Quick Install, Running the Installer.) automates the following tasks:</p>
594 <ol class="arabic simple">
595 <li>Checks the system for required components;</li>
596 <li>Prompts the user for the following information:<ol class="loweralpha">
597 <li>Location of the Glassfish directory;</li>
598 <li>Access information (host, port, database name, username, password) for PostgresQL;</li>
599 <li>Access information (host, port, username, password) for Rserve;</li>
600 </ol>
601 </li>
602 <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>&#8220;PostgreSQL configuration&#8221;</em></a> Appendix section for details.</li>
603 <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>
604 <li>Copies additional configuration files (supplied in the dvninstall/config directory of the Installer package) into the config directory of the Glassfish domain.</li>
605 <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>
606 <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 &#8220;virgin&#8221;, fresh config. Glassfish will perform some initialization tasks on this first startup and deploy some internal apps.</li>
607 <li>If step 5. succeeds, the Installer attempts to deploy the DVN application (the Java archive DVN-EAR.ear supplied with the installer).</li>
608 <li>Stops Glassfish, populates the DVN database with the initial content (section <a class="reference internal" href="#postgresql-setup"><em>&#8220;PostgreSQL configuration&#8221;</em></a>&#8221; of the Appendix), starts Glassfish.</li>
609 <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>
610 <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>
611 </ol>
612 <p>Throughout the steps above, the Installer attempts to diagnose any
613 potential issues and give the user clear error messages when things go
614 wrong (&#8220;version of Postgres too old&#8221;, &#8220;you must run this as root&#8221;,
615 etc.).</p>
616 <p>Enough information is supplied in this manual to enable a user (a
617 skilled and rather patient user, we may add) to perform all the steps
618 above without the use of the script.</p>
619 </div>
620 <div class="section" id="glassfish-configuration-template">
621 <span id="id7"></span><h3>Glassfish configuration template<a class="headerlink" href="#glassfish-configuration-template" title="Permalink to this headline">¶</a></h3>
622 <p>The configuration template (<tt class="docutils literal"><span class="pre">domain.xml.TEMPLATE</span></tt>) is part of the
623 installer zip package. The installer replaces the placeholder
624 configuration tokens (for example, <tt class="docutils literal"><span class="pre">%POSTGRES_DATABASE%</span></tt>) with the
625 real values provided by the user to create the Glassfish configuration
626 file <tt class="docutils literal"><span class="pre">domain.xml</span></tt>.</p>
627 <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>
628 <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>
629 <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>
630 <span class="pre">whatever]</span></tt></p>
631 </div>
632 <div class="section" id="glassfish-configuration-individual-settings">
633 <span id="id8"></span><h3>Glassfish Configuration, individual settings<a class="headerlink" href="#glassfish-configuration-individual-settings" title="Permalink to this headline">¶</a></h3>
634 <p>As explained earlier in the Appendix, the Installer configures Glassfish
635 by cooking a complete domain configuration file (<tt class="docutils literal"><span class="pre">domain.xml</span></tt>) and
636 installing it in the domain directory.</p>
637 <p>All of the settings and options however can be configured individually
638 by an operator, using the Glassfish Admin Console.</p>
639 <p>The Console can be accessed at the network port 4848 when Glassfish is
640 running, by pointing a browser at</p>
641 <blockquote>
642 <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>
643 <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
644 is of course strongly recommended to log in and change it first thing
645 after you run the Installer.</p>
646 <p>The sections below describe all the configuration settings that would
647 need to be done through the GUI in order to replicate the configuration
648 file produced by the Installer. This information is provided for the
649 benefit of an advanced user who may want to experiment with individual
650 options. Or to attempt to install DVN on a platform not supported by our
651 installer; although we wish sincerely that nobody is driven to such
652 desperate measures ever.</p>
653 <div class="section" id="jvm-options">
654 <span id="id9"></span><h4>JVM options<a class="headerlink" href="#jvm-options" title="Permalink to this headline">¶</a></h4>
655 <p>Under Application Server-&gt;JVM Settings-&gt;JVM Options:</p>
656 <p>If you are installing Glassfish in a production environment, follow
657 these steps:</p>
658 <ol class="arabic">
659 <li><div class="first line-block">
660 <div class="line">Delete the following options: -Dsun.rmi.dgc.server.gcInterval=3600000</div>
661 <div class="line">-Dsun.rmi.dgc.client.gcInterval=3600000</div>
662 </div>
663 </li>
664 <li><div class="first line-block">
665 <div class="line">Add the following options:</div>
666 <div class="line">-XX:MaxPermSize=192m</div>
667 <div class="line">-XX:+AggressiveHeap</div>
668 <div class="line">-Xss128l</div>
669 <div class="line">-XX:+DisableExplicitGC</div>
670 <div class="line">-Dcom.sun.enterprise.ss.ASQuickStartup=false</div>
671 </div>
672 </li>
673 <li><div class="first line-block">
674 <div class="line">To install on a multi-processor machine, add the following:</div>
675 <div class="line"><tt class="docutils literal"><span class="pre">-XX:+UseParallelOldGC</span></tt></div>
676 </div>
677 </li>
678 <li><div class="first line-block">
679 <div class="line">To enable the optional HANDLE.NET installation and provide access to</div>
680 <div class="line">study ID registration, add the following (see the &#8220;Handles System&#8221;</div>
681 <div class="line">section in the &#8220;Optional Components&#8221; for</div>
682 <div class="line">details):</div>
683 <div class="line"><tt class="docutils literal"><span class="pre">-Ddvn.handle.baseUrl=&lt;-Dataverse</span> <span class="pre">Network</span> <span class="pre">host</span> <span class="pre">URL&gt;/dvn/study?globalId=hdl:</span></tt></div>
684 <div class="line"><tt class="docutils literal"><span class="pre">-Ddvn.handle.auth=&lt;authority&gt;</span></tt></div>
685 <div class="line"><tt class="docutils literal"><span class="pre">-Ddvn.handle.admcredfile=/hs/svr_1/admpriv.bin</span></tt></div>
686 </div>
687 </li>
688 <li><div class="first line-block">
689 <div class="line">To enable the optional Google Analytics option on the Network Options</div>
690 <div class="line">page and provide access to site usage reports, add the following (see</div>
691 <div class="line">the &#8220;Google Analytics&#8221; section in the &#8220;Optional Components&#8221; for</div>
692 <div class="line">details):</div>
693 <div class="line-block">
694 <div class="line"><tt class="docutils literal"><span class="pre">-Ddvn.googleanalytics.key=&lt;googleAnalyticsTrackingCode&gt;</span></tt></div>
695 </div>
696 </div>
697 </li>
698 <li><div class="first line-block">
699 <div class="line">Configure the following option only if you run multiple instances</div>
700 <div class="line">of the GlassFish server for load balancing. This option controls</div>
701 <div class="line">which GlassFish instance runs scheduled jobs, such as harvest or</div>
702 <div class="line">export.</div>
703 <div class="line">For the server instance that will run scheduled jobs, include the</div>
704 <div class="line">following JVM option:</div>
705 <div class="line"><tt class="docutils literal"><span class="pre">-Ddvn.timerServer=true</span></tt></div>
706 <div class="line">For all other server instances, include this JVM option:</div>
707 <div class="line"><tt class="docutils literal"><span class="pre">-Ddvn.timerServer=false</span></tt></div>
708 <div class="line">If you are installing Glassfish in either a production or development</div>
709 <div class="line">environment, follow these steps:</div>
710 </div>
711 <ul>
712 <li><div class="first line-block">
713 <div class="line">Change the following options’ settings:</div>
714 <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>
715 <div class="line">Change <tt class="docutils literal"><span class="pre">-Xmx512m</span></tt> to whatever size you can allot for the maximum</div>
716 <div class="line">Java heap space.</div>
717 <div class="line">Set `` –Xms512m`` to the same value to which you set <tt class="docutils literal"><span class="pre">–Xmx512m</span></tt>.</div>
718 </div>
719 </li>
720 <li><div class="first line-block">
721 <div class="line">To configure permanent file storage (data and documentation files</div>
722 <div class="line">uploaded to studies) set the following:</div>
723 <div class="line"><tt class="docutils literal"><span class="pre">-Dvdc.study.file.dir=${com.sun.aas.instanceRoot}/config/files/studies</span></tt></div>
724 </div>
725 </li>
726 <li><div class="first line-block">
727 <div class="line">To configure the temporary location used in file uploads add the</div>
728 <div class="line">following:</div>
729 <div class="line"><tt class="docutils literal"><span class="pre">-Dvdc.temp.file.dir=${com.sun.aas.instanceRoot}/config/files/temp</span></tt></div>
730 </div>
731 </li>
732 <li><div class="first line-block">
733 <div class="line">To configure export and import logs (harvesting and importing),</div>
734 <div class="line">add the following:</div>
735 <div class="line">-Dvdc.export.log.dir=${com.sun.aas.instanceRoot}/logs/export</div>
736 <div class="line">-Dvdc.import.log.dir=${com.sun.aas.instanceRoot}/logs/import</div>
737 </div>
738 </li>
739 <li><div class="first line-block">
740 <div class="line">Add the following:</div>
741 <div class="line">-Djhove.conf.dir=${com.sun.aas.instanceRoot}/config</div>
742 <div class="line">-Ddvn.inetAddress=&lt;host or fully qualified domain name of server</div>
743 <div class="line">on which Dataverse Network runs&gt;</div>
744 <div class="line">-Ddvn.networkData.libPath=${com.sun.aas.instanceRoot}/applications/j2ee-</div>
745 <div class="line-block">
746 <div class="line">apps/DVN-EAR</div>
747 </div>
748 </div>
749 </li>
750 <li><div class="first line-block">
751 <div class="line">To manage calls to RServe and the R host (analysis and file upload), add</div>
752 <div class="line">the following:</div>
753 <div class="line"><tt class="docutils literal"><span class="pre">-Dvdc.dsb.host=&lt;RServe</span> <span class="pre">server</span> <span class="pre">hostname&gt;</span></tt></div>
754 <div class="line"><tt class="docutils literal"><span class="pre">-Dvdc.dsb.rserve.user=&lt;account&gt;</span></tt></div>
755 <div class="line"><tt class="docutils literal"><span class="pre">-Dvdc.dsb.rserve.pwrd=&lt;password&gt;</span></tt></div>
756 <div class="line"><tt class="docutils literal"><span class="pre">-Dvdc.dsb.rserve.port=&lt;port</span> <span class="pre">number&gt;</span></tt></div>
757 </div>
758 <div class="line-block">
759 <div class="line">For Installing R, see:</div>
760 <div class="line"><a class="reference internal" href="#r-and-rserve"><em>R and R-Serve</em></a></div>
761 <div class="line">for information about configuring these values in the <tt class="docutils literal"><span class="pre">Rserv.conf</span></tt></div>
762 <div class="line">file.</div>
763 <div class="line">These settings must be configured for subsetting and analysis to</div>
764 <div class="line">work.</div>
765 </div>
766 </li>
767 <li><div class="first line-block">
768 <div class="line">To configure search index files set the following:</div>
769 <div class="line"><tt class="docutils literal"><span class="pre">-Ddvn.index.location=${com.sun.aas.instanceRoot}/config</span></tt></div>
770 </div>
771 </li>
772 <li><div class="first line-block">
773 <div class="line">To use the optional customized error logging and add more information</div>
774 <div class="line">to your log files, set the following:</div>
775 <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>
776 <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>
777 </div>
778 </li>
779 <li><div class="first line-block">
780 <div class="line">The default size limit for file downloads is 100MB. To override this</div>
781 <div class="line">default add the following JVM option:</div>
782 <div class="line"><tt class="docutils literal"><span class="pre">-Ddvn.batchdownload.limit=&lt;max</span> <span class="pre">download</span> <span class="pre">bytes&gt;</span></tt></div>
783 </div>
784 </li>
785 </ul>
786 </li>
787 </ol>
788 </div>
789 <div class="section" id="ejb-container">
790 <h4>EJB Container<a class="headerlink" href="#ejb-container" title="Permalink to this headline">¶</a></h4>
791 <p>Under Configuration-&gt;EJB Container-&gt;EJB Timer Service:</p>
792 <ol class="arabic">
793 <li><div class="first line-block">
794 <div class="line">Set the Timer Datasource to the following:</div>
795 <div class="line"><tt class="docutils literal"><span class="pre">jdbc/VDCNetDS</span></tt></div>
796 </div>
797 </li>
798 <li><div class="first line-block">
799 <div class="line">Save the configuration.</div>
800 </div>
801 </li>
802 </ol>
803 </div>
804 <div class="section" id="http-service">
805 <h4>HTTP Service<a class="headerlink" href="#http-service" title="Permalink to this headline">¶</a></h4>
806 <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
807 | Sun Microsystems Documentation web site at the following URL:</p>
808 <p><a class="reference external" href="http://docs.sun.com/">http://docs.sun.com/</a></p>
809 <div class="line-block">
810 <div class="line"><strong>Note</strong>: If your server becomes so busy that it drops connections,</div>
811 <div class="line">adjust the Thread Counts to improve performance.</div>
812 </div>
813 <ol class="arabic">
814 <li><p class="first">Under Configuration-&gt;HTTP Service-&gt;HTTP
815 Listeners-&gt;<tt class="docutils literal"><span class="pre">http-listener-1</span></tt>:</p>
816 <ul class="simple">
817 <li>Listener Port: 80</li>
818 <li>Acceptor Threads: The number of CPUs (cores) on your server</li>
819 </ul>
820 </li>
821 <li><p class="first">Under Configuration-&gt;HTTP Service, in the RequestProcessing tab:</p>
822 <ul class="simple">
823 <li>Thread Count: Four times the number of CPUs (cores) on your server</li>
824 <li>Initial Thread Count: The number of CPUs (cores)</li>
825 </ul>
826 </li>
827 <li><p class="first">Under Configuration-&gt;HTTP Service-&gt;Virtual Servers-&gt;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>
828 <blockquote>
829 <div><ol class="arabic">
830 <li><div class="first line-block">
831 <div class="line">Under Configuration-&gt;HTTP Service, configure Access Logging:</div>
832 </div>
833 </li>
834 </ol>
835 <div class="line-block">
836 <div class="line">format=%client.name% %auth-user-name% %datetime% %request% %status%</div>
837 <div class="line">%response.length%</div>
838 <div class="line">rotation-enabled=true</div>
839 <div class="line">rotation-interval-in-minutes=15</div>
840 <div class="line">rotation-policy=time</div>
841 <div class="line">rotation-suffix=yyyy-MM-dd</div>
842 </div>
843 </div></blockquote>
844 </li>
845 </ol>
846 </div>
847 <div class="section" id="javamail-session">
848 <h4>JavaMail Session<a class="headerlink" href="#javamail-session" title="Permalink to this headline">¶</a></h4>
849 <p>Under Resources-&gt;JavaMail Sessions<tt class="docutils literal"><span class="pre">-&gt;mail/notifyMailSession:</span></tt></p>
850 <ul>
851 <li><div class="first line-block">
852 <div class="line">Mail Host: <tt class="docutils literal"><span class="pre">&lt;your</span> <span class="pre">mail</span> <span class="pre">server&gt;</span></tt></div>
853 <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>
854 </div>
855 </li>
856 <li><dl class="first docutils">
857 <dt>Default User: <tt class="docutils literal"><span class="pre">dataversenotify</span></tt></dt>
858 <dd><p class="first last">This does not need to be a real mail account.</p>
859 </dd>
860 </dl>
861 </li>
862 <li><p class="first">Default Return Address: <tt class="docutils literal"><span class="pre">do-not-reply&#64;&lt;your</span> <span class="pre">mail</span> <span class="pre">server&gt;</span></tt></p>
863 </li>
864 </ul>
865 </div>
866 <div class="section" id="jdbc-resources">
867 <h4>JDBC Resources<a class="headerlink" href="#jdbc-resources" title="Permalink to this headline">¶</a></h4>
868 <p><strong>Under Resources-&gt;JDBC-&gt;Connection Pools:</strong></p>
869 <div class="line-block">
870 <div class="line">Add a new Connection Pool entry:</div>
871 </div>
872 <ul class="simple">
873 <li>entryName: <tt class="docutils literal"><span class="pre">dvnDbPool</span></tt></li>
874 <li>Resource Type: <tt class="docutils literal"><span class="pre">javax.sql.DataSource</span></tt></li>
875 <li>Database Vendor: <tt class="docutils literal"><span class="pre">PostgreSQL</span></tt></li>
876 <li>DataSource ClassName: <tt class="docutils literal"><span class="pre">org.postgresql.ds.PGPoolingDataSource</span></tt></li>
877 <li>Additional Properties:<ul>
878 <li>ConnectionAttributes: <tt class="docutils literal"><span class="pre">;create=true</span></tt></li>
879 <li>User: <tt class="docutils literal"><span class="pre">dvnApp</span></tt></li>
880 <li>PortNumber: <tt class="docutils literal"><span class="pre">5432</span></tt> (Port 5432 is the PostgreSQL default port.)</li>
881 <li>Password: <tt class="docutils literal"><span class="pre">&lt;Dataverse</span> <span class="pre">Network</span> <span class="pre">application</span> <span class="pre">database</span> <span class="pre">password&gt;</span></tt></li>
882 <li>DatabaseName: <tt class="docutils literal"><span class="pre">&lt;your</span> <span class="pre">database</span> <span class="pre">name&gt;</span></tt></li>
883 <li>ServerName: <tt class="docutils literal"><span class="pre">&lt;your</span> <span class="pre">database</span> <span class="pre">host&gt;</span></tt></li>
884 <li>JDBC30DataSource: <tt class="docutils literal"><span class="pre">true</span></tt></li>
885 </ul>
886 </li>
887 </ul>
888 <div class="line-block">
889 <div class="line"><br /></div>
890 </div>
891 <p><strong>Under Resources-&gt;JDBC-&gt;JDBC Resources:</strong></p>
892 <div class="line-block">
893 <div class="line">Add a new JDBC Resources entry:</div>
894 </div>
895 <ul class="simple">
896 <li>JNDI Name: <tt class="docutils literal"><span class="pre">jdbc/VDCNetDS</span></tt></li>
897 <li>Pool Name: <tt class="docutils literal"><span class="pre">dvnDbPool</span></tt></li>
898 </ul>
899 </div>
900 <div class="section" id="jms-resources">
901 <h4>JMS Resources<a class="headerlink" href="#jms-resources" title="Permalink to this headline">¶</a></h4>
902 <p>Under Resources-&gt;JMS Resources:</p>
903 <ol class="arabic simple">
904 <li>Add a new Connection Factory for the DSB Queue:<ul>
905 <li>JNDI Name: <tt class="docutils literal"><span class="pre">jms/DSBQueueConnectionFactory</span></tt></li>
906 <li>Resource Type: <tt class="docutils literal"><span class="pre">javax.jms.QueueConnectionFactory</span></tt></li>
907 </ul>
908 </li>
909 <li>Add a new Connection Factory for the Index Message:<ul>
910 <li>JNDI Name: <tt class="docutils literal"><span class="pre">jms/IndexMessageFactory</span></tt></li>
911 <li>Resource Type: <tt class="docutils literal"><span class="pre">javax.jms.QueueConnectionFactory</span></tt></li>
912 </ul>
913 </li>
914 <li>Add a new Destination Resource for the DSB Queue:<ul>
915 <li>JNDI Name: <tt class="docutils literal"><span class="pre">jms/DSBIngest</span></tt></li>
916 <li>Physical Destination Name: <tt class="docutils literal"><span class="pre">DSBIngest</span></tt></li>
917 <li>Resource Type: <tt class="docutils literal"><span class="pre">javax.jms.Queue</span></tt></li>
918 </ul>
919 </li>
920 <li>Add a new Destination Resource for the Index Message:<ul>
921 <li>JNDI Name: <tt class="docutils literal"><span class="pre">jms/IndexMessage</span></tt></li>
922 <li>Physical Destination Name: <tt class="docutils literal"><span class="pre">IndexMessage</span></tt></li>
923 <li>Resource Type: <tt class="docutils literal"><span class="pre">javax.jms.Queue</span></tt></li>
924 </ul>
925 </li>
926 </ol>
927 </div>
928 </div>
929 <div class="section" id="postgresql-setup">
930 <span id="id10"></span><h3>PostgreSQL setup<a class="headerlink" href="#postgresql-setup" title="Permalink to this headline">¶</a></h3>
931 <p>The following actions are normally performed by the automated installer
932 script. These steps are explained here for reference, and/or in case
933 your need to perform them manually:</p>
934 <ol class="arabic">
935 <li><p class="first">Start as root, then change to user postgres:</p>
936 <p><tt class="docutils literal"><span class="pre">su</span> <span class="pre">postgres</span></tt></p>
937 </li>
938 </ol>
939 <blockquote>
940 <div><p>Create DVN database usert (role):</p>
941 <p><tt class="docutils literal"><span class="pre">createuser</span> <span class="pre">-SrdPE</span> <span class="pre">[DB_USERNAME]</span></tt></p>
942 <p>(you will be prompted to choose a user password).</p>
943 <p>Create DVN database:</p>
944 <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>
945 <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>
946 </div></blockquote>
947 <ol class="arabic simple" start="2">
948 <li>Before Glassfish can be configured for the DVN app, the Postgres driver needs to be installed in the &lt;GLASSFISH ROOT&gt;/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>&#8220;What does the Installer do?&#8221;</em></a> section of this appendix) An example of the installed location of the driver:</li>
949 </ol>
950 <blockquote>
951 <div><tt class="docutils literal"><span class="pre">/usr/local/glassfish/lib/postgresql-8.3-603.jdbc4.jar</span></tt></div></blockquote>
952 <ol class="arabic simple" start="3">
953 <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>
954 </ol>
955 <blockquote>
956 <div><p><tt class="docutils literal"><span class="pre">su</span> <span class="pre">postgres</span></tt>
957 <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>
958 <p>The file referenceData.sql is provided as part of the installer zip package.</p>
959 </div></blockquote>
960 </div>
961 <div class="section" id="redhat-startup-file-for-glassfish-example">
962 <h3>RedHat startup file for glassfish, example<a class="headerlink" href="#redhat-startup-file-for-glassfish-example" title="Permalink to this headline">¶</a></h3>
963 <p>Below is an example of a glassfish startup file that you may want to
964 install on your RedHat (or similar) system to have glassfish start
965 automatically on boot.</p>
966 <div class="line-block">
967 <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>
968 </div>
969 <p>Note that the extra configuration steps before the domain start line,
970 for increasing the file limit and allowing &#8220;memory overcommit&#8221;. These
971 are useful settings to have on a production server.</p>
972 <div class="line-block">
973 <div class="line">You may of course add extra custom configuration specific to your
974 setup.</div>
975 </div>
976 <div class="highlight-guess"><div class="highlight"><pre><span class="c">#! /bin/sh</span>
977 <span class="c"># chkconfig: 2345 99 01</span>
978 <span class="c"># description: GlassFish App Server</span>
979 <span class="nb">set</span> -e
980 <span class="nv">ASADMIN</span><span class="o">=</span>/usr/local/glassfish/bin/asadmin
981 <span class="k">case</span> <span class="s2">&quot;$1&quot;</span> in
982 start<span class="o">)</span>
983 <span class="nb">echo</span> -n <span class="s2">&quot;Starting GlassFish server: glassfish&quot;</span>
984 <span class="c"># Increase file descriptor limit:</span>
985 <span class="nb">ulimit</span> -n 32768
986 <span class="c"># Allow &quot;memory overcommit&quot;:</span>
987 <span class="c"># (basically, this allows to run exec() calls from inside the</span>
988 <span class="c"># app, without the Unix fork() call physically hogging 2X</span>
989 <span class="c"># the amount of memory glassfish is already using)</span>
990 <span class="nb">echo </span>1 &gt; /proc/sys/vm/overcommit_memory
991 <span class="nv">$ASADMIN</span> start-domain domain1 <span class="nb">echo</span> <span class="s2">&quot;.&quot;</span>
992 ;;
993 stop<span class="o">)</span>
994 <span class="nb">echo</span> -n <span class="s2">&quot;Stopping GlassFish server: glassfish&quot;</span>
995 <span class="nv">$ASADMIN</span> stop-domain domain1
996 <span class="nb">echo</span> <span class="s2">&quot;.&quot;</span>
997 ;;
998 *<span class="o">)</span>
999 <span class="nb">echo</span> <span class="s2">&quot;Usage: /etc/init.d/glassfish {start|stop}&quot;</span>
1000
1001 <span class="nb">exit </span>1
1002 <span class="k">esac</span>
1003 <span class="nb">exit </span>0
1004 </pre></div>
1005 </div>
1006 </div>
1007 <div class="section" id="enabling-secure-remote-access-to-asadmin">
1008 <h3>Enabling secure remote access to Asadmin<a class="headerlink" href="#enabling-secure-remote-access-to-asadmin" title="Permalink to this headline">¶</a></h3>
1009 <p>As was mentioned in the Glassfish section of the manual, in version
1010 3.1.2 admin interface (asadmin) is configured to be accessible on the
1011 localhost interface only. If you need to be able to access the admin
1012 console remotely, you will have to enable secure access to it. (It will
1013 be accessible over https only, at <tt class="docutils literal"><span class="pre">https://&lt;YOUR</span> <span class="pre">HOST&gt;:4848</span></tt>; connections
1014 to <tt class="docutils literal"><span class="pre">http://&lt;YOUR</span> <span class="pre">HOST&gt;:4848</span></tt> will be automatically redirected to the https
1015 interface)</p>
1016 <p>The following must be done as root:</p>
1017 <ol class="arabic">
1018 <li><p class="first">First you need to configure the admin password:</p>
1019 <p><tt class="docutils literal"><span class="pre">&lt;GF</span> <span class="pre">LOCATION&gt;/glassfish3/bin/asadmin</span> <span class="pre">change-admin-password</span></tt></p>
1020 <p>(since you didn&#8217;t create one when you were installing Glassfish, leave the &#8220;current password&#8221; blank, i.e., hit ENTER)</p>
1021 </li>
1022 <li><p class="first">Enable the secure access:</p>
1023 </li>
1024 </ol>
1025 <blockquote>
1026 <div><p><tt class="docutils literal"><span class="pre">&lt;GF</span> <span class="pre">LOCATION&gt;/glassfish3/bin/asadmin</span> <span class="pre">enable-secure-admin</span></tt></p>
1027 <p>(Note that you will need to restart Glassfish after step 2. above)</p>
1028 </div></blockquote>
1029 </div>
1030 <div class="section" id="using-lockss-with-dvn">
1031 <span id="id11"></span><h3>Using LOCKSS with DVN<a class="headerlink" href="#using-lockss-with-dvn" title="Permalink to this headline">¶</a></h3>
1032 <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>
1033 <p>The current stable version of the plugin is available at the following location:</p>
1034 <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>
1035 <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>
1036 <p>In order to crawl a DVN, the following steps need to be performed:</p>
1037 <ol class="arabic">
1038 <li><p class="first">Point your LOCKSS daemon to the plugin repository above. (Refer to the LOCKSS documentation for details);</p>
1039 </li>
1040 <li><p class="first">Create a LOCKSS Archival Unit for your target DVN:</p>
1041 <p>In the LOCKSS Admin Console, go to <strong>Journal Configuration</strong> -&gt; <strong>Manual Add/Edit</strong> and click on <strong>Add Archival Unit</strong>.</p>
1042 <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>
1043 <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>
1044 </li>
1045 </ol>
1046 <p>Note that LOCKSS crawling must be authorized on the DVN side. Refer to
1047 the <a class="reference internal" href="dataverse-user-main.html#edit-lockss-harvest-settings"><em>&#8220;Edit LOCKSS Settings&#8221;</em></a>
1048 section of the DVN Network Administrator Guide for the instructions on
1049 enabling LOCKSS crawling on the network level, and/or to the
1050 <a class="reference internal" href="dataverse-user-main.html#enabling-lockss-access-to-the-dataverse"><em>Enabling LOCKSS access to the Dataverse</em></a>
1051 of the Dataverse Administration Guide. Once you allow LOCKSS crawling of
1052 your Dataverse(s), you will need to enter the URL of the &#8220;LOCKSS
1053 Manifest&#8221; page provided by the DVN in the configuration above. For the
1054 network-wide archival unit this URL will be
1055 <tt class="docutils literal"><span class="pre">http</span></tt><tt class="docutils literal"><span class="pre">://&lt;YOUR</span> <span class="pre">SERVER&gt;/dvn/faces/ManifestPage.xhtml</span></tt>; for an
1056 individual dataverse it is
1057 <tt class="docutils literal"><span class="pre">http</span></tt><tt class="docutils literal"><span class="pre">://&lt;YOUR</span> <span class="pre">SERVER&gt;/dvn/dv/&lt;DV</span> <span class="pre">ALIAS&gt;/faces/ManifestPage.xhtml.</span></tt></p>
1058 <div class="line-block">
1059 <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">://&lt;YOUR</span> <span class="pre">DVN</span> <span class="pre">HOST&gt;/dvn/OAIHandler</span></tt>.</div>
1060 </div>
1061 </div>
1062 <div class="section" id="read-only-mode">
1063 <h3>Read Only Mode<a class="headerlink" href="#read-only-mode" title="Permalink to this headline">¶</a></h3>
1064 <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.
1065 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>
1066 <p>To set to Read Only Mode:</p>
1067 <blockquote>
1068 <div><div class="line-block">
1069 <div class="line"><tt class="docutils literal"><span class="pre">BEGIN;</span></tt></div>
1070 <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>
1071 <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>
1072 <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>
1073 <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">&quot;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.&quot;;</span></tt></div>
1074 <div class="line"><tt class="docutils literal"><span class="pre">ALTER</span> <span class="pre">DATABASE</span> <span class="pre">&quot;dvnDb&quot;</span> <span class="pre">set</span> <span class="pre">default_transaction_read_only=on;</span></tt></div>
1075 <div class="line"><tt class="docutils literal"><span class="pre">Alter</span> <span class="pre">user</span> <span class="pre">&quot;dvnApp&quot;</span> <span class="pre">set</span> <span class="pre">default_transaction_read_only=on;</span></tt></div>
1076 <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">&quot;&quot;;</span></tt></div>
1077 <div class="line"><tt class="docutils literal"><span class="pre">END;</span></tt></div>
1078 </div>
1079 </div></blockquote>
1080 <p>To return to regular service:</p>
1081 <blockquote>
1082 <div><div class="line-block">
1083 <div class="line"><tt class="docutils literal"><span class="pre">BEGIN;</span></tt></div>
1084 <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>
1085 <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>
1086 <div class="line"><tt class="docutils literal"><span class="pre">ALTER</span> <span class="pre">DATABASE</span> <span class="pre">&quot;dvnDb&quot;</span> <span class="pre">set</span> <span class="pre">default_transaction_read_only=off;</span></tt></div>
1087 <div class="line"><tt class="docutils literal"><span class="pre">Alter</span> <span class="pre">user</span> <span class="pre">&quot;dvnApp&quot;</span> <span class="pre">set</span> <span class="pre">default_transaction_read_only=off;</span></tt></div>
1088 <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">&quot;&quot;;</span></tt></div>
1089 <div class="line"><tt class="docutils literal"><span class="pre">END;</span></tt></div>
1090 </div>
1091 </div></blockquote>
1092 </div>
1093 <div class="section" id="backup-and-restore">
1094 <h3>Backup and Restore<a class="headerlink" href="#backup-and-restore" title="Permalink to this headline">¶</a></h3>
1095 <p><strong>Backup</strong></p>
1096 <div class="line-block">
1097 <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>
1098 </div>
1099 <p>Glassfish configuration files (i.e. domain.xml, robots.txt) and local
1100 customizations (i.e. images in the docroot) should be backed up as well.
1101 In practice, it is best to simply back up the entire Glassfish directory
1102 as other files such as logs may be of interest.</p>
1103 <div class="line-block">
1104 <div class="line"><strong>Restore</strong></div>
1105 </div>
1106 <p>Restoring DVN consists of restoring the PostgreSQL database and the
1107 Glassfish directory.</p>
1108 </div>
1109 </div>
1110 </div>
1111
1112
1113 </div>
1114 </div>
1115 </div>
1116 </div>
1117 <div class="sidebar">
1118 <h3>Table Of Contents</h3>
1119 <ul class="current">
1120 <li class="toctree-l1"><a class="reference internal" href="dataverse-user-main.html">User Guide</a></li>
1121 <li class="toctree-l1 current"><a class="current reference internal" href="">Installers Guide</a><ul>
1122 <li class="toctree-l2"><a class="reference internal" href="#quick-install">Quick Install</a></li>
1123 <li class="toctree-l2"><a class="reference internal" href="#system-requirements">SYSTEM REQUIREMENTS</a></li>
1124 <li class="toctree-l2"><a class="reference internal" href="#prerequisites">PREREQUISITES</a><ul>
1125 <li class="toctree-l3"><a class="reference internal" href="#glassfish">Glassfish</a></li>
1126 <li class="toctree-l3"><a class="reference internal" href="#postgresql">PostgreSQL</a></li>
1127 <li class="toctree-l3"><a class="reference internal" href="#r-and-rserve">R and RServe</a></li>
1128 <li class="toctree-l3"><a class="reference internal" href="#system-configuration">System Configuration</a></li>
1129 </ul>
1130 </li>
1131 <li class="toctree-l2"><a class="reference internal" href="#running-the-installer">RUNNING THE INSTALLER</a></li>
1132 <li class="toctree-l2"><a class="reference internal" href="#optional-components">Optional Components</a><ul>
1133 <li class="toctree-l3"><a class="reference internal" href="#recaptcha-bot-blocker">reCAPTCHA bot blocker</a></li>
1134 <li class="toctree-l3"><a class="reference internal" href="#google-analytics">Google Analytics</a></li>
1135 <li class="toctree-l3"><a class="reference internal" href="#imagemagick">ImageMagick</a></li>
1136 <li class="toctree-l3"><a class="reference internal" href="#handle-system">Handle System</a></li>
1137 <li class="toctree-l3"><a class="reference internal" href="#twitter-setup">Twitter setup</a></li>
1138 <li class="toctree-l3"><a class="reference internal" href="#digital-object-identifiers">Digital Object Identifiers</a></li>
1139 </ul>
1140 </li>
1141 <li class="toctree-l2"><a class="reference internal" href="#appendix">Appendix</a><ul>
1142 <li class="toctree-l3"><a class="reference internal" href="#do-you-need-r">Do you need R?</a></li>
1143 <li class="toctree-l3"><a class="reference internal" href="#what-does-the-installer-do">What does the Installer do?</a></li>
1144 <li class="toctree-l3"><a class="reference internal" href="#glassfish-configuration-template">Glassfish configuration template</a></li>
1145 <li class="toctree-l3"><a class="reference internal" href="#glassfish-configuration-individual-settings">Glassfish Configuration, individual settings</a><ul>
1146 <li class="toctree-l4"><a class="reference internal" href="#jvm-options">JVM options</a></li>
1147 <li class="toctree-l4"><a class="reference internal" href="#ejb-container">EJB Container</a></li>
1148 <li class="toctree-l4"><a class="reference internal" href="#http-service">HTTP Service</a></li>
1149 <li class="toctree-l4"><a class="reference internal" href="#javamail-session">JavaMail Session</a></li>
1150 <li class="toctree-l4"><a class="reference internal" href="#jdbc-resources">JDBC Resources</a></li>
1151 <li class="toctree-l4"><a class="reference internal" href="#jms-resources">JMS Resources</a></li>
1152 </ul>
1153 </li>
1154 <li class="toctree-l3"><a class="reference internal" href="#postgresql-setup">PostgreSQL setup</a></li>
1155 <li class="toctree-l3"><a class="reference internal" href="#redhat-startup-file-for-glassfish-example">RedHat startup file for glassfish, example</a></li>
1156 <li class="toctree-l3"><a class="reference internal" href="#enabling-secure-remote-access-to-asadmin">Enabling secure remote access to Asadmin</a></li>
1157 <li class="toctree-l3"><a class="reference internal" href="#using-lockss-with-dvn">Using LOCKSS with DVN</a></li>
1158 <li class="toctree-l3"><a class="reference internal" href="#read-only-mode">Read Only Mode</a></li>
1159 <li class="toctree-l3"><a class="reference internal" href="#backup-and-restore">Backup and Restore</a></li>
1160 </ul>
1161 </li>
1162 </ul>
1163 </li>
1164 <li class="toctree-l1"><a class="reference internal" href="dataverse-developer-main.html">DVN Developers Guide</a></li>
1165 <li class="toctree-l1"><a class="reference internal" href="dataverse-api-main.html">APIs Guide</a></li>
1166 </ul>
1167
1168 <h3 style="margin-top: 1.5em;">Search</h3>
1169 <form class="search" action="search.html" method="get">
1170 <input type="text" name="q" />
1171 <input type="submit" value="Go" />
1172 <input type="hidden" name="check_keywords" value="yes" />
1173 <input type="hidden" name="area" value="default" />
1174 </form>
1175 <p class="searchtip" style="font-size: 90%">
1176 Enter search terms.
1177 </p>
1178 </div>
1179 <div class="clearer"></div>
1180 </div>
1181 </div>
1182
1183 <div class="footer-wrapper">
1184 <div class="footer">
1185 <div class="left">
1186 <a href="dataverse-user-main.html" title="User Guide"
1187 >previous</a> |
1188 <a href="dataverse-developer-main.html" title="DVN Developers Guide"
1189 >next</a> |
1190 <a href="genindex.html" title="General Index"
1191 >index</a>
1192 <br/>
1193 <a href="_sources/dataverse-installer-main.txt"
1194 rel="nofollow">Show Source</a>
1195 </div>
1196
1197 <div class="right">
1198
1199 <div class="footer">
1200 &copy; Copyright 1997-2013, President &amp; Fellows Harvard University.
1201 Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
1202 </div>
1203 </div>
1204 <div class="clearer"></div>
1205 </div>
1206 </div>
1207
1208 </body>
1209 </html>