Project

General

Profile

« Previous | Next » 

Revision 6838

Added by Matt Jones about 11 years ago

Updated the Installation chapter, coverted to RST.

View differences:

docs/dev/metacat/source/themes/readable/static/readable.css
36 36
pre {
37 37
    font-family: 'Consolas', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
38 38
    font-size: 0.95em;
39
    font-weight: bold;
39 40
    letter-spacing: 0.015em;
40 41
    padding: 0.5em;
41
    border: 1px solid #ccc;
42
    background-color: #f8f8f8;
42
    border: 1px solid darkGray;
43
    background-color: white;
44
    color: #203030;
45
    margin-left: 1em;
43 46
}
44 47

  
45 48
td.linenos pre {
......
303 306
    margin: 0 0 0.5em 1em;
304 307
    border: 1px solid #ddb;
305 308
    padding: 7px 7px 0 7px;
306
    background-color: #ffe;
309
    background-color: #B3B4C9;
307 310
    width: 40%;
308 311
    float: right;
309 312
}
docs/dev/metacat/source/install.rst
1 1
Downloading and Installing Metacat
2 2
==================================
3 3

  
4
Under construction!
4
Instructions for both Linux and Windows systems are included in this section.
5 5

  
6
.. contents::
7

  
6 8
System Requirements
7 9
-------------------
10
In addition to meeting the recommended system requirements, the server on which
11
you wish to install Metacat must have the following software installed and
12
running correctly:
8 13

  
14
* PostgreSQL_ (or another SQL92-compliant RDBMS like Oracle_) 
15
* `Apache Ant`_ (if building from source)
16
* `Apache Tomcat`_ 
17
* `Apache HTTPD Server`_ (recommended)
18

  
19
  * In order to use the Metacat Registry (and for a more robust Web-serving environment in general), the Apache Web server should be installed with Tomcat and the two should be integrated. See the installing Apache for more information.
20

  
21
* Java_ 6 (Note: Java 5 is deprecated)
22

  
23
.. _PostgreSQL: http://www.postgresql.org/
24

  
25
.. _Oracle: http://www.oracle.com/
26

  
27
.. _Apache Ant: http://ant.apache.org/
28

  
29
.. _Apache Tomcat: http://tomcat.apache.org/
30

  
31
.. _Apache HTTPD Server: http://httpd.apache.org/
32

  
33
.. _Java: http://www.oracle.com/technetwork/java/javaee/overview/index.html
34

  
35
System requirements for running Metacat:
36

  
37
.. NOTE::
38

  
39
   Check these system requirements
40

  
41
* a server running an SQL92-compliant database (PostgreSQL_ recommended) 
42
* at least 128MB RAM
43
* a Pentium III processor (or higher)
44
* 11 MB disk space (Note: The amount of disk space required depends on the size of your RDBMS tablespace (which should be at least 10 MB; however, Metacat itself requires only about 140 MB of free space after installation).
45

  
46

  
9 47
Installing on Linux
10 48
-------------------
49
This section contains instructions for downloading and installing Metacat on 
50
Linux systems. As Mac OS X is based on BSD Unix, these Linux instructions can
51
be adapted to also work on Mac OS X (although the exact commands for
52
downloading and installing packages will differ due to the different package
53
management approaches on the Mac).
11 54

  
12 55
Quick Start Overview
13 56
~~~~~~~~~~~~~~~~~~~~
57
For the impatient or those who have already installed Metacat and know what
58
they are doing, here are the steps needed to install Metacat. Detailed
59
instructions for each step are in the next section.
14 60

  
61
1. Download and install prerequisites (Java_ 6, `Apache Tomcat`_ 6, PostgreSQL_, `Apache HTTPD Server`_), including the tomcat6 init.d script
62
2. Create a database in PostgreSQL named 'metacat' and authorize access to it in ``pb_hba.conf`` for the user 'metacat'
63
3. Log in to PostgreSQL and create the 'metacat' user
64
4. Download Metacat from the `Metacat Download Page`_ and extract the archive
65
5. ``sudo mkdir /var/metacat; sudo chown -R <tomcat_user> /var/metacat``
66
6. ``sudo cp <metacat_package_dir>/knb.war <tomcat_app_dir>``
67
7. ``sudo /etc/init.d/tomcat5.5 restart``
68
8. Configure Metacat through the Web interface
69

  
70
.. _Metacat Download Page: http://knb.ecoinformatics.org/software/metacat/
71

  
15 72
Downloading Metacat
16 73
~~~~~~~~~~~~~~~~~~~
74
Before installing Metacat, please ensure that all required software is
75
installed and running correctly. To obtain a Metacat WAR file, which is needed
76
for installation, download one of the following: 
17 77

  
78
* the Metacat installer, which has a pre-built WAR file,
79
* the Metacat source distribution, which must be built in order to create a WAR file, 
80
* the Metacat source code from SVN. You must build the source code in order to create a WAR file. 
81

  
82
Instructions for all three options are discussed below. Note that downloading
83
the installer (described in the next section) is the simplest way to get
84
started. 
85

  
18 86
Download the Metacat Installer
19 87
..............................
88
Downloading the Metacat Installer is the simplest way to get started with the
89
application. To download the installer: 
20 90

  
91
1.  Browse to the `Metacat Download Page`_. In the Metacat section, select the link to the "GZIP file" (the link should look like: metacat-bin-X.X.X.tar.gz, where X.X.X is the latest version of Metacat e.g., 1.9.0) 
92
2.  Save the file locally. 
93
3.  Extract the Metacat package files by typing:
94

  
95
::
96

  
97
  tar -xvzf metacat-bin-X.X.X.tar.gz
98

  
99
You should see a WAR file and several supporting files (Table 2.1). The
100
extraction location will be referred to as the ``<metacat_package_dir>`` for the
101
remainder of this documentation.
102

  
103
================== ===========================================================
104
File               Description
105
================== ===========================================================
106
knb.war            The Metacat Web archive file (WAR) 
107
knb                The Web definition file used by Apache on Ubuntu/Debian 
108
                   Linux systems. 
109
Knb.ssl            The SSL definition file used by Apache on Ubuntu/Debian 
110
                   Linux systems.
111
jk.conf            The JkMount configuration file used by Apache on 
112
                   Ubuntu/Debian Linux systems. 
113
workers.properties The workers definition file used by Apache on Ubuntu/Debian 
114
                   Linux systems. 
115
tomcat5.5          The Tomcat startup script for Tomcat 5.5 installed with 
116
                   apt-get on Ubuntu/Debian Linux systems.
117
authority          The optional LSID Server application WAR
118
================== ===========================================================
119

  
120

  
21 121
Download Metacat Source Code
22 122
............................
123
To get the Metacat source distribution:
23 124

  
125
1. Browse to the `Metacat Download Page`_. In the Metacat section, select the link to the Metacat Source code (it will look something like this: metacat-src-X.X.X.tar.gz, where X.X.X is the latest version of Metacat, e.g., 1.9.0).
126
2. Save the file locally. 
127
3. Extract the Metacat package files by typing (replace X.X.X with the current version number): 
128

  
129
::
130

  
131
  tar -xvzf metacat-src-X.X.X.tar.gz
132

  
133
4. Rename the metacat-X.X.X directory to metacat. 
134

  
135
Note that you do not need to create the WAR file directly because the Ant
136
build-file has an "install" target that will build and deploy the WAR for you. 
137

  
138

  
24 139
Check Out Metacat Source Code from SVN (for Developers)
25 140
.......................................................
141
If you wish to work with the most recent Metacat code, or you'd like to extend
142
the Metacat code yourself, you may wish to check out the Metacat source code
143
from SVN. You will need a Subversion (SVN) client installed and configured on
144
your system (see the end of this section for information about obtaining an SVN
145
client). 
26 146

  
147
.. sidebar:: Installing an SVN Client:
148

  
149
    If you have not already installed Subversion and you are running Ubuntu/Debian,
150
    you can get the SVN client by typing:
151
    
152
    ::
153

  
154
        sudo apt-get install subversion
155

  
156
    Otherwise, you can get the SVN client from The Subversion homepage
157
    (http://subversion.tigris.org/).
158

  
159
To check out the code from SVN, go to the directory where you would like the
160
code to live and type::
161

  
162
  svn co https://code.ecoinformatics.org/code/metacat/tags/METACAT_<rev> metacat
163

  
164
Where ``<rev>`` is the version of the code you want to check out (like 1_9). 
165

  
166
To check out the head, type::
167

  
168
  svn co https://code.ecoinformatics.org/code/metacat/trunk metacat
169

  
170
You should see a list of files as they check out.
171

  
172
Note that you do not need to create the WAR file directly because the Ant
173
build-file has an "install" target that will build and deploy the WAR for you. 
174

  
175

  
27 176
Installing and Configuring Required Software
28 177
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
178
Before you can install and run Metacat, you must ensure that a recent Java SDK,
179
PostgreSQL (or another SQL92-compliant RDBMS like Oracle 8i), Ant (if
180
installing from source), and Tomcat are installed and running correctly. We
181
also highly recommend that you install Apache Web server, as it provides a more
182
robust Web-serving environment and is required by some Metacat functionality. 
29 183

  
184
* Java_ 6
185
* `Apache Tomcat`_ 
186
* `Apache HTTPD Server`_ (Highly Recommended)
187
* PostgreSQL_ Database (or Oracle_)
188
* `Apache Ant`_ (if building from Source)
189

  
30 190
Java 6
31 191
......
192
To run Metacat, you should use Java 6 (Java 5 is deprecated and will not be
193
supported after Metacat version 1.9.2). Make sure that the JAVA_HOME
194
environment variable is properly set and that both ``java`` and ``javac`` 
195
are on your PATH. 
32 196

  
33
Apache Jakarta-Tomcat
34
.....................
197
To install Java if you are running Ubuntu_/Debian, type::
35 198

  
36
Apache Web Server (Highly Recommended)
37
......................................
199
  sudo apt-get install sun-java6-jdk
38 200

  
39
PostgreSQL Database (or Oracle 8i)
40
..................................
201
Click "ok" then "yes" for license agreement.
41 202

  
203
If you are not using Ubuntu_/Debian, you can get Java from the Oracle_ website.
204

  
205
.. _Ubuntu: http://www.ubuntu.com/
206

  
207
Apache Tomcat
208
.............
209
We recommend that you install Tomcat 6 into the directory of your choice.
210
Included with the Metacat download is a Tomcat-friendly start-up script that
211
should be installed as well.
212

  
213
Note: we will refer to the Tomcat installation directory as ``<tomcat_home>`` for
214
the remainder of the documentation. 
215

  
216
If you are running Ubuntu_/Debian, get Tomcat by typing::
217

  
218
  sudo apt-get install tomcat5.5
219

  
220
Otherwise, get Tomcat from the `Apache Tomcat`_ page.
221

  
222
Install the Metacat-friendly Tomcat start-up script by typing::
223

  
224
  sudo /etc/init.d/tomcat5.5 stop
225
  sudo mv /etc/init.d/tomcat5.5 /etc/init.d/tomcat5.5.bak
226
  sudo cp <metacat_package_dir>/debian/tomcat5.5 /etc/init.d/tomcat5.5
227
  sudo chmod +x /etc/init.d/tomcat5.5
228

  
229

  
230
Apache HTTPD Server (Highly Recommended)
231
........................................
232
Although you have the option of running Metacat with only the Tomcat server, we
233
highly recommend that you run it behind the Apache Web server for several
234
reasons; running Tomcat with the Apache server provides a more robust Web
235
serving environment, and the Apache Web server is required if you wish to
236
install and run the Metacat Registry. 
237

  
238
.. sidebar:: Configuring Apache on an OS other than Ubuntu/Debian 
239

  
240
  If you are running on an O/S other than Ubuntu/Debian (e.g., Fedora Core or
241
  RedHat Linux) or if you installed the Apache source or binary, you must
242
  manually edit the Apache configuration file, where <apache_install_dir> is the
243
  directory in which Apache is installed:
244

  
245
  ::
246

  
247
    <apache_install_dir>/conf/httpd.conf
248

  
249
  1. Configure the log location and level for Mod JK. If your configuration file does not already have the following section, add it and set the log location to any place you'd like:
250

  
251
    ::
252

  
253
      <IfModule mod_jk.c> 
254
        JkLogFile "/var/log/tomcat/mod_jk.log" 
255
        JkLogLevel info 
256
      </IfModule> 
257

  
258
  2. Configure apache to route traffic to the Metacat application. ServerName should be set to the DNS name of the Metacat server. ScriptAlias and the following Directory section should both point to the cgi-bin directory inside your Metacat installation:
259

  
260
    ::
261

  
262
      <VirtualHost XXX.XXX.XXX.XXX:80> 
263
        DocumentRoot /var/www 
264
        ServerName dev.nceas.ucsb.edu 
265
        ErrorLog /var/log/httpd/error_log 
266
        CustomLog /var/log/httpd/access_log common 
267
        ScriptAlias /cgi-bin/ "/var/www/cgi-knb/" 
268
        <Directory /var/www/cgi-knb/> 
269
          AllowOverride None 
270
          Options ExecCGI 
271
          Order allow,deny 
272
          Allow from all 
273
        </Directory> 
274
        ScriptAlias /knb/cgi-bin/ "/var/www/webapps/knb/cgi-bin/" 
275
        <Directory "/var/www/webapps/knb/cgi-bin/"> 
276
          AllowOverride None 
277
          Options ExecCGI 
278
          Order allow,deny 
279
          Allow from all 
280
        </Directory> 
281
        JkMount /knb ajp13 
282
        JkMount /knb/* ajp13 
283
        JkMount /knb/metacat ajp13 
284
        JkUnMount /knb/cgi-bin/* ajp13 
285
        JkMount /*.jsp ajp13 
286
        JkMount /metacat ajp13 
287
        JkMount /metacat/* ajp13 
288
      </VirtualHost> 
289

  
290
  3. Copy the "workers.properties" file provided by Metacat into your Apache configuration directory (<apache_install_dir>/conf/).  Depending on whether you are installing from binary distribution or source, the workers.properties file will be in one of two locations:
291

  
292
    * the directory in which you extracted the Metacat distribution (for binary distribution)
293
    * <metacat_code_dir>/src/scripts/workers.properties (for both the source distribution and source code checked out from SVN)
294

  
295
  4. Edit the workers.properties file and make sure the following properties are set correctly:
296

  
297
    ::
298

  
299
      workers.tomcat_home -  set to the Tomcat install directory. 
300
      workers.java_home - set to the Java install directory. 
301

  
302
  5. Restart Apache to bring in changes by typing:
303

  
304
    ::
305

  
306
      sudo /etc/init.d/apache2 restart
307

  
308
This section contains instructions for installing and configuring the Apache
309
Web server for Metacat on an Ubuntu_/Debian system. Instructions for configuring
310
Apache running on other Linux systems are included in the sidebar.
311

  
312
1. Install the Apache and Mod JK packages (Mod JK is the module Apache uses to talk to Tomcat applications) by typing:
313

  
314
::
315

  
316
  sudo apt-get install apache2 libapache2-mod-jk
317

  
318
If you are installing the Apache server on an Ubuntu/Debian system, and you
319
installed Apache using apt-get as described above, the Metacat code will have
320
helper files that can be dropped into directories to configure Apache.
321
Depending on whether you are installing from binary distribution or source,
322
these helper files will be in one of two locations: 
323

  
324
* the directory in which you extracted the distribution (for binary distribution)
325
* ``<metacat_code_dir>/src/scripts`` (for both the source distribution and source code checked out from SVN).  We will refer to the directory with the helper scripts as ``<metacat_helper_dir>`` and the directory where Apache is installed (e.g., ``/etc/apache2/``) as ``<apache_install_dir>``.
326

  
327
2. Set up Mod JK apache configuration by typing:
328

  
329
::
330

  
331
  sudo cp <metacat_helper_dir>/jk.conf <apache_install_dir>/mods-available
332
  sudo cp <metacat_helper_dir>/workers.properties <apache_install_dir>
333

  
334
3. Disable and re-enable the Apache Mod JK module to pick up the new changes:
335

  
336
::
337

  
338
  sudo a2dismod jk
339
  sudo a2enmod jk
340

  
341
4. Apache needs to know about the Metacat site. The helper file named "knb" has rules that tell Apache which traffic to route to Metacat. Set up the knb (Metacat) site by dropping the knb file into the sites-available directory and running a2ensite to enable the site:
342

  
343
::
344

  
345
  sudo cp <metacat_helper_dir>/knb <apache_install_dir>/sites-available
346
  sudo a2ensite knb
347

  
348
5. Restart Apache to bring in changes by typing:
349

  
350
::
351

  
352
  sudo /etc/init.d/apache2 restart
353

  
354

  
355
PostgreSQL Database 
356
...................
357
Metacat has been most widely tested with PostgreSQL_ and we recommend using it.
358
Instructions for installing and configuring Oracle are also included in the
359
next section.  To install and configure PostgreSQL_:
360

  
361
1. If you are running Ubuntu_/Debian, get PostgreSQL by typing:
362

  
363
  ::
364

  
365
    sudo apt-get install postgresql
366

  
367
  On other systems, install the rpms for postgres.
368

  
369
2. Start the database by running:
370

  
371
  ::
372

  
373
    /etc/init.d/postgresql start
374

  
375
3. Change to postgres user: 
376

  
377
  ::
378

  
379
    sudo su - postgres
380

  
381

  
382
4. Set up an empty Metacat database instance by editing the postgreSQL configuration file: 
383

  
384
  ::
385

  
386
    gedit /etc/postgresql/8.3/main/pg_hba.conf
387

  
388

  
389
  Add the following line to the configuration file: 
390

  
391
  ::
392

  
393
    host metacat metacat 127.0.0.1 255.255.255.255 password
394

  
395

  
396
  Save the file and then create the Metacat instance: 
397

  
398
  ::
399

  
400
    createdb metacat
401

  
402

  
403
5. Log in to postgreSQL by typing: 
404

  
405
  ::
406

  
407
    psql metacat
408

  
409

  
410
6. At the psql prompt, create the Metacat user by typing:
411

  
412
  ::
413

  
414
    CREATE USER metacat WITH UNENCRYPTED PASSWORD 'your_password';
415

  
416
  where 'your_password' is whatever password you would like for the Metacat user. 
417

  
418
7. Exit PostgreSQL by typing 
419

  
420
  ::
421

  
422
    \q
423

  
424
8. Restart the PostgreSQL database to bring in changes: 
425

  
426
  ::
427

  
428
    /etc/init.d/postgresql-8.3 restart
429

  
430
9. Log out of the postgres user account by typing: 
431

  
432
  ::
433

  
434
    logout
435

  
436
10. Test the installation and Metacat account by typing: 
437

  
438
  ::
439

  
440
    psql -U metacat -W -h localhost metacat
441

  
442
11. Log out of postgreSQL: 
443

  
444
  ::
445

  
446
    \q
447

  
448

  
449
The Metacat servlet automatically creates the required database schema. For
450
more information about configuring the database, please see Database
451
Configuration.
452

  
42 453
Installing and Configuring Oracle 8i
43 454
....................................
455
To use Oracle 8i with Metacat, the Oracle RDBMS must be installed and running
456
as a daemon on the system. In addition the JDBC listener must be enabled.
457
Enable it by logging in as an Oracle user and typing::
44 458

  
45
Apache Jakarta-Ant (if building from Source)
46
............................................
459
  lsnrctl start
47 460

  
461
Your instance should have a table space of at least 5 MB (10 MB or higher
462
recommended). You must also create and enable a username specific to Metacat.
463
The Metacat user must have most normal permissions including: CREATE SESSION,
464
CREATE TABLE, CREATE INDEX, CREATE TRIGGER, EXECUTE PROCEDURE, EXECUTE TYPE,
465
etc. If an action is unexplainably rejected by Metacat, the user permissions
466
are (most likely) not correctly set.
467

  
468
The Metacat servlet automatically creates the required database schema. For
469
more information, please see Database Configuration.
470

  
471
Apache Ant (if building from Source)
472
....................................
473
If you are building Metacat from a source distribution or from source code
474
checked out from SVN, Ant is required. (Users installing Metacat from the
475
binary distribution do not require it.) Ant is a Java-based build application
476
similar to Make on UNIX systems. It takes build instructions from a file named
477
"build.xml", which is found in the root installation directory. Metacat source
478
code comes with a default "build.xml" file that may require some modification
479
upon installation. 
480

  
481
If you are running Ubuntu/Debian, get Ant by typing::
482

  
483
  sudo apt-get install ant
484

  
485
Otherwise, get Ant from the `Apache Ant`_ homepage.
486

  
487
Ant should be installed on your system and the "ant" executable shell script
488
should be available in the user's path. The latest Metacat release was tested
489
with Ant 1.6.5. 
490

  
48 491
Installing Metacat
49 492
~~~~~~~~~~~~~~~~~~
493
Instructions for a new install, an upgrade, and a source install are included
494
below.
50 495

  
496
New Install
497
...........
498
Before installing Metacat, please ensure that all required applications are
499
installed, configured to run with Metacat, and running correctly. If you are
500
upgrading an existing Metacat servlet, please skip to Upgrade. For information
501
about installing from source, skip to Source Install and Upgrade.
502

  
503
To install a new Metacat servlet:
504

  
505
1. Create the Metacat directory. Metacat uses a base directory to store data, metadata, temporary files, and configuration backups. This directory should be outside of the Tomcat application directory so that it will not get wiped out during an upgrade. Typically, the directory is '/var/metacat', as shown in the instructions. If you choose a different location, remember it. You will be asked to configure Metacat to point to the base directory at startup.  Create the Metacat directory by typing:
506

  
507
  ::
508

  
509
    sudo mkdir /var/metacat
510

  
511
2. Change the ownership of the directory to the user that will start Tomcat by typing (note: If you are starting Tomcat as the root user, you do not need to run the chown command):
512

  
513
  ::
514

  
515
    sudo chown -R <tomcat_user> /var/metacat
516

  
517

  
518
3)  Install the Metacat WAR in the Tomcat web-application directory. For instructions on downloading the Metacat WAR, please see Downloading Metacat.  Typically, Tomcat will look for its application files (WAR files) in the <tomcat_home>/webapps directory (e.g., /usr/share/tomcat5.5/webapps). Your instance of Tomcat may be configured to look in a different directory. We will refer to the Tomcat application directory as <tomcat_app_dir>.  NOTE: The name of the WAR file (e.g., knb.war) provides the application context, which appears in the URL of the Metacat (e.g., http://yourserver.com/knb/). To change the context, simply change the name of the WAR file to the desired name before copying it.  To install the Metacat WAR:
519

  
520
  ::
521

  
522
    sudo cp <metacat_package_dir>/knb.war <tomcat_app_dir>
523

  
524

  
525
4. Restart Tomcat. Log in as the user that runs your Tomcat server (often "tomcat") and type:  
526

  
527
  ::
528

  
529
    /etc/init.d/tomcat5.5 restart
530

  
531
Congratulations! You have now installed Metacat. If everything is installed
532
correctly, you should see the Authentication Configuration screen (Figure 2.1)
533
when you type http://yourserver.com/yourcontext/ (e.g.,
534
http://knb.ecoinformatics.org/knb) into a browser. For more information about
535
configuring Metacat, please see the Configuration Section.
536

  
537
.. figure:: images/screenshots/image009.jpg
538
   :align: center
539

  
540
   The Authentication Configuration screen appears the first time you open a 
541
   new installation of Metacat. 
542

  
543
Upgrade Metacat
544
...............
545
To upgrade an existing binary Metacat installation follow the steps in this
546
section. The steps for upgrading Metacat from source are the same as the
547
instructions for installing from source:
548

  
549
1. Download and extract the new version of Metacat. For more information about downloading and extracting Metacat, please see Downloading Metacat.
550

  
551
2. Stop running Metacat. To stop Metacat, log in as the user that runs your Tomcat server (often "tomcat") and type:
552

  
553
  ::
554

  
555
    /etc/init.d/tomcat5.5 stop
556

  
557
3. Back up the existing Metacat installation. Although not required, we highly recommend that you back up your existing Metacat to a backup directory (<backup_dir>) before installing a new one. You can do so by typing:
558

  
559
  ::
560

  
561
    cp <web_app_dir>/knb <backup_dir>/knb.<yyyymmdd>
562
    cp <web_app_dir>/knb.war <backup_dir>/knb.war.<yyyymmdd>
563

  
564
  Warning: Do not backup the files to the ``<web_app_dir>`` directory.  Tomcat will
565
  try to run the backup copy as a service.
566

  
567
4. Copy the new Metacat WAR file in to the Tomcat applications directory: 
568

  
569
  ::
570

  
571
    sudo cp <metacat_package_dir>/knb.war <tomcat_app_dir>
572

  
573
  Note: Typically, Tomcat will look for its application files (WAR files) in the
574
  ``<tomcat_home>/webapps`` directory. Your instance of Tomcat may be configured to
575
  look in a different directory. 
576

  
577
5. If you have been (or would like to start) running an LSID server, copy the new authority.war file to the Tomcat applications directory. For more information about the LSID server, please see Optional Installation Options. 
578

  
579
  ::
580
   
581
    sudo cp <metacat_package_dir>/authority.war <tomcat_app_dir>
582

  
583
6. Restart Tomcat (and Apache if you have Tomcat integrated with it). Log in as the user that runs your Tomcat server (often "tomcat"), and type:  
584

  
585
  ::
586

  
587
    /etc/init.d/tomcat5.5 restart
588

  
589

  
590
7. Run your new Metacat servlet. Go to a Web browser and visit your installed
591
Metacat application, using a URL of the form: 
592

  
593
  ::
594

  
595
    http://yourserver.yourdomain.com/yourcontext/
596

  
597
You should substitute your context name for "yourcontext" in the URL above
598
(your context will be "knb" unless you change the name of the knb.war file to
599
something else). If everything is working correctly, you should be presented
600
with Metacat's Authorization Configuration screen. Note that if you do not have
601
Tomcat integrated with Apache you will probably have to type
602
http://yourserver.yourdomain.com:8080/yourcontext/
603

  
604
Source Install and Upgrade
605
..........................
606
Whether you are building Metacat from the source distribution or source code
607
checked out from SVN, you will need Apache Ant to do the build (see Installing
608
and Configuring Required Software for more information about Ant). 
609

  
610
To install Metacat from source:
611

  
612
1. Edit the build.properties file found in the directory in which you
613
   downloaded Metacat. Note: Throughout the instructions, we will refer to this
614
   directory as ``<metacat_src_dir>``. 
615

  
616
  * Set the build.tomcat.dir property to your Tomcat installation directory.
617
    Metacat will use some of the native Tomcat libraries during the build. For
618
    instance: build.tomcat.dir=/usr/local/tomcat
619
  * Set the app.deploy.dir property to your application deployment directory.
620
    For instance: app.deploy.dir=/usr/local/tomcat/webapps
621

  
622
2. In the ``<metacat_src_dir>``, run: 
623

  
624
  ::
625

  
626
    sudo ant clean install
627

  
628
  You will see the individual modules get built. You should see a "BUILD
629
  SUCCESSFUL" message at the end.
630

  
631
  You should see a new file named knb.war in your application deployment
632
  directory.
633

  
634
To run your new Metacat servlet, open a Web browser and type::
635

  
636
  http://yourserver.yourdomain.com/yourcontext/ 
637
  (e.g.  http://knb.ecoinformatics.org/knb/)
638

  
639
Your context will be "knb" unless you changed the name of the knb.war file to
640
something else. The servlet may require a few seconds to start up, but once it
641
is running, you will be presented with the Authorization Configuration screen.
642

  
51 643
Optional Installation Options (LSID Server)
52 644
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
53 645

  
646
.. Note::
647

  
648
  The support for LSID identifiers is deprecated, and is being replaced with
649
  support for DOI_ identifiers in a future release. We are maintaining support
650
  for LSIDs on one particular site, but this support will be removed in a
651
  future version of Metacat.
652

  
653
.. _DOI: http://www.doi.org/
654

  
655
Metacat's optional LSID server allows Metacat to use a standardized syntax for
656
identifying data sets, in addition to Metacat's internal, custom scheme for
657
identifiers. LSID's were designed to identify complex biological entities with
658
short identifiers (much like DOIs in publishing) that are both computer and
659
human readable. LSID identifiers are URIs and are therefore usable in many
660
Internet applications, but they also cleanly separate the identity of a data
661
set (i.e., its permenant identifier) from its current location (e.g., the list
662
of URLs from which it might be retrieved).  LSIDs accomplish this by using a
663
level of indirection; the identifier represents simply a name without location,
664
but an associated resolver service can be used to locate the current location
665
of the data and medata for the data set.  This is accomplished by establishing
666
a well-known location for the resolution service for each authority using an
667
infrequently used feature of the domain name system called SRV records.  At its
668
most basic, resolution of an identifier is performed when a client looks up the
669
SRV record for an LSID by querying DNS, which returns the current host and port
670
of the authority web service, which is in turn used to locate the data and
671
metadata.
672

  
673
Using LSIDs to identify data records is being debated among members of the
674
Taxonomic Databases Working Group (TDWG).  There are several alternate
675
technologies that are under consideration (e.g., DOI_, plain http URIs), and so
676
at this time the support for LSIDs in Metacat has been created on an
677
experimental basis only.  If the LSID approach is ratified by the broader
678
community, we will expand support for LSIDs in Metacat, but until then it is an
679
optional and experimental feature.
680

  
681
The format of an LSID is:: 
682

  
683
  urn:lsid:<Authority>:<Namespace>:<ObjectID>[:<Version>]
684
  e.g., urn:lsid:ecoinformatics.org:tao:12039:1
685

  
686
When you enable the Metacat LSID support, you can use LSID clients (such as
687
LSID Launchpad) and LSID notation to query Metacat for data and metadata. LSID
688
notation can be used directly in Metacat HTTP queries as well. For example, a
689
data package with an ID tao.12039.1 that is stored in a Metacat available at:
690
http://example.com:9999 can be accessed by the following HTTP Metacat queries::
691

  
692
  http://example.com:9999/authority/data?lsid=urn:lsid:ecoinformatics.org:tao:12039:1
693
  (To return the data)
694

  
695
  http://example.com:9999/authority/metadata?lsid=urn:lsid:ecoinformatics.org:tao:12039:1
696
  (To return the metadata)
697

  
698
Notice that in the HTTP query strings, the periods in the data package ID have
699
been replaced with colons. The authority (ecoinformatics.org) must be properly
700
configured by the Metacat administrator. Note: In order to configure the
701
authority, you must have access to the DNS server for the Metacat domain.
702
Further instructions are provided below.
703

  
704
Install and configure the LSID Server shipped with Metacat
705
..........................................................
706

  
707
To install the LSID server using the binary installation:
708

  
709
1. Copy the authority.war file to Tomcat:
710

  
711
  ::
712

  
713
    sudo cp <metacat_package_directory>/authority.war /usr/share/tomcat5.5/webapps
714
 
715
2. Set up the LSID server by dropping the authority file into Apache's
716
   sites-available directory and running a2ensite to enable the site:
717

  
718
   ::
719

  
720
     sudo cp <metacat_helper_dir>/authority /etc/apache2/sites-available
721
     sudo a2ensite authority
722

  
723
3. Restart Tomcat. Log in as the user that runs your Tomcat server (often
724
   "tomcat") and type:
725

  
726
   ::
727

  
728
     /etc/init.d/tomcat5.5 restart
729

  
730
4. Restart Apache to bring in changes by typing:
731

  
732
  ::
733

  
734
    sudo /etc/init.d/apache2 restart
735

  
736
5. See notes beneath LSID server source installation for instructions for
737
   modifying the SRV record(s)
738

  
739
To install the LSID server from a source
740
........................................
741

  
742
1. In the build.properties file found in the directory into which you
743
   extracted the Metacat source code, set the authority and config.lsidauthority
744
   properties. For example:
745
  
746
  ::
747
   
748
   authority.context=authority
749
   config.lsidauthority=ecoinformatics.org
750

  
751
2. In the <metacat-src-dirctory> create the authority.war by running:
752

  
753
  ::
754

  
755
    sudo ant war-lsid
756

  
757
3. Copy the LSID WAR file into the Tomcat application directory.
758

  
759
  ::
760

  
761
    sudo cp <metacat_package_dir>/dist/authority.war <tomcat_app_dir>
762

  
763
4. Restart Tomcat. Log in as the user that runs your Tomcat server (often
764
   "tomcat") and type:   
765

  
766
  ::
767

  
768
    /etc/init.d/tomcat5.5 restart
769

  
770
5. If you are running Tomcat behind the Apache server (the recommended
771
   configuration), set up and enable the authority service site configurations by
772
   typing:
773

  
774
  ::
775

  
776
    sudo cp <metacat_helper_dir>/authority <apache_install_dir>/sites-available
777
    sudo a2ensite authority
778

  
779
  Where <metacat_helper_dir> can be found in <metacat_code_dir>/src/scripts
780

  
781
6.  Restart Apache to bring in changes by typing: 
782

  
783
  ::
784

  
785
    sudo /etc/init.d/apache2 restart
786

  
787
  Once the authority.war is installed, you must also modify the SRV record(s)
788
  on the DNS server for the domain hosting the Metacat. The record should be
789
  added to the master zone file for the metacat's DNS server:
790

  
791
    ::
792

  
793
      _lsid._tcp      IN      SRV     1       0       8080    <metacat.edu>.
794

  
795
  Where <metacat.edu> is the name of the machine that will serve as the
796
  physical location of the AuthorityService.
797

  
798
  For example, the value of <metacat.edu> for the below example URL would be
799
  example.com:
800
  
801
    ::
802
    
803
      http://example.com:9999/authority/data?lsid=urn:lsid:ecoinformatics.org:tao:12039:1
804

  
805
  For more information, please see http://www.ibm.com/developerworks/opensource/library/os-lsid/
806

  
54 807
Troubleshooting
55 808
~~~~~~~~~~~~~~~
809
We keep and update a list of common problems and their solutions on the KNB
810
website. See http://knb.ecoinformatics.org/software/metacat/troubleshooting.html 
811
for more information.
56 812

  
57 813
Installing on Windows
58 814
---------------------
815
Metacat can be installed on Windows. Please follow the instructions in this
816
section for downloading Metacat, installing the required software, and
817
installing Metacat. Note that Registry and Data Upload functionality has not
818
been tested on Windows.
819

  
820
Download Metacat
821
~~~~~~~~~~~~~~~~
822
To obtain a Metacat WAR file, which is used when installing the Metacat
823
servlet:
824

  
825
1. Browse to the KNB Software Download Page. In the Metacat section, select
826
   the link that looks like: metacat-bin-X.X.X.zip, where X.X.X is the latest
827
   version of Metacat (e.g., 1.9.0).
828

  
829
2. Choose to download and Save the file locally. 
830

  
831
3. Extract the Metacat package files using your Windows zip utility. You
832
   should see a WAR file and several supporting files (we will only use the WAR
833
   file when installing Metacat). 
834

  
835
Note: The location where these files were extracted will be referred to as the
836
``<metacat_package_dir>`` for the remainder of this documentation. 
837

  
838
Note: Before installing Metacat, please ensure that all required software is
839
installed and running correctly.
840

  
841

  
842
Install Required Software
843
~~~~~~~~~~~~~~~~~~~~~~~~~
844
Before you can install and run Metacat, you must ensure that a recent Java SDK,
845
PostgreSQL and Tomcat are installed, configured, and running correctly. 
846

  
847
* Java_ 6
848
* `Apache Tomcat`_
849
* PostgreSQL_ Database
850

  
851
Java 6
852
......
853
To run Metacat, you must have Java 6. (Java 5 is deprecated). Make sure that
854
the JAVA_HOME environment variable is properly set and that both java and javac
855
are on your PATH.
856

  
857
To download and install Java:
858

  
859
1. Browse to: http://java.sun.com/javase/downloads/widget/jdk6.jsp and follow
860
   the instructions to download JDK 6.
861

  
862
2. Run the downloaded installer to install Java.
863

  
864
3. Set the JAVA_HOME environment variable: In "My Computer" properties, go to
865
   "advanced settings > environment variables". Add:
866

  
867
  ::
868

  
869
    System Variable: JAVA_HOME C:\Program Files\Java\jdk1.6.0_18 
870
    (or whichever version you downloaded)
871

  
872
Apache Tomcat
873
.............
874
We recommend that you install Tomcat version 6.  To download and install Tomcat:
875

  
876
1. Browse to: http://tomcat.apache.org/download-55.cgi 
877
2. Download the Tomcat core zip file 
878
3. Extract Tomcat files to C:\Program Files\tomcat using the windows zip
879
   utility. 
880

  
881
PostgreSQL Database
882
...................
883
Metacat can be run with several SQL92-compliant database systems, but it has 
884
been most widely tested with PostgreSQL_. Instructions for installing and 
885
configuring PostgreSQL for use with Metacat are included in this section.
886

  
887
To download and install PostgreSQL:
888

  
889
1. Browse to http://www.postgresql.org/download/windows and download the
890
   one-click installer 
891
2. Run the installer 
892
3. Edit C:\Program Files\PostgreSQL\8.3\data and add:
893
  
894
  ::
895

  
896
    host metacat metacat 127.0.0.1 255.255.255.255 password
897

  
898
4. Create a super user. At the command line, enter:
899

  
900
  ::
901

  
902
    C:\Program Files\PostgreSQL\8.3\bin 
903
    createdb -U postgres metacat (enter super user password)
904

  
905
5. Log in to PostgreSQL: 
906

  
907
  ::
908

  
909
    psql -U postgres metacat (enter super user password)
910

  
911
6. Create a Metacat user:
912

  
913
  ::
914

  
915
    CREATE USER metacat WITH UNENCRYPTED PASSWORD 'your_password'
916

  
917
7. Exit PostgreSQL: 
918

  
919
  ::
920

  
921
    \q
922

  
923
8. Restart PostgreSQL from the start menu by selecting:
924
  
925
  ::
926

  
927
    run start/All Programs/PostgreSQL 8.3/Stop Server
928
    run start/All Programs/PostgreSQL 8.3/Start Server
929

  
930

  
931
9. Test the installation by logging in as the metacat user: 
932

  
933
  ::
934
  
935
    Psql –U metacat –W –h localhost metacat
936

  
937
10. Exit PostgreSQL:
938

  
939
  ::
940

  
941
    \q
942

  
943
The Metacat servlet automatically creates the required database schema. For
944
more information, please see Database Configuration.
945

  
946
Installing Metacat
947
~~~~~~~~~~~~~~~~~~
948
Instructions for a new install and for an upgrade are included below.
949

  
950
New Install
951
...........
952
Before installing Metacat, please ensure that all required applications are
953
installed, configured to run with Metacat, and running correctly. If you are
954
upgrading an existing Metacat servlet, please skip to Upgrade.
955

  
956
To install a new Metacat servlet:
957

  
958
1. Create the Metacat base directory at: 
959

  
960
  ::
961

  
962
    C:/Program Files/metacat
963

  
964
2. Copy the Metacat WAR file to Tomcat (for information about obtaining a
965
   Metacat WAR file, see Download Metacat): 
966
  
967
  ::
968

  
969
    copy <metacat_package_dir>\knb.war C:\Program Files\tomcat\webapps
970

  
971
3.  Restart Tomcat: 
972

  
973
  ::
974

  
975
    C:\Program Files\tomcat\shutdown.bat
976
    C:\Program Files\tomcat\startup.bat
977

  
978

  
979
Congratulations! You are now ready to configure Metacat. Please see the
980
Configuration Section for more information. 
981

  
982
Upgrade
983
.......
984
To upgrade an existing Metacat installation:
985

  
986
1. Download and extract the new version of Metacat. For more information about
987
   downloading and extracting Metacat, please see Download Metacat.
988

  
989
2. Back up the existing Metacat installation. Although not required, we highly
990
   recommend that you back up your existing Metacat to a backup directory 
991
   (<backup_dir>) before installing a new version. You can do so by copying:
992

  
993
  ::
994

  
995
    <web_app_dir>/knb to <backup_dir>/knb.<yyyymmdd>
996
    <web_app_dir>/knb.war to <backup_dir>/knb.war.<yyyymmdd>
997

  
998
  Warning: Do not backup the knb directory in the <web_app_dir> directory.
999
  Tomcat will try to run the backup copy as a service.
1000

  
1001
3.  Copy the new Metacat WAR file in to Tomcat applications directory: 
1002

  
1003
  ::
1004

  
1005
    copy knb.war C:\Program Files\tomcat\webapps
1006

  
1007
4.  Restart Tomcat: 
1008
  
1009
  ::
1010
  
1011
    C:\Program Files\tomcat\shutdown.bat
1012
    C:\Program Files\tomcat\startup.bat
1013

  
1014
Congratulations! You are now ready to configure Metacat. Please see Configuring
1015
Metacat for more information.
1016

  

Also available in: Unified diff