Project

General

Profile

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

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.0.2) 
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.0.2).
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 2_0_0). 
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), 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, you can download the appropriate self-extracting installer:: 
191

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

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

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

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

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

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

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

    
220
  sudo apt-get install tomcat6
221

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

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

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

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

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

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

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

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

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

    
258
  ::
259

    
260
    <apache_install_dir>/conf/httpd.conf
261

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

    
264
    ::
265

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

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

    
273
    ::
274

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

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

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

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

    
310
    ::
311

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

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

    
317
    ::
318

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

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

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

    
327
::
328

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

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

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

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

    
342
::
343

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

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

    
349
::
350

    
351
  sudo a2dismod jk
352
  sudo a2enmod jk
353

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

    
356
::
357

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

    
363
::
364

    
365
  sudo a2dissite 000-default  
366

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

    
369
::
370

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

    
373

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

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

    
382
  ::
383

    
384
    sudo apt-get install postgresql
385

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

    
388
2. Start the database by running:
389

    
390
  ::
391

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

    
394
3. Change to postgres user: 
395

    
396
  ::
397

    
398
    sudo su - postgres
399

    
400

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

    
403
  ::
404

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

    
407

    
408
  Add the following line to the configuration file: 
409

    
410
  ::
411

    
412
    host metacat metacat 127.0.0.1 255.255.255.255 password
413

    
414

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

    
417
  ::
418

    
419
    createdb metacat
420

    
421

    
422
5. Log in to postgreSQL by typing: 
423

    
424
  ::
425

    
426
    psql metacat
427

    
428

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

    
431
  ::
432

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

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

    
437
7. Exit PostgreSQL by typing 
438

    
439
  ::
440

    
441
    \q
442

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

    
445
  ::
446

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

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

    
451
  ::
452

    
453
    logout
454

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

    
457
  ::
458

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

    
461
11. Log out of postgreSQL: 
462

    
463
  ::
464

    
465
    \q
466

    
467

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

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

    
478
  lsnrctl start
479

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

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

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

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

    
502
  sudo apt-get install ant
503

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

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

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

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

    
522
To install a new Metacat servlet:
523

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

    
526
  ::
527

    
528
    sudo mkdir /var/metacat
529

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

    
532
  ::
533

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

    
536

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

    
539
  ::
540

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

    
543

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

    
546
  ::
547

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

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

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

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

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

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

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

    
572
  ::
573

    
574
    /etc/init.d/tomcat6 stop
575

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

    
578
  ::
579

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

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

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

    
588
  ::
589

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

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

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

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

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

    
604
  ::
605

    
606
    /etc/init.d/tomcat6 restart
607

    
608

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

    
612
  ::
613

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

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

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

    
629
To install Metacat from source:
630

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

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

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

    
643
  ::
644

    
645
    sudo ant clean install
646

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

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

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

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

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

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

    
665
.. Note::
666

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

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

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

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

    
700
The format of an LSID is:: 
701

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

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

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

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

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

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

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

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

    
730
  ::
731

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

    
737
   ::
738

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

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

    
745
   ::
746

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

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

    
751
  ::
752

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

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

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

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

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

    
772
  ::
773

    
774
    sudo ant war-lsid
775

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

    
778
  ::
779

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

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

    
785
  ::
786

    
787
    /etc/init.d/tomcat6 restart
788

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

    
793
  ::
794

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

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

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

    
802
  ::
803

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

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

    
810
    ::
811

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

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

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

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

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

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

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

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

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

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

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

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

    
860

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

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

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

    
876
To download and install Java:
877

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

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

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

    
886
  ::
887

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

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

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

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

    
906
To download and install PostgreSQL:
907

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

    
915
    host metacat metacat 127.0.0.1 255.255.255.255 password
916

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

    
919
  ::
920

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

    
924
5. Log in to PostgreSQL: 
925

    
926
  ::
927

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

    
930
6. Create a Metacat user:
931

    
932
  ::
933

    
934
    CREATE USER metacat WITH UNENCRYPTED PASSWORD 'your_password'
935

    
936
7. Exit PostgreSQL: 
937

    
938
  ::
939

    
940
    \q
941

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

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

    
949

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

    
952
  ::
953
  
954
    Psql –U metacat –W –h localhost metacat
955

    
956
10. Exit PostgreSQL:
957

    
958
  ::
959

    
960
    \q
961

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

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

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

    
975
To install a new Metacat servlet:
976

    
977
1. Create the Metacat base directory at: 
978

    
979
  ::
980

    
981
    C:/Program Files/metacat
982

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

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

    
990
3.  Restart Tomcat: 
991

    
992
  ::
993

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

    
997

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

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

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

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

    
1012
  ::
1013

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

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

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

    
1022
  ::
1023

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

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

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