Project

General

Profile

metacat / docs / user / metacat / source / install.rst @ 8223

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., 2.2.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 sample 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                Sample Web definition file used by Apache on Ubuntu/Debian 
103
                   Linux systems. 
104
knb.ssl            Sample SSL definition file used by Apache on Ubuntu/Debian 
105
                   Linux systems.
106
jk.conf            Sample JkMount configuration file used by Apache on 
107
                   Ubuntu/Debian Linux systems. 
108
workers.properties Sample workers definition file used by Apache on Ubuntu/Debian 
109
                   Linux systems. 
110
authority.war      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., 2.2.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

    
135
.. sidebar:: Installing an SVN Client:
136

    
137
    If you have not already installed Subversion and you are running Ubuntu/Debian,
138
    you can get the SVN client by typing:
139
    
140
    ::
141

    
142
        sudo apt-get install subversion
143

    
144
    Otherwise, you can get the SVN client from The Subversion homepage
145
    (http://subversion.tigris.org/).
146
    
147
If you wish to work with the most recent Metacat code, or you'd like to extend
148
the Metacat code yourself, you may wish to check out the Metacat source code
149
from SVN. You will need a Subversion (SVN) client installed and configured on
150
your system (see the end of this section for information about obtaining an SVN
151
client). 
152

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

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

    
158
Where ``<rev>`` is the version of the code you want to check out (like 2_0_0). 
159

    
160
To check out the head, type::
161

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

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

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

    
169

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

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

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

    
191
To install Java if you are running Ubuntu_/Debian, you can download the appropriate self-extracting installer:: 
192

    
193
  wget http://download.oracle.com/otn-pub/java/jdk/6u30-b12/jdk-6u30-linux-x64.bin
194
  
195
and follow these commands to install::
196
  
197
  sudo mkdir -p /opt/java/64
198
  sudo mv jdk-6u30-linux-x64.bin /opt/java/64
199
  cd /opt/java/64
200
  sudo chmod +x jdk-6u30-linux-x64.bin
201
  sudo ./jdk-6u30-linux-x64.bin
202
  sudo update-alternatives --install "/usr/bin/java" "java" "/opt/java/64/jdk1.6.0_30/bin/java" 1
203

    
204
You must accept the license agreement during the install process.
205

    
206
If you are not using Ubuntu_/Debian, you can get Java from the Oracle_ website and install using the RPM or other installer (Windows).
207

    
208
.. _Ubuntu: http://www.ubuntu.com/
209

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

    
216
Note: we will refer to the Tomcat installation directory as ``<tomcat_home>`` for
217
the remainder of the documentation. 
218

    
219
If you are running Ubuntu_/Debian, get Tomcat by typing::
220

    
221
  sudo apt-get install tomcat6
222

    
223
Otherwise, get Tomcat from the `Apache Tomcat`_ page.
224

    
225
After installing Tomcat, you can switch back to the Sun JDK by typing::
226

    
227
  sudo update-alternatives --config java
228
  
229
and selecting the correct Java installation.
230

    
231
If using Tomcat with Apache/mod_jk, enable the AJP connector on port 8009 by uncommenting that section in::
232

    
233
  <tomcat_home>/conf/server.xml
234
  
235
For DataONE deployments edit::  
236

    
237
	/etc/tomcat6/catalina.properties
238
	
239
to include::
240

    
241
	org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true
242
	org.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH=true
243
	
244
Apache HTTPD Server (Highly Recommended)
245
........................................
246
Although you have the option of running Metacat with only the Tomcat server, we
247
highly recommend that you run it behind the Apache Web server for several
248
reasons; running Tomcat with the Apache server provides a more robust Web
249
serving environment. The Apache Web server is required if you wish to
250
install and run the Metacat Registry or to use the Metacat Replication feature. 
251

    
252
.. sidebar:: Configuring Apache on an OS other than Ubuntu/Debian 
253

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

    
259
  ::
260

    
261
    <apache_install_dir>/conf/httpd.conf
262

    
263
  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:
264

    
265
    ::
266

    
267
      <IfModule mod_jk.c> 
268
        JkLogFile "/var/log/tomcat/mod_jk.log" 
269
        JkLogLevel info 
270
      </IfModule> 
271

    
272
  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:
273

    
274
    ::
275

    
276
      <VirtualHost XXX.XXX.XXX.XXX:80> 
277
        DocumentRoot /var/www 
278
        ServerName dev.nceas.ucsb.edu 
279
        ErrorLog /var/log/httpd/error_log 
280
        CustomLog /var/log/httpd/access_log common 
281
        ScriptAlias /cgi-bin/ "/var/www/cgi-knb/" 
282
        <Directory /var/www/cgi-knb/> 
283
          AllowOverride None 
284
          Options ExecCGI 
285
          Order allow,deny 
286
          Allow from all 
287
        </Directory> 
288
        ScriptAlias /knb/cgi-bin/ "/var/www/webapps/knb/cgi-bin/" 
289
        <Directory "/var/www/webapps/knb/cgi-bin/"> 
290
          AllowOverride None 
291
          Options ExecCGI 
292
          Order allow,deny 
293
          Allow from all 
294
        </Directory> 
295
        JkMount /knb ajp13 
296
        JkMount /knb/* ajp13 
297
        JkMount /knb/metacat ajp13 
298
        JkUnMount /knb/cgi-bin/* ajp13 
299
        JkMount /*.jsp ajp13 
300
        JkMount /metacat ajp13 
301
        JkMount /metacat/* ajp13 
302
      </VirtualHost> 
303

    
304
  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:
305

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

    
309
  4. Edit the workers.properties file and make sure the following properties are set correctly:
310

    
311
    ::
312

    
313
      workers.tomcat_home -  set to the Tomcat install directory. 
314
      workers.java_home - set to the Java install directory. 
315

    
316
  5. Restart Apache to bring in changes by typing:
317

    
318
    ::
319

    
320
      sudo /etc/init.d/apache2 restart
321

    
322
This section contains instructions for installing and configuring the Apache
323
Web server for Metacat on an Ubuntu_/Debian system. Instructions for configuring
324
Apache running on other Linux systems are included in the sidebar.
325

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

    
328
::
329

    
330
  sudo apt-get install apache2 libapache2-mod-jk
331

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

    
338
* the directory in which you extracted the distribution (for binary distribution)
339
* ``<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>``.
340

    
341
2. Set up Mod JK apache configuration by typing:
342

    
343
::
344

    
345
  sudo cp <metacat_helper_dir>/debian/jk.conf <apache_install_dir>/mods-available
346
  sudo cp <metacat_helper_dir>/debian/workers.properties <apache_install_dir>
347

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

    
350
::
351

    
352
  sudo a2dismod jk
353
  sudo a2enmod jk
354

    
355
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:
356

    
357
::
358

    
359
  sudo cp <metacat_helper_dir>/knb <apache_install_dir>/sites-available
360
  sudo a2ensite knb
361
  
362
5. Disable the default Apache site configuration:
363

    
364
::
365

    
366
  sudo a2dissite 000-default  
367

    
368
6. Restart Apache to bring in changes by typing:
369

    
370
::
371

    
372
  sudo /etc/init.d/apache2 restart
373

    
374

    
375
PostgreSQL Database
376
...................
377
Metacat has been most widely tested with PostgreSQL_ and we recommend using it.
378
Instructions for installing and configuring Oracle are also included in the
379
next section.  To install and configure PostgreSQL_:
380

    
381
1. If you are running Ubuntu_/Debian, get PostgreSQL by typing:
382

    
383
  ::
384

    
385
    sudo apt-get install postgresql
386

    
387
  On other systems, install the rpms for postgres.
388

    
389
2. Start the database by running:
390

    
391
  ::
392

    
393
    sudo /etc/init.d/postgresql-8.4 start
394

    
395
3. Change to postgres user: 
396

    
397
  ::
398

    
399
    sudo su - postgres
400

    
401

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

    
404
  ::
405

    
406
    gedit /etc/postgresql/8.4/main/pg_hba.conf
407

    
408

    
409
  Add the following line to the configuration file: 
410

    
411
  ::
412

    
413
    host metacat metacat 127.0.0.1 255.255.255.255 password
414

    
415

    
416
  Save the file and then create the Metacat instance: 
417

    
418
  ::
419

    
420
    createdb metacat
421

    
422

    
423
5. Log in to postgreSQL by typing: 
424

    
425
  ::
426

    
427
    psql metacat
428

    
429

    
430
6. At the psql prompt, create the Metacat user by typing:
431

    
432
  ::
433

    
434
    CREATE USER metacat WITH UNENCRYPTED PASSWORD 'your_password';
435

    
436
  where 'your_password' is whatever password you would like for the Metacat user. 
437

    
438
7. Exit PostgreSQL by typing 
439

    
440
  ::
441

    
442
    \q
443

    
444
8. Restart the PostgreSQL database to bring in changes: 
445

    
446
  ::
447

    
448
    /etc/init.d/postgresql-8.4 restart
449

    
450
9. Log out of the postgres user account by typing: 
451

    
452
  ::
453

    
454
    logout
455

    
456
10. Test the installation and Metacat account by typing: 
457

    
458
  ::
459

    
460
    psql -U metacat -W -h localhost metacat
461

    
462
11. Log out of postgreSQL: 
463

    
464
  ::
465

    
466
    \q
467

    
468

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

    
473
Installing and Configuring Oracle
474
.................................
475
To use Oracle with Metacat, the Oracle RDBMS must be installed and running
476
as a daemon on the system. In addition the JDBC listener must be enabled.
477
Enable it by logging in as an Oracle user and typing::
478

    
479
  lsnrctl start
480

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

    
488
The Metacat servlet automatically creates the required database schema. For
489
more information, please see Database Configuration.
490

    
491
Apache Ant (if building from Source)
492
....................................
493
If you are building Metacat from a source distribution or from source code
494
checked out from SVN, Ant is required. (Users installing Metacat from the
495
binary distribution do not require it.) Ant is a Java-based build application
496
similar to Make on UNIX systems. It takes build instructions from a file named
497
"build.xml", which is found in the root installation directory. Metacat source
498
code comes with a default "build.xml" file that may require some modification
499
upon installation. 
500

    
501
If you are running Ubuntu/Debian, get Ant by typing::
502

    
503
  sudo apt-get install ant
504

    
505
Otherwise, get Ant from the `Apache Ant`_ homepage.
506

    
507
Ant should be installed on your system and the "ant" executable shell script
508
should be available in the user's path. The latest Metacat release was tested
509
with Ant 1.8.2. 
510

    
511
Installing Metacat
512
~~~~~~~~~~~~~~~~~~
513
Instructions for a new install, an upgrade, and a source install are included
514
below.
515

    
516
New Install
517
...........
518
Before installing Metacat, please ensure that all required applications are
519
installed, configured to run with Metacat, and running correctly. If you are
520
upgrading an existing Metacat servlet, please skip to Upgrade. For information
521
about installing from source, skip to Source Install and Upgrade.
522

    
523
To install a new Metacat servlet:
524

    
525
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:
526

    
527
  ::
528

    
529
    sudo mkdir /var/metacat
530

    
531
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):
532

    
533
  ::
534

    
535
    sudo chown -R <tomcat_user> /var/metacat
536

    
537

    
538
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:
539

    
540
  ::
541

    
542
    sudo cp <metacat_package_dir>/knb.war <tomcat_app_dir>
543

    
544

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

    
547
  ::
548

    
549
    sudo /etc/init.d/tomcat6 restart
550

    
551
Congratulations! You have now installed Metacat. If everything is installed
552
correctly, you should see the Authentication Configuration screen (Figure 2.1)
553
when you type http://yourserver.com/yourcontext/ (e.g.,
554
http://knb.ecoinformatics.org/knb) into a browser. For more information about
555
configuring Metacat, please see the Configuration Section.
556

    
557
.. figure:: images/screenshots/image009.png
558
   :align: center
559

    
560
   The Authentication Configuration screen appears the first time you open a 
561
   new installation of Metacat. 
562

    
563
Upgrade Metacat
564
...............
565
To upgrade an existing binary Metacat installation follow the steps in this
566
section. The steps for upgrading Metacat from source are the same as the
567
instructions for installing from source:
568

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

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

    
573
  ::
574

    
575
    /etc/init.d/tomcat6 stop
576

    
577
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:
578

    
579
  ::
580

    
581
    cp <web_app_dir>/knb <backup_dir>/knb.<yyyymmdd>
582
    cp <web_app_dir>/knb.war <backup_dir>/knb.war.<yyyymmdd>
583

    
584
  Warning: Do not backup the files to the ``<web_app_dir>`` directory.  Tomcat will
585
  try to run the backup copy as a service.
586

    
587
4. Copy the new Metacat WAR file in to the Tomcat applications directory: 
588

    
589
  ::
590

    
591
    sudo cp <metacat_package_dir>/knb.war <tomcat_app_dir>
592

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

    
597
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. 
598

    
599
  ::
600
   
601
    sudo cp <metacat_package_dir>/authority.war <tomcat_app_dir>
602

    
603
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:  
604

    
605
  ::
606

    
607
    /etc/init.d/tomcat6 restart
608

    
609

    
610
7. Run your new Metacat servlet. Go to a Web browser and visit your installed
611
Metacat application, using a URL of the form: 
612

    
613
  ::
614

    
615
    http://yourserver.yourdomain.com/yourcontext/
616

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

    
624
Source Install and Upgrade
625
..........................
626
Whether you are building Metacat from the source distribution or source code
627
checked out from SVN, you will need Apache Ant to do the build (see Installing
628
and Configuring Required Software for more information about Ant). 
629

    
630
To install Metacat from source:
631

    
632
1. Edit the build.properties file found in the directory in which you
633
   downloaded Metacat. Note: Throughout the instructions, we will refer to this
634
   directory as ``<metacat_src_dir>``. 
635

    
636
  * Set the build.tomcat.dir property to your Tomcat installation directory.
637
    Metacat will use some of the native Tomcat libraries during the build. For
638
    instance: build.tomcat.dir=/usr/local/tomcat
639
  * Set the app.deploy.dir property to your application deployment directory.
640
    For instance: app.deploy.dir=/usr/local/tomcat/webapps
641

    
642
2. In the ``<metacat_src_dir>``, run: 
643

    
644
  ::
645

    
646
    sudo ant clean install
647

    
648
  You will see the individual modules get built. You should see a "BUILD
649
  SUCCESSFUL" message at the end.
650

    
651
  You should see a new file named knb.war in your application deployment
652
  directory.
653

    
654
To run your new Metacat servlet, open a Web browser and type::
655

    
656
  http://yourserver.yourdomain.com/yourcontext/ 
657
  (e.g.  http://knb.ecoinformatics.org/knb/)
658

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

    
663
Optional Installation Options (LSID Server)
664
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
665

    
666
.. Note::
667

    
668
  The support for LSID identifiers is deprecated, and is being replaced with
669
  support for DOI_ identifiers in a future release. We are maintaining support
670
  for LSIDs on one particular site, but this support will be removed in a
671
  future version of Metacat.
672

    
673
.. _DOI: http://www.doi.org/
674

    
675
Metacat's optional LSID server allows Metacat to use a standardized syntax for
676
identifying data sets, in addition to Metacat's internal, custom scheme for
677
identifiers. LSID's were designed to identify complex biological entities with
678
short identifiers (much like DOIs in publishing) that are both computer and
679
human readable. LSID identifiers are URIs and are therefore usable in many
680
Internet applications, but they also cleanly separate the identity of a data
681
set (i.e., its permenant identifier) from its current location (e.g., the list
682
of URLs from which it might be retrieved).  LSIDs accomplish this by using a
683
level of indirection; the identifier represents simply a name without location,
684
but an associated resolver service can be used to locate the current location
685
of the data and medata for the data set.  This is accomplished by establishing
686
a well-known location for the resolution service for each authority using an
687
infrequently used feature of the domain name system called SRV records.  At its
688
most basic, resolution of an identifier is performed when a client looks up the
689
SRV record for an LSID by querying DNS, which returns the current host and port
690
of the authority web service, which is in turn used to locate the data and
691
metadata.
692

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

    
701
The format of an LSID is:: 
702

    
703
  urn:lsid:<Authority>:<Namespace>:<ObjectID>[:<Version>]
704
  e.g., urn:lsid:ecoinformatics.org:tao:12039:1
705

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

    
712
  http://example.com:9999/authority/data?lsid=urn:lsid:ecoinformatics.org:tao:12039:1
713
  (To return the data)
714

    
715
  http://example.com:9999/authority/metadata?lsid=urn:lsid:ecoinformatics.org:tao:12039:1
716
  (To return the metadata)
717

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

    
724
Install and configure the LSID Server shipped with Metacat
725
..........................................................
726

    
727
To install the LSID server using the binary installation:
728

    
729
1. Copy the authority.war file to Tomcat:
730

    
731
  ::
732

    
733
    sudo cp <metacat_package_directory>/authority.war /usr/share/tomcat6/webapps
734
 
735
2. Set up the LSID server by dropping the authority file into Apache's
736
   sites-available directory and running a2ensite to enable the site:
737

    
738
   ::
739

    
740
     sudo cp <metacat_helper_dir>/authority /etc/apache2/sites-available
741
     sudo a2ensite authority
742

    
743
3. Restart Tomcat. Log in as the user that runs your Tomcat server (often
744
   "tomcat") and type:
745

    
746
   ::
747

    
748
     /etc/init.d/tomcat5.5 restart
749

    
750
4. Restart Apache to bring in changes by typing:
751

    
752
  ::
753

    
754
    sudo /etc/init.d/apache2 restart
755

    
756
5. See notes beneath LSID server source installation for instructions for
757
   modifying the SRV record(s)
758

    
759
To install the LSID server from a source
760
........................................
761

    
762
1. In the build.properties file found in the directory into which you
763
   extracted the Metacat source code, set the authority and config.lsidauthority
764
   properties. For example:
765
  
766
  ::
767
   
768
   authority.context=authority
769
   config.lsidauthority=ecoinformatics.org
770

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

    
773
  ::
774

    
775
    sudo ant war-lsid
776

    
777
3. Copy the LSID WAR file into the Tomcat application directory.
778

    
779
  ::
780

    
781
    sudo cp <metacat_package_dir>/dist/authority.war <tomcat_app_dir>
782

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

    
786
  ::
787

    
788
    /etc/init.d/tomcat6 restart
789

    
790
5. If you are running Tomcat behind the Apache server (the recommended
791
   configuration), set up and enable the authority service site configurations by
792
   typing:
793

    
794
  ::
795

    
796
    sudo cp <metacat_helper_dir>/authority <apache_install_dir>/sites-available
797
    sudo a2ensite authority
798

    
799
  Where <metacat_helper_dir> can be found in <metacat_code_dir>/src/scripts
800

    
801
6.  Restart Apache to bring in changes by typing: 
802

    
803
  ::
804

    
805
    sudo /etc/init.d/apache2 restart
806

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

    
811
    ::
812

    
813
      _lsid._tcp      IN      SRV     1       0       8080    <metacat.edu>.
814

    
815
  Where <metacat.edu> is the name of the machine that will serve as the
816
  physical location of the AuthorityService.
817

    
818
  For example, the value of <metacat.edu> for the below example URL would be
819
  example.com:
820
  
821
    ::
822
    
823
      http://example.com:9999/authority/data?lsid=urn:lsid:ecoinformatics.org:tao:12039:1
824

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

    
827
Troubleshooting
828
~~~~~~~~~~~~~~~
829
We keep and update a list of common problems and their solutions on the KNB
830
website. See http://knb.ecoinformatics.org/software/metacat/troubleshooting.html 
831
for more information.
832

    
833
Installing on Windows
834
---------------------
835
Metacat can be installed on Windows. Please follow the instructions in this
836
section for downloading Metacat, installing the required software, and
837
installing Metacat. Note that Registry and Data Upload functionality has not
838
been tested on Windows.
839

    
840
Download Metacat
841
~~~~~~~~~~~~~~~~
842
To obtain a Metacat WAR file, which is used when installing the Metacat
843
servlet:
844

    
845
1. Browse to the KNB Software Download Page. In the Metacat section, select
846
   the link that looks like: metacat-bin-X.X.X.zip, where X.X.X is the latest
847
   version of Metacat (e.g., 2.0.4).
848

    
849
2. Choose to download and Save the file locally. 
850

    
851
3. Extract the Metacat package files using your Windows zip utility. You
852
   should see a WAR file and several supporting files (we will only use the WAR
853
   file when installing Metacat). 
854

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

    
858
Note: Before installing Metacat, please ensure that all required software is
859
installed and running correctly.
860

    
861

    
862
Install Required Software
863
~~~~~~~~~~~~~~~~~~~~~~~~~
864
Before you can install and run Metacat, you must ensure that a recent Java SDK,
865
PostgreSQL and Tomcat are installed, configured, and running correctly. 
866

    
867
* `Java 6`_
868
* `Apache Tomcat`_
869
* PostgreSQL_ Database
870

    
871
Java 6
872
......
873
To run Metacat, you must have Java 6. (Java 5 is deprecated). Make sure that
874
the JAVA_HOME environment variable is properly set and that both java and javac
875
are on your PATH.
876

    
877
To download and install Java:
878

    
879
1. Browse to: http://java.sun.com/javase/downloads/widget/jdk6.jsp and follow
880
   the instructions to download JDK 6.
881

    
882
2. Run the downloaded installer to install Java.
883

    
884
3. Set the JAVA_HOME environment variable: In "My Computer" properties, go to
885
   "advanced settings > environment variables". Add:
886

    
887
  ::
888

    
889
    System Variable: JAVA_HOME C:\Program Files\Java\jdk1.6.0_18 
890
    (or whichever version you downloaded)
891

    
892
Apache Tomcat
893
.............
894
We recommend that you install Tomcat version 6.  To download and install Tomcat:
895

    
896
1. Browse to: http://tomcat.apache.org/
897
2. Download the Tomcat core zip file 
898
3. Extract Tomcat files to C:\Program Files\tomcat using the windows zip
899
   utility. 
900

    
901
PostgreSQL Database
902
...................
903
Metacat can be run with several SQL92-compliant database systems, but it has 
904
been most widely tested with PostgreSQL_. Instructions for installing and 
905
configuring PostgreSQL for use with Metacat are included in this section.
906

    
907
To download and install PostgreSQL:
908

    
909
1. Browse to http://www.postgresql.org/download/windows and download the
910
   one-click installer 
911
2. Run the installer 
912
3. Edit C:\Program Files\PostgreSQL\8.3\data and add:
913
  
914
  ::
915

    
916
    host metacat metacat 127.0.0.1 255.255.255.255 password
917

    
918
4. Create a super user. At the command line, enter:
919

    
920
  ::
921

    
922
    C:\Program Files\PostgreSQL\8.3\bin 
923
    createdb -U postgres metacat (enter super user password)
924

    
925
5. Log in to PostgreSQL: 
926

    
927
  ::
928

    
929
    psql -U postgres metacat (enter super user password)
930

    
931
6. Create a Metacat user:
932

    
933
  ::
934

    
935
    CREATE USER metacat WITH UNENCRYPTED PASSWORD 'your_password'
936

    
937
7. Exit PostgreSQL: 
938

    
939
  ::
940

    
941
    \q
942

    
943
8. Restart PostgreSQL from the start menu by selecting:
944
  
945
  ::
946

    
947
    run start/All Programs/PostgreSQL 8.3/Stop Server
948
    run start/All Programs/PostgreSQL 8.3/Start Server
949

    
950

    
951
9. Test the installation by logging in as the metacat user: 
952

    
953
  ::
954
  
955
    Psql ���������U metacat ���������W ���������h localhost metacat
956

    
957
10. Exit PostgreSQL:
958

    
959
  ::
960

    
961
    \q
962

    
963
The Metacat servlet automatically creates the required database schema. For
964
more information, please see Database Configuration.
965

    
966
Installing Metacat
967
~~~~~~~~~~~~~~~~~~
968
Instructions for a new install and for an upgrade are included below.
969

    
970
New Install
971
...........
972
Before installing Metacat, please ensure that all required applications are
973
installed, configured to run with Metacat, and running correctly. If you are
974
upgrading an existing Metacat servlet, please skip to Upgrade.
975

    
976
To install a new Metacat servlet:
977

    
978
1. Create the Metacat base directory at: 
979

    
980
  ::
981

    
982
    C:/Program Files/metacat
983

    
984
2. Copy the Metacat WAR file to Tomcat (for information about obtaining a
985
   Metacat WAR file, see Download Metacat): 
986
  
987
  ::
988

    
989
    copy <metacat_package_dir>\knb.war C:\Program Files\tomcat\webapps
990

    
991
3.  Restart Tomcat: 
992

    
993
  ::
994

    
995
    C:\Program Files\tomcat\shutdown.bat
996
    C:\Program Files\tomcat\startup.bat
997

    
998

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

    
1002
Upgrade
1003
.......
1004
To upgrade an existing Metacat installation:
1005

    
1006
1. Download and extract the new version of Metacat. For more information about
1007
   downloading and extracting Metacat, please see Download Metacat.
1008

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

    
1013
  ::
1014

    
1015
    <web_app_dir>/knb to <backup_dir>/knb.<yyyymmdd>
1016
    <web_app_dir>/knb.war to <backup_dir>/knb.war.<yyyymmdd>
1017

    
1018
  Warning: Do not backup the knb directory in the <web_app_dir> directory.
1019
  Tomcat will try to run the backup copy as a service.
1020

    
1021
3.  Copy the new Metacat WAR file in to Tomcat applications directory: 
1022

    
1023
  ::
1024

    
1025
    copy knb.war C:\Program Files\tomcat\webapps
1026

    
1027
4.  Restart Tomcat: 
1028
  
1029
  ::
1030
  
1031
    C:\Program Files\tomcat\shutdown.bat
1032
    C:\Program Files\tomcat\startup.bat
1033

    
1034
Congratulations! You are now ready to configure Metacat. Please see Configuring
1035
Metacat for more information.
1036