Project

General

Profile

1
Downloading and Installing Metacat
2
==================================
3

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

    
6
.. contents::
7

    
8
System Requirements
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:
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 6: http://www.oracle.com/technetwork/java/javaee/overview/index.html
34

    
35
System requirements for running Metacat:
36

    
37
* a server running an SQL92-compliant database (PostgreSQL_ recommended) 
38
* at least 512MB RAM
39
* 200 MB disk space (Note: The amount of disk space required depends on the size of your RDBMS tablespace and the the size and number of documents stored. Metacat itself requires only about 140 MB of free space after installation).
40

    
41

    
42
Installing on Linux
43
-------------------
44
This section contains instructions for downloading and installing Metacat on 
45
Linux systems. As Mac OS X is based on BSD Unix, these Linux instructions can
46
be adapted to also work on Mac OS X (although the exact commands for
47
downloading and installing packages will differ due to the different package
48
management approaches on the Mac).
49

    
50
Quick Start Overview
51
~~~~~~~~~~~~~~~~~~~~
52
For the impatient or those who have already installed Metacat and know what
53
they are doing, here are the steps needed to install Metacat. Detailed
54
instructions for each step are in the next section.
55

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

    
65
.. _Metacat Download Page: http://knb.ecoinformatics.org/software/metacat/
66

    
67
Downloading Metacat
68
~~~~~~~~~~~~~~~~~~~
69
Before installing Metacat, please ensure that all required software is
70
installed and running correctly. To obtain a Metacat WAR file, which is needed
71
for installation, download one of the following: 
72

    
73
* the Metacat installer, which has a pre-built WAR file,
74
* the Metacat source distribution, which must be built in order to create a WAR file, 
75
* the Metacat source code from SVN. You must build the source code in order to create a WAR file. 
76

    
77
Instructions for all three options are discussed below. Note that downloading
78
the installer (described in the next section) is the simplest way to get
79
started. 
80

    
81
Download the Metacat Installer
82
..............................
83
Downloading the Metacat Installer is the simplest way to get started with the
84
application. To download the installer: 
85

    
86
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) 
87
2.  Save the file locally. 
88
3.  Extract the Metacat package files by typing:
89

    
90
::
91

    
92
  tar -xvzf metacat-bin-X.X.X.tar.gz
93

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

    
98
================== ===========================================================
99
File               Description
100
================== ===========================================================
101
knb.war            The Metacat Web archive file (WAR) 
102
knb                The Web definition file used by Apache on Ubuntu/Debian 
103
                   Linux systems. 
104
knb.ssl            The SSL definition file used by Apache on Ubuntu/Debian 
105
                   Linux systems.
106
jk.conf            The JkMount configuration file used by Apache on 
107
                   Ubuntu/Debian Linux systems. 
108
workers.properties The workers definition file used by Apache on Ubuntu/Debian 
109
                   Linux systems. 
110
authority          The optional LSID Server application WAR
111
================== ===========================================================
112

    
113

    
114
Download Metacat Source Code
115
............................
116
To get the Metacat source distribution:
117

    
118
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).
119
2. Save the file locally. 
120
3. Extract the Metacat package files by typing (replace X.X.X with the current version number): 
121

    
122
::
123

    
124
  tar -xvzf metacat-src-X.X.X.tar.gz
125

    
126
4. Rename the metacat-X.X.X directory to metacat. 
127

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

    
131

    
132
Check Out Metacat Source Code from SVN (for Developers)
133
.......................................................
134
If you wish to work with the most recent Metacat code, or you'd like to extend
135
the Metacat code yourself, you may wish to check out the Metacat source code
136
from SVN. You will need a Subversion (SVN) client installed and configured on
137
your system (see the end of this section for information about obtaining an SVN
138
client). 
139

    
140
.. sidebar:: Installing an SVN Client:
141

    
142
    If you have not already installed Subversion and you are running Ubuntu/Debian,
143
    you can get the SVN client by typing:
144
    
145
    ::
146

    
147
        sudo apt-get install subversion
148

    
149
    Otherwise, you can get the SVN client from The Subversion homepage
150
    (http://subversion.tigris.org/).
151

    
152
To check out the code from SVN, go to the directory where you would like the
153
code to live and type::
154

    
155
  svn co https://code.ecoinformatics.org/code/metacat/tags/METACAT_<rev> metacat
156

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

    
159
To check out the head, type::
160

    
161
  svn co https://code.ecoinformatics.org/code/metacat/trunk metacat
162

    
163
You should see a list of files as they check out.
164

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

    
168

    
169
Installing and Configuring Required Software
170
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
171
Before you can install and run Metacat, you must ensure that a recent Java SDK,
172
PostgreSQL (or another SQL92-compliant RDBMS like Oracle 8i), Ant (if
173
installing from source), and Tomcat are installed and running correctly. We
174
also highly recommend that you install Apache Web server, as it provides a more
175
robust Web-serving environment and is required by some Metacat functionality. 
176

    
177
* `Java 6`_
178
* `Apache Tomcat`_ 
179
* `Apache HTTPD Server`_ (Highly Recommended)
180
* PostgreSQL_ Database (or Oracle_)
181
* `Apache Ant`_ (if building from Source)
182

    
183
Java 6
184
......
185
To run Metacat, you should use Java 6 (Java 5 is deprecated and will not be
186
supported after Metacat version 1.9.2). Make sure that the JAVA_HOME
187
environment variable is properly set and that both ``java`` and ``javac`` 
188
are on your PATH. 
189

    
190
To install Java if you are running Ubuntu_/Debian, type::
191

    
192
  sudo apt-get install sun-java6-jdk
193

    
194
Click "ok" then "yes" for license agreement.
195

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

    
198
.. _Ubuntu: http://www.ubuntu.com/
199

    
200
Apache Tomcat
201
.............
202
We recommend that you install Tomcat 6 into the directory of your choice.
203
Included with the Metacat download is a Tomcat-friendly start-up script that
204
should be installed as well.
205

    
206
Note: we will refer to the Tomcat installation directory as ``<tomcat_home>`` for
207
the remainder of the documentation. 
208

    
209
If you are running Ubuntu_/Debian, get Tomcat by typing::
210

    
211
  sudo apt-get install tomcat6
212

    
213
Otherwise, get Tomcat from the `Apache Tomcat`_ page.
214

    
215
Apache HTTPD Server (Highly Recommended)
216
........................................
217
Although you have the option of running Metacat with only the Tomcat server, we
218
highly recommend that you run it behind the Apache Web server for several
219
reasons; running Tomcat with the Apache server provides a more robust Web
220
serving environment, and the Apache Web server is required if you wish to
221
install and run the Metacat Registry. 
222

    
223
.. sidebar:: Configuring Apache on an OS other than Ubuntu/Debian 
224

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

    
230
  ::
231

    
232
    <apache_install_dir>/conf/httpd.conf
233

    
234
  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:
235

    
236
    ::
237

    
238
      <IfModule mod_jk.c> 
239
        JkLogFile "/var/log/tomcat/mod_jk.log" 
240
        JkLogLevel info 
241
      </IfModule> 
242

    
243
  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:
244

    
245
    ::
246

    
247
      <VirtualHost XXX.XXX.XXX.XXX:80> 
248
        DocumentRoot /var/www 
249
        ServerName dev.nceas.ucsb.edu 
250
        ErrorLog /var/log/httpd/error_log 
251
        CustomLog /var/log/httpd/access_log common 
252
        ScriptAlias /cgi-bin/ "/var/www/cgi-knb/" 
253
        <Directory /var/www/cgi-knb/> 
254
          AllowOverride None 
255
          Options ExecCGI 
256
          Order allow,deny 
257
          Allow from all 
258
        </Directory> 
259
        ScriptAlias /knb/cgi-bin/ "/var/www/webapps/knb/cgi-bin/" 
260
        <Directory "/var/www/webapps/knb/cgi-bin/"> 
261
          AllowOverride None 
262
          Options ExecCGI 
263
          Order allow,deny 
264
          Allow from all 
265
        </Directory> 
266
        JkMount /knb ajp13 
267
        JkMount /knb/* ajp13 
268
        JkMount /knb/metacat ajp13 
269
        JkUnMount /knb/cgi-bin/* ajp13 
270
        JkMount /*.jsp ajp13 
271
        JkMount /metacat ajp13 
272
        JkMount /metacat/* ajp13 
273
      </VirtualHost> 
274

    
275
  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:
276

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

    
280
  4. Edit the workers.properties file and make sure the following properties are set correctly:
281

    
282
    ::
283

    
284
      workers.tomcat_home -  set to the Tomcat install directory. 
285
      workers.java_home - set to the Java install directory. 
286

    
287
  5. Restart Apache to bring in changes by typing:
288

    
289
    ::
290

    
291
      sudo /etc/init.d/apache2 restart
292

    
293
This section contains instructions for installing and configuring the Apache
294
Web server for Metacat on an Ubuntu_/Debian system. Instructions for configuring
295
Apache running on other Linux systems are included in the sidebar.
296

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

    
299
::
300

    
301
  sudo apt-get install apache2 libapache2-mod-jk
302

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

    
309
* the directory in which you extracted the distribution (for binary distribution)
310
* ``<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>``.
311

    
312
2. Set up Mod JK apache configuration by typing:
313

    
314
::
315

    
316
  sudo cp <metacat_helper_dir>/jk.conf <apache_install_dir>/mods-available
317
  sudo cp <metacat_helper_dir>/workers.properties <apache_install_dir>
318

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

    
321
::
322

    
323
  sudo a2dismod jk
324
  sudo a2enmod jk
325

    
326
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:
327

    
328
::
329

    
330
  sudo cp <metacat_helper_dir>/knb <apache_install_dir>/sites-available
331
  sudo a2ensite knb
332

    
333
5. Restart Apache to bring in changes by typing:
334

    
335
::
336

    
337
  sudo /etc/init.d/apache2 restart
338

    
339

    
340
PostgreSQL Database
341
...................
342
Metacat has been most widely tested with PostgreSQL_ and we recommend using it.
343
Instructions for installing and configuring Oracle are also included in the
344
next section.  To install and configure PostgreSQL_:
345

    
346
1. If you are running Ubuntu_/Debian, get PostgreSQL by typing:
347

    
348
  ::
349

    
350
    sudo apt-get install postgresql
351

    
352
  On other systems, install the rpms for postgres.
353

    
354
2. Start the database by running:
355

    
356
  ::
357

    
358
    /etc/init.d/postgresql start
359

    
360
3. Change to postgres user: 
361

    
362
  ::
363

    
364
    sudo su - postgres
365

    
366

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

    
369
  ::
370

    
371
    gedit /etc/postgresql/8.3/main/pg_hba.conf
372

    
373

    
374
  Add the following line to the configuration file: 
375

    
376
  ::
377

    
378
    host metacat metacat 127.0.0.1 255.255.255.255 password
379

    
380

    
381
  Save the file and then create the Metacat instance: 
382

    
383
  ::
384

    
385
    createdb metacat
386

    
387

    
388
5. Log in to postgreSQL by typing: 
389

    
390
  ::
391

    
392
    psql metacat
393

    
394

    
395
6. At the psql prompt, create the Metacat user by typing:
396

    
397
  ::
398

    
399
    CREATE USER metacat WITH UNENCRYPTED PASSWORD 'your_password';
400

    
401
  where 'your_password' is whatever password you would like for the Metacat user. 
402

    
403
7. Exit PostgreSQL by typing 
404

    
405
  ::
406

    
407
    \q
408

    
409
8. Restart the PostgreSQL database to bring in changes: 
410

    
411
  ::
412

    
413
    /etc/init.d/postgresql-8.3 restart
414

    
415
9. Log out of the postgres user account by typing: 
416

    
417
  ::
418

    
419
    logout
420

    
421
10. Test the installation and Metacat account by typing: 
422

    
423
  ::
424

    
425
    psql -U metacat -W -h localhost metacat
426

    
427
11. Log out of postgreSQL: 
428

    
429
  ::
430

    
431
    \q
432

    
433

    
434
The Metacat servlet automatically creates the required database schema. For
435
more information about configuring the database, please see Database
436
Configuration.
437

    
438
Installing and Configuring Oracle 8i
439
....................................
440
To use Oracle 8i with Metacat, the Oracle RDBMS must be installed and running
441
as a daemon on the system. In addition the JDBC listener must be enabled.
442
Enable it by logging in as an Oracle user and typing::
443

    
444
  lsnrctl start
445

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

    
453
The Metacat servlet automatically creates the required database schema. For
454
more information, please see Database Configuration.
455

    
456
Apache Ant (if building from Source)
457
....................................
458
If you are building Metacat from a source distribution or from source code
459
checked out from SVN, Ant is required. (Users installing Metacat from the
460
binary distribution do not require it.) Ant is a Java-based build application
461
similar to Make on UNIX systems. It takes build instructions from a file named
462
"build.xml", which is found in the root installation directory. Metacat source
463
code comes with a default "build.xml" file that may require some modification
464
upon installation. 
465

    
466
If you are running Ubuntu/Debian, get Ant by typing::
467

    
468
  sudo apt-get install ant
469

    
470
Otherwise, get Ant from the `Apache Ant`_ homepage.
471

    
472
Ant should be installed on your system and the "ant" executable shell script
473
should be available in the user's path. The latest Metacat release was tested
474
with Ant 1.8.2. 
475

    
476
Installing Metacat
477
~~~~~~~~~~~~~~~~~~
478
Instructions for a new install, an upgrade, and a source install are included
479
below.
480

    
481
New Install
482
...........
483
Before installing Metacat, please ensure that all required applications are
484
installed, configured to run with Metacat, and running correctly. If you are
485
upgrading an existing Metacat servlet, please skip to Upgrade. For information
486
about installing from source, skip to Source Install and Upgrade.
487

    
488
To install a new Metacat servlet:
489

    
490
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:
491

    
492
  ::
493

    
494
    sudo mkdir /var/metacat
495

    
496
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):
497

    
498
  ::
499

    
500
    sudo chown -R <tomcat_user> /var/metacat
501

    
502

    
503
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/tomcat6/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:
504

    
505
  ::
506

    
507
    sudo cp <metacat_package_dir>/knb.war <tomcat_app_dir>
508

    
509

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

    
512
  ::
513

    
514
    /etc/init.d/tomcat6 restart
515

    
516
Congratulations! You have now installed Metacat. If everything is installed
517
correctly, you should see the Authentication Configuration screen (Figure 2.1)
518
when you type http://yourserver.com/yourcontext/ (e.g.,
519
http://knb.ecoinformatics.org/knb) into a browser. For more information about
520
configuring Metacat, please see the Configuration Section.
521

    
522
.. figure:: images/screenshots/image009.png
523
   :align: center
524

    
525
   The Authentication Configuration screen appears the first time you open a 
526
   new installation of Metacat. 
527

    
528
Upgrade Metacat
529
...............
530
To upgrade an existing binary Metacat installation follow the steps in this
531
section. The steps for upgrading Metacat from source are the same as the
532
instructions for installing from source:
533

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

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

    
538
  ::
539

    
540
    /etc/init.d/tomcat6 stop
541

    
542
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:
543

    
544
  ::
545

    
546
    cp <web_app_dir>/knb <backup_dir>/knb.<yyyymmdd>
547
    cp <web_app_dir>/knb.war <backup_dir>/knb.war.<yyyymmdd>
548

    
549
  Warning: Do not backup the files to the ``<web_app_dir>`` directory.  Tomcat will
550
  try to run the backup copy as a service.
551

    
552
4. Copy the new Metacat WAR file in to the Tomcat applications directory: 
553

    
554
  ::
555

    
556
    sudo cp <metacat_package_dir>/knb.war <tomcat_app_dir>
557

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

    
562
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. 
563

    
564
  ::
565
   
566
    sudo cp <metacat_package_dir>/authority.war <tomcat_app_dir>
567

    
568
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:  
569

    
570
  ::
571

    
572
    /etc/init.d/tomcat6 restart
573

    
574

    
575
7. Run your new Metacat servlet. Go to a Web browser and visit your installed
576
Metacat application, using a URL of the form: 
577

    
578
  ::
579

    
580
    http://yourserver.yourdomain.com/yourcontext/
581

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

    
589
Source Install and Upgrade
590
..........................
591
Whether you are building Metacat from the source distribution or source code
592
checked out from SVN, you will need Apache Ant to do the build (see Installing
593
and Configuring Required Software for more information about Ant). 
594

    
595
To install Metacat from source:
596

    
597
1. Edit the build.properties file found in the directory in which you
598
   downloaded Metacat. Note: Throughout the instructions, we will refer to this
599
   directory as ``<metacat_src_dir>``. 
600

    
601
  * Set the build.tomcat.dir property to your Tomcat installation directory.
602
    Metacat will use some of the native Tomcat libraries during the build. For
603
    instance: build.tomcat.dir=/usr/local/tomcat
604
  * Set the app.deploy.dir property to your application deployment directory.
605
    For instance: app.deploy.dir=/usr/local/tomcat/webapps
606

    
607
2. In the ``<metacat_src_dir>``, run: 
608

    
609
  ::
610

    
611
    sudo ant clean install
612

    
613
  You will see the individual modules get built. You should see a "BUILD
614
  SUCCESSFUL" message at the end.
615

    
616
  You should see a new file named knb.war in your application deployment
617
  directory.
618

    
619
To run your new Metacat servlet, open a Web browser and type::
620

    
621
  http://yourserver.yourdomain.com/yourcontext/ 
622
  (e.g.  http://knb.ecoinformatics.org/knb/)
623

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

    
628
Optional Installation Options (LSID Server)
629
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
630

    
631
.. Note::
632

    
633
  The support for LSID identifiers is deprecated, and is being replaced with
634
  support for DOI_ identifiers in a future release. We are maintaining support
635
  for LSIDs on one particular site, but this support will be removed in a
636
  future version of Metacat.
637

    
638
.. _DOI: http://www.doi.org/
639

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

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

    
666
The format of an LSID is:: 
667

    
668
  urn:lsid:<Authority>:<Namespace>:<ObjectID>[:<Version>]
669
  e.g., urn:lsid:ecoinformatics.org:tao:12039:1
670

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

    
677
  http://example.com:9999/authority/data?lsid=urn:lsid:ecoinformatics.org:tao:12039:1
678
  (To return the data)
679

    
680
  http://example.com:9999/authority/metadata?lsid=urn:lsid:ecoinformatics.org:tao:12039:1
681
  (To return the metadata)
682

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

    
689
Install and configure the LSID Server shipped with Metacat
690
..........................................................
691

    
692
To install the LSID server using the binary installation:
693

    
694
1. Copy the authority.war file to Tomcat:
695

    
696
  ::
697

    
698
    sudo cp <metacat_package_directory>/authority.war /usr/share/tomcat6/webapps
699
 
700
2. Set up the LSID server by dropping the authority file into Apache's
701
   sites-available directory and running a2ensite to enable the site:
702

    
703
   ::
704

    
705
     sudo cp <metacat_helper_dir>/authority /etc/apache2/sites-available
706
     sudo a2ensite authority
707

    
708
3. Restart Tomcat. Log in as the user that runs your Tomcat server (often
709
   "tomcat") and type:
710

    
711
   ::
712

    
713
     /etc/init.d/tomcat5.5 restart
714

    
715
4. Restart Apache to bring in changes by typing:
716

    
717
  ::
718

    
719
    sudo /etc/init.d/apache2 restart
720

    
721
5. See notes beneath LSID server source installation for instructions for
722
   modifying the SRV record(s)
723

    
724
To install the LSID server from a source
725
........................................
726

    
727
1. In the build.properties file found in the directory into which you
728
   extracted the Metacat source code, set the authority and config.lsidauthority
729
   properties. For example:
730
  
731
  ::
732
   
733
   authority.context=authority
734
   config.lsidauthority=ecoinformatics.org
735

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

    
738
  ::
739

    
740
    sudo ant war-lsid
741

    
742
3. Copy the LSID WAR file into the Tomcat application directory.
743

    
744
  ::
745

    
746
    sudo cp <metacat_package_dir>/dist/authority.war <tomcat_app_dir>
747

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

    
751
  ::
752

    
753
    /etc/init.d/tomcat6 restart
754

    
755
5. If you are running Tomcat behind the Apache server (the recommended
756
   configuration), set up and enable the authority service site configurations by
757
   typing:
758

    
759
  ::
760

    
761
    sudo cp <metacat_helper_dir>/authority <apache_install_dir>/sites-available
762
    sudo a2ensite authority
763

    
764
  Where <metacat_helper_dir> can be found in <metacat_code_dir>/src/scripts
765

    
766
6.  Restart Apache to bring in changes by typing: 
767

    
768
  ::
769

    
770
    sudo /etc/init.d/apache2 restart
771

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

    
776
    ::
777

    
778
      _lsid._tcp      IN      SRV     1       0       8080    <metacat.edu>.
779

    
780
  Where <metacat.edu> is the name of the machine that will serve as the
781
  physical location of the AuthorityService.
782

    
783
  For example, the value of <metacat.edu> for the below example URL would be
784
  example.com:
785
  
786
    ::
787
    
788
      http://example.com:9999/authority/data?lsid=urn:lsid:ecoinformatics.org:tao:12039:1
789

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

    
792
Troubleshooting
793
~~~~~~~~~~~~~~~
794
We keep and update a list of common problems and their solutions on the KNB
795
website. See http://knb.ecoinformatics.org/software/metacat/troubleshooting.html 
796
for more information.
797

    
798
Installing on Windows
799
---------------------
800
Metacat can be installed on Windows. Please follow the instructions in this
801
section for downloading Metacat, installing the required software, and
802
installing Metacat. Note that Registry and Data Upload functionality has not
803
been tested on Windows.
804

    
805
Download Metacat
806
~~~~~~~~~~~~~~~~
807
To obtain a Metacat WAR file, which is used when installing the Metacat
808
servlet:
809

    
810
1. Browse to the KNB Software Download Page. In the Metacat section, select
811
   the link that looks like: metacat-bin-X.X.X.zip, where X.X.X is the latest
812
   version of Metacat (e.g., 2.0.0).
813

    
814
2. Choose to download and Save the file locally. 
815

    
816
3. Extract the Metacat package files using your Windows zip utility. You
817
   should see a WAR file and several supporting files (we will only use the WAR
818
   file when installing Metacat). 
819

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

    
823
Note: Before installing Metacat, please ensure that all required software is
824
installed and running correctly.
825

    
826

    
827
Install Required Software
828
~~~~~~~~~~~~~~~~~~~~~~~~~
829
Before you can install and run Metacat, you must ensure that a recent Java SDK,
830
PostgreSQL and Tomcat are installed, configured, and running correctly. 
831

    
832
* `Java 6`_
833
* `Apache Tomcat`_
834
* PostgreSQL_ Database
835

    
836
Java 6
837
......
838
To run Metacat, you must have Java 6. (Java 5 is deprecated). Make sure that
839
the JAVA_HOME environment variable is properly set and that both java and javac
840
are on your PATH.
841

    
842
To download and install Java:
843

    
844
1. Browse to: http://java.sun.com/javase/downloads/widget/jdk6.jsp and follow
845
   the instructions to download JDK 6.
846

    
847
2. Run the downloaded installer to install Java.
848

    
849
3. Set the JAVA_HOME environment variable: In "My Computer" properties, go to
850
   "advanced settings > environment variables". Add:
851

    
852
  ::
853

    
854
    System Variable: JAVA_HOME C:\Program Files\Java\jdk1.6.0_18 
855
    (or whichever version you downloaded)
856

    
857
Apache Tomcat
858
.............
859
We recommend that you install Tomcat version 6.  To download and install Tomcat:
860

    
861
1. Browse to: http://tomcat.apache.org/
862
2. Download the Tomcat core zip file 
863
3. Extract Tomcat files to C:\Program Files\tomcat using the windows zip
864
   utility. 
865

    
866
PostgreSQL Database
867
...................
868
Metacat can be run with several SQL92-compliant database systems, but it has 
869
been most widely tested with PostgreSQL_. Instructions for installing and 
870
configuring PostgreSQL for use with Metacat are included in this section.
871

    
872
To download and install PostgreSQL:
873

    
874
1. Browse to http://www.postgresql.org/download/windows and download the
875
   one-click installer 
876
2. Run the installer 
877
3. Edit C:\Program Files\PostgreSQL\8.3\data and add:
878
  
879
  ::
880

    
881
    host metacat metacat 127.0.0.1 255.255.255.255 password
882

    
883
4. Create a super user. At the command line, enter:
884

    
885
  ::
886

    
887
    C:\Program Files\PostgreSQL\8.3\bin 
888
    createdb -U postgres metacat (enter super user password)
889

    
890
5. Log in to PostgreSQL: 
891

    
892
  ::
893

    
894
    psql -U postgres metacat (enter super user password)
895

    
896
6. Create a Metacat user:
897

    
898
  ::
899

    
900
    CREATE USER metacat WITH UNENCRYPTED PASSWORD 'your_password'
901

    
902
7. Exit PostgreSQL: 
903

    
904
  ::
905

    
906
    \q
907

    
908
8. Restart PostgreSQL from the start menu by selecting:
909
  
910
  ::
911

    
912
    run start/All Programs/PostgreSQL 8.3/Stop Server
913
    run start/All Programs/PostgreSQL 8.3/Start Server
914

    
915

    
916
9. Test the installation by logging in as the metacat user: 
917

    
918
  ::
919
  
920
    Psql –U metacat –W –h localhost metacat
921

    
922
10. Exit PostgreSQL:
923

    
924
  ::
925

    
926
    \q
927

    
928
The Metacat servlet automatically creates the required database schema. For
929
more information, please see Database Configuration.
930

    
931
Installing Metacat
932
~~~~~~~~~~~~~~~~~~
933
Instructions for a new install and for an upgrade are included below.
934

    
935
New Install
936
...........
937
Before installing Metacat, please ensure that all required applications are
938
installed, configured to run with Metacat, and running correctly. If you are
939
upgrading an existing Metacat servlet, please skip to Upgrade.
940

    
941
To install a new Metacat servlet:
942

    
943
1. Create the Metacat base directory at: 
944

    
945
  ::
946

    
947
    C:/Program Files/metacat
948

    
949
2. Copy the Metacat WAR file to Tomcat (for information about obtaining a
950
   Metacat WAR file, see Download Metacat): 
951
  
952
  ::
953

    
954
    copy <metacat_package_dir>\knb.war C:\Program Files\tomcat\webapps
955

    
956
3.  Restart Tomcat: 
957

    
958
  ::
959

    
960
    C:\Program Files\tomcat\shutdown.bat
961
    C:\Program Files\tomcat\startup.bat
962

    
963

    
964
Congratulations! You are now ready to configure Metacat. Please see the
965
Configuration Section for more information. 
966

    
967
Upgrade
968
.......
969
To upgrade an existing Metacat installation:
970

    
971
1. Download and extract the new version of Metacat. For more information about
972
   downloading and extracting Metacat, please see Download Metacat.
973

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

    
978
  ::
979

    
980
    <web_app_dir>/knb to <backup_dir>/knb.<yyyymmdd>
981
    <web_app_dir>/knb.war to <backup_dir>/knb.war.<yyyymmdd>
982

    
983
  Warning: Do not backup the knb directory in the <web_app_dir> directory.
984
  Tomcat will try to run the backup copy as a service.
985

    
986
3.  Copy the new Metacat WAR file in to Tomcat applications directory: 
987

    
988
  ::
989

    
990
    copy knb.war C:\Program Files\tomcat\webapps
991

    
992
4.  Restart Tomcat: 
993
  
994
  ::
995
  
996
    C:\Program Files\tomcat\shutdown.bat
997
    C:\Program Files\tomcat\startup.bat
998

    
999
Congratulations! You are now ready to configure Metacat. Please see Configuring
1000
Metacat for more information.
1001

    
(12-12/20)