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 7`_ (Note: Java 6 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 7: http://www.oracle.com/technetwork/java/javase/downloads/jre7-downloads-1880261.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>/metacat.war <tomcat_app_dir>``
62
7. ``sudo /etc/init.d/tomcat7 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., |release|) 
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
metacat.war        The Metacat Web archive file (WAR) 
102
metacat-site.conf       Sample Web definition file used by Apache on Ubuntu/Debian 
103
                   Linux systems. 
104
metacat-site-ssl.conf   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
metacat-index.war  The Metacat Index WAR for supporting SOLR query features
111
					Optional unless Metacat UI is being used.
112
metacat-ui.war     The Metacat UI - can be deployed as a webapp or directly in webserver
113
					Metacat UI requires metacat-index be deployed and configured.
114
authority.war      The optional LSID Server application WAR
115
================== ======================================================================
116

    
117

    
118
Download Metacat Source Code
119
............................
120
To get the Metacat source distribution:
121

    
122
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., |release|).
123
2. Save the file locally. 
124
3. Extract the Metacat package files by typing (replace X.X.X with the current version number): 
125

    
126
::
127

    
128
  tar -xvzf metacat-src-X.X.X.tar.gz
129

    
130
4. Rename the metacat-X.X.X directory to metacat. 
131

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

    
135

    
136
Check Out Metacat Source Code from SVN (for Developers)
137
.......................................................
138

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

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

    
146
        sudo apt-get install subversion
147

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

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

    
160
  svn co https://code.ecoinformatics.org/code/metacat/tags/METACAT_<rev> metacat
161

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

    
164
To check out the head, type::
165

    
166
  svn co https://code.ecoinformatics.org/code/metacat/trunk metacat
167

    
168
You should see a list of files as they check out.
169

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

    
173

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

    
182
* `Java 7`_
183
* `Apache Tomcat`_ 
184
* `Apache HTTPD Server`_ (Highly Recommended)
185
* PostgreSQL_ Database (or Oracle_)
186
* `Apache Ant`_ (if building from Source)
187

    
188
Java 7
189
......
190
To run Metacat, you should use Java 7. Make sure that the JAVA_HOME
191
environment variable is properly set and that both ``java`` and ``javac`` 
192
are on your PATH. 
193

    
194
To install Java if you are running Ubuntu_/Debian, you can install using apt-get:: 
195

    
196
  sudo apt-get install openjdk-7-jdk
197

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

    
200
.. _Ubuntu: http://www.ubuntu.com/
201

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

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

    
211
If you are running Ubuntu_/Debian, get Tomcat by typing::
212

    
213
  sudo apt-get install tomcat7
214

    
215
Otherwise, get Tomcat from the `Apache Tomcat`_ page.
216

    
217
After installing Tomcat, you can switch back to the Sun JDK by typing::
218

    
219
  sudo update-alternatives --config java
220
  
221
and selecting the correct Java installation.
222

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

    
225
  <tomcat_home>/conf/server.xml
226
  
227
For DataONE deployments edit::  
228

    
229
	/etc/tomcat7/catalina.properties
230
	
231
to include::
232

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

    
244
.. sidebar:: Configuring Apache on an OS other than Ubuntu/Debian 
245

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

    
251
  ::
252

    
253
    <apache_install_dir>/conf/httpd.conf
254

    
255
  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:
256

    
257
    ::
258

    
259
      <IfModule mod_jk.c> 
260
        JkLogFile "/var/log/tomcat/mod_jk.log" 
261
        JkLogLevel info 
262
      </IfModule> 
263

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

    
266
    ::
267

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

    
294
  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:
295

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

    
299
  4. Edit the workers.properties file and make sure the following properties are set correctly:
300

    
301
    ::
302

    
303
      workers.tomcat_home -  set to the Tomcat install directory. 
304
      workers.java_home - set to the Java install directory. 
305

    
306
  5. Restart Apache to bring in changes by typing:
307

    
308
    ::
309

    
310
      sudo /etc/init.d/apache2 restart
311

    
312
This section contains instructions for installing and configuring the Apache
313
Web server for Metacat on an Ubuntu_/Debian system. Instructions for configuring
314
Apache running on other Linux systems are included in the sidebar.
315

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

    
318
::
319

    
320
  sudo apt-get install apache2 libapache2-mod-jk
321

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

    
328
* the directory in which you extracted the distribution (for binary distribution)
329
* ``<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>``.
330

    
331
2. Set up Mod JK apache configuration by typing:
332

    
333
::
334

    
335
  sudo cp <metacat_helper_dir>/debian/jk.conf <apache_install_dir>/mods-available
336
  sudo cp <metacat_helper_dir>/debian/workers.properties <apache_install_dir>
337

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

    
340
::
341

    
342
  sudo a2dismod jk
343
  sudo a2enmod jk
344

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

    
347
::
348

    
349
  sudo cp <metacat_helper_dir>/metacat-site.conf <apache_install_dir>/sites-available
350
  sudo a2ensite metacat-site.conf
351
  
352
5. Disable the default Apache site configuration:
353

    
354
::
355

    
356
  sudo a2dissite 000-default  
357

    
358
6. Restart Apache to bring in changes by typing:
359

    
360
::
361

    
362
  sudo /etc/init.d/apache2 restart
363

    
364

    
365
PostgreSQL Database
366
...................
367
Metacat has been most widely tested with PostgreSQL_ and we recommend using it.
368
Instructions for installing and configuring Oracle are also included in the
369
next section.  To install and configure PostgreSQL_:
370

    
371
1. If you are running Ubuntu_/Debian, get PostgreSQL by typing:
372

    
373
  ::
374

    
375
    sudo apt-get install postgresql
376

    
377
  On other systems, install the rpms for postgres.
378

    
379
2. Start the database by running:
380

    
381
  ::
382

    
383
    sudo /etc/init.d/postgresql-8.4 start
384

    
385
3. Change to postgres user: 
386

    
387
  ::
388

    
389
    sudo su - postgres
390

    
391

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

    
394
  ::
395

    
396
    gedit /etc/postgresql/8.4/main/pg_hba.conf
397

    
398

    
399
  Add the following line to the configuration file: 
400

    
401
  ::
402

    
403
    host metacat metacat 127.0.0.1 255.255.255.255 password
404

    
405

    
406
  Save the file and then create the Metacat instance: 
407

    
408
  ::
409

    
410
    createdb metacat
411

    
412

    
413
5. Log in to postgreSQL by typing: 
414

    
415
  ::
416

    
417
    psql metacat
418

    
419

    
420
6. At the psql prompt, create the Metacat user by typing:
421

    
422
  ::
423

    
424
    CREATE USER metacat WITH UNENCRYPTED PASSWORD 'your_password';
425

    
426
  where 'your_password' is whatever password you would like for the Metacat user. 
427

    
428
7. Exit PostgreSQL by typing 
429

    
430
  ::
431

    
432
    \q
433

    
434
8. Restart the PostgreSQL database to bring in changes: 
435

    
436
  ::
437

    
438
    /etc/init.d/postgresql-8.4 restart
439

    
440
9. Log out of the postgres user account by typing: 
441

    
442
  ::
443

    
444
    logout
445

    
446
10. Test the installation and Metacat account by typing: 
447

    
448
  ::
449

    
450
    psql -U metacat -W -h localhost metacat
451

    
452
11. Log out of postgreSQL: 
453

    
454
  ::
455

    
456
    \q
457

    
458

    
459
The Metacat servlet automatically creates the required database schema. For
460
more information about configuring the database, please see Database
461
Configuration.
462

    
463
Installing and Configuring Oracle
464
.................................
465
To use Oracle with Metacat, the Oracle RDBMS must be installed and running
466
as a daemon on the system. In addition the JDBC listener must be enabled.
467
Enable it by logging in as an Oracle user and typing::
468

    
469
  lsnrctl start
470

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

    
478
The Metacat servlet automatically creates the required database schema. For
479
more information, please see Database Configuration.
480

    
481
Apache Ant (if building from Source)
482
....................................
483
If you are building Metacat from a source distribution or from source code
484
checked out from SVN, Ant is required. (Users installing Metacat from the
485
binary distribution do not require it.) Ant is a Java-based build application
486
similar to Make on UNIX systems. It takes build instructions from a file named
487
"build.xml", which is found in the root installation directory. Metacat source
488
code comes with a default "build.xml" file that may require some modification
489
upon installation. 
490

    
491
If you are running Ubuntu/Debian, get Ant by typing::
492

    
493
  sudo apt-get install ant
494

    
495
Otherwise, get Ant from the `Apache Ant`_ homepage.
496

    
497
Ant should be installed on your system and the "ant" executable shell script
498
should be available in the user's path. The latest Metacat release was tested
499
with Ant 1.8.2. 
500

    
501
Installing Metacat
502
~~~~~~~~~~~~~~~~~~
503
Instructions for a new install, an upgrade, and a source install are included
504
below.
505

    
506
New Install
507
...........
508
Before installing Metacat, please ensure that all required applications are
509
installed, configured to run with Metacat, and running correctly. If you are
510
upgrading an existing Metacat servlet, please skip to Upgrade. For information
511
about installing from source, skip to Source Install and Upgrade.
512

    
513
To install a new Metacat servlet:
514

    
515
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:
516

    
517
  ::
518

    
519
    sudo mkdir /var/metacat
520

    
521
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):
522

    
523
  ::
524

    
525
    sudo chown -R <tomcat_user> /var/metacat
526

    
527

    
528
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/tomcat7/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., metacat.war) provides the application context, which appears in the URL of the Metacat (e.g., http://yourserver.com/metacat/). To change the context, simply change the name of the WAR file to the desired name before copying it.  To install the Metacat WAR:
529

    
530
  ::
531

    
532
    sudo cp <metacat_package_dir>/metacat.war <tomcat_app_dir>
533

    
534

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

    
537
  ::
538

    
539
    sudo /etc/init.d/tomcat7 restart
540

    
541
Congratulations! You have now installed Metacat. If everything is installed
542
correctly, you should see the Authentication Configuration screen (Figure 2.1)
543
when you type http://yourserver.com/yourcontext/ (e.g.,
544
http://knb.ecoinformatics.org/knb) into a browser. For more information about
545
configuring Metacat, please see the Configuration Section.
546

    
547
.. figure:: images/screenshots/image009.png
548
   :align: center
549

    
550
   The Authentication Configuration screen appears the first time you open a 
551
   new installation of Metacat. 
552

    
553
Upgrade Metacat
554
...............
555
To upgrade an existing binary Metacat installation follow the steps in this
556
section. The steps for upgrading Metacat from source are the same as the
557
instructions for installing from source:
558

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

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

    
563
  ::
564

    
565
    /etc/init.d/tomcat7 stop
566

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

    
569
  ::
570

    
571
    cp <web_app_dir>/metacat <backup_dir>/metacat.<yyyymmdd>
572
    cp <web_app_dir>/metacat.war <backup_dir>/metacat.war.<yyyymmdd>
573

    
574
  Warning: Do not backup the files to the ``<web_app_dir>`` directory.  Tomcat will
575
  try to run the backup copy as a service.
576

    
577
4. Copy the new Metacat WAR file in to the Tomcat applications directory: 
578

    
579
  ::
580

    
581
    sudo cp <metacat_package_dir>/metacat.war <tomcat_app_dir>
582

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

    
587
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. 
588

    
589
  ::
590
   
591
    sudo cp <metacat_package_dir>/authority.war <tomcat_app_dir>
592

    
593
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:  
594

    
595
  ::
596

    
597
    /etc/init.d/tomcat7 restart
598

    
599

    
600
7. Run your new Metacat servlet. Go to a Web browser and visit your installed
601
Metacat application, using a URL of the form: 
602

    
603
  ::
604

    
605
    http://yourserver.yourdomain.com/yourcontext/
606

    
607
You should substitute your context name for "yourcontext" in the URL above
608
(your context will be "metacat" unless you change the name of the metacat.war file to
609
something else). If everything is working correctly, you should be presented
610
with Metacat's Authorization Configuration screen. Note that if you do not have
611
Tomcat integrated with Apache you will probably have to type
612
http://yourserver.yourdomain.com:8080/yourcontext/
613

    
614
Source Install and Upgrade
615
..........................
616
Whether you are building Metacat from the source distribution or source code
617
checked out from SVN, you will need Apache Ant to do the build (see Installing
618
and Configuring Required Software for more information about Ant). 
619

    
620
To install Metacat from source:
621

    
622
1. Edit the build.properties file found in the directory in which you
623
   downloaded Metacat. Note: Throughout the instructions, we will refer to this
624
   directory as ``<metacat_src_dir>``. 
625

    
626
  * Set the build.tomcat.dir property to your Tomcat installation directory.
627
    Metacat will use some of the native Tomcat libraries during the build. For
628
    instance: build.tomcat.dir=/usr/local/tomcat
629
  * Set the app.deploy.dir property to your application deployment directory.
630
    For instance: app.deploy.dir=/usr/local/tomcat/webapps
631

    
632
2. In the ``<metacat_src_dir>``, run: 
633

    
634
  ::
635

    
636
    sudo ant clean install
637

    
638
  You will see the individual modules get built. You should see a "BUILD
639
  SUCCESSFUL" message at the end.
640

    
641
  You should see a new file named metacat.war in your application deployment
642
  directory.
643

    
644
To run your new Metacat servlet, open a Web browser and type::
645

    
646
  http://yourserver.yourdomain.com/yourcontext/ 
647
  (e.g.  http://knb.ecoinformatics.org/metacat/)
648

    
649
Your context will be "metacat" unless you changed the name of the metacat.war file to
650
something else. The servlet may require a few seconds to start up, but once it
651
is running, you will be presented with the Authorization Configuration screen.
652

    
653
Optional Installation Options (LSID Server)
654
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
655

    
656
.. Note::
657

    
658
  The support for LSID identifiers is deprecated, and is being replaced with
659
  support for DOI_ identifiers in a future release. We are maintaining support
660
  for LSIDs on one particular site, but this support will be removed in a
661
  future version of Metacat.
662

    
663
.. _DOI: http://www.doi.org/
664

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

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

    
691
The format of an LSID is:: 
692

    
693
  urn:lsid:<Authority>:<Namespace>:<ObjectID>[:<Version>]
694
  e.g., urn:lsid:ecoinformatics.org:tao:12039:1
695

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

    
702
  http://example.com:9999/authority/data?lsid=urn:lsid:ecoinformatics.org:tao:12039:1
703
  (To return the data)
704

    
705
  http://example.com:9999/authority/metadata?lsid=urn:lsid:ecoinformatics.org:tao:12039:1
706
  (To return the metadata)
707

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

    
714
Install and configure the LSID Server shipped with Metacat
715
..........................................................
716

    
717
To install the LSID server using the binary installation:
718

    
719
1. Copy the authority.war file to Tomcat:
720

    
721
  ::
722

    
723
    sudo cp <metacat_package_directory>/authority.war /usr/share/tomcat7/webapps
724
 
725
2. Set up the LSID server by dropping the authority file into Apache's
726
   sites-available directory and running a2ensite to enable the site:
727

    
728
   ::
729

    
730
     sudo cp <metacat_helper_dir>/authority /etc/apache2/sites-available
731
     sudo a2ensite authority
732

    
733
3. Restart Tomcat. Log in as the user that runs your Tomcat server (often
734
   "tomcat") and type:
735

    
736
   ::
737

    
738
     /etc/init.d/tomcat5.5 restart
739

    
740
4. Restart Apache to bring in changes by typing:
741

    
742
  ::
743

    
744
    sudo /etc/init.d/apache2 restart
745

    
746
5. See notes beneath LSID server source installation for instructions for
747
   modifying the SRV record(s)
748

    
749
To install the LSID server from a source
750
........................................
751

    
752
1. In the build.properties file found in the directory into which you
753
   extracted the Metacat source code, set the authority and config.lsidauthority
754
   properties. For example:
755
  
756
  ::
757
   
758
   authority.context=authority
759
   config.lsidauthority=ecoinformatics.org
760

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

    
763
  ::
764

    
765
    sudo ant war-lsid
766

    
767
3. Copy the LSID WAR file into the Tomcat application directory.
768

    
769
  ::
770

    
771
    sudo cp <metacat_package_dir>/dist/authority.war <tomcat_app_dir>
772

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

    
776
  ::
777

    
778
    /etc/init.d/tomcat7 restart
779

    
780
5. If you are running Tomcat behind the Apache server (the recommended
781
   configuration), set up and enable the authority service site configurations by
782
   typing:
783

    
784
  ::
785

    
786
    sudo cp <metacat_helper_dir>/authority <apache_install_dir>/sites-available
787
    sudo a2ensite authority
788

    
789
  Where <metacat_helper_dir> can be found in <metacat_code_dir>/src/scripts
790

    
791
6.  Restart Apache to bring in changes by typing: 
792

    
793
  ::
794

    
795
    sudo /etc/init.d/apache2 restart
796

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

    
801
    ::
802

    
803
      _lsid._tcp      IN      SRV     1       0       8080    <metacat.edu>.
804

    
805
  Where <metacat.edu> is the name of the machine that will serve as the
806
  physical location of the AuthorityService.
807

    
808
  For example, the value of <metacat.edu> for the below example URL would be
809
  example.com:
810
  
811
    ::
812
    
813
      http://example.com:9999/authority/data?lsid=urn:lsid:ecoinformatics.org:tao:12039:1
814

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

    
817
Troubleshooting
818
~~~~~~~~~~~~~~~
819
We keep and update a list of common problems and their solutions on the KNB
820
website. See http://knb.ecoinformatics.org/software/metacat/troubleshooting.html 
821
for more information.
822

    
823
Installing on Windows
824
---------------------
825
Metacat can be installed on Windows. Please follow the instructions in this
826
section for downloading Metacat, installing the required software, and
827
installing Metacat. Note that Registry and Data Upload functionality has not
828
been tested on Windows.
829

    
830
Download Metacat
831
~~~~~~~~~~~~~~~~
832
To obtain a Metacat WAR file, which is used when installing the Metacat
833
servlet:
834

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

    
839
2. Choose to download and Save the file locally. 
840

    
841
3. Extract the Metacat package files using your Windows zip utility. You
842
   should see a WAR file and several supporting files (we will only use the WAR
843
   file when installing Metacat). 
844

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

    
848
Note: Before installing Metacat, please ensure that all required software is
849
installed and running correctly.
850

    
851

    
852
Install Required Software
853
~~~~~~~~~~~~~~~~~~~~~~~~~
854
Before you can install and run Metacat, you must ensure that a recent Java SDK,
855
PostgreSQL and Tomcat are installed, configured, and running correctly. 
856

    
857
* `Java 7`_
858
* `Apache Tomcat`_
859
* PostgreSQL_ Database
860

    
861
Java 7
862
......
863
To run Metacat, you must have Java 7. Make sure that
864
the JAVA_HOME environment variable is properly set and that both java and javac
865
are on your PATH.
866

    
867
To download and install Java:
868

    
869
1. Browse to: http://www.oracle.com/technetwork/java/javase/downloads/jre7-downloads-1880261.html and follow
870
   the instructions to download JDK 7.
871

    
872
2. Run the downloaded installer to install Java.
873

    
874
3. Set the JAVA_HOME environment variable: In "My Computer" properties, go to
875
   "advanced settings > environment variables". Add:
876

    
877
  ::
878

    
879
    System Variable: JAVA_HOME C:\Program Files\Java\jdk1.7.0_79 
880
    (or whichever version you downloaded)
881

    
882
Apache Tomcat
883
.............
884
We recommend that you install Tomcat version 7.  To download and install Tomcat:
885

    
886
1. Browse to: http://tomcat.apache.org/
887
2. Download the Tomcat core zip file 
888
3. Extract Tomcat files to C:\Program Files\tomcat using the windows zip
889
   utility. 
890

    
891
PostgreSQL Database
892
...................
893
Metacat can be run with several SQL92-compliant database systems, but it has 
894
been most widely tested with PostgreSQL_. Instructions for installing and 
895
configuring PostgreSQL for use with Metacat are included in this section.
896

    
897
To download and install PostgreSQL:
898

    
899
1. Browse to http://www.postgresql.org/download/windows and download the
900
   one-click installer 
901
2. Run the installer 
902
3. Edit C:\Program Files\PostgreSQL\8.3\data and add:
903
  
904
  ::
905

    
906
    host metacat metacat 127.0.0.1 255.255.255.255 password
907

    
908
4. Create a super user. At the command line, enter:
909

    
910
  ::
911

    
912
    C:\Program Files\PostgreSQL\8.3\bin 
913
    createdb -U postgres metacat (enter super user password)
914

    
915
5. Log in to PostgreSQL: 
916

    
917
  ::
918

    
919
    psql -U postgres metacat (enter super user password)
920

    
921
6. Create a Metacat user:
922

    
923
  ::
924

    
925
    CREATE USER metacat WITH UNENCRYPTED PASSWORD 'your_password'
926

    
927
7. Exit PostgreSQL: 
928

    
929
  ::
930

    
931
    \q
932

    
933
8. Restart PostgreSQL from the start menu by selecting:
934
  
935
  ::
936

    
937
    run start/All Programs/PostgreSQL 8.3/Stop Server
938
    run start/All Programs/PostgreSQL 8.3/Start Server
939

    
940

    
941
9. Test the installation by logging in as the metacat user: 
942

    
943
  ::
944
  
945
    psql -U metacat -W -h localhost metacat
946

    
947
10. Exit PostgreSQL:
948

    
949
  ::
950

    
951
    \q
952

    
953
The Metacat servlet automatically creates the required database schema. For
954
more information, please see Database Configuration.
955

    
956
Installing Metacat
957
~~~~~~~~~~~~~~~~~~
958
Instructions for a new install and for an upgrade are included below.
959

    
960
New Install
961
...........
962
Before installing Metacat, please ensure that all required applications are
963
installed, configured to run with Metacat, and running correctly. If you are
964
upgrading an existing Metacat servlet, please skip to Upgrade.
965

    
966
To install a new Metacat servlet:
967

    
968
1. Create the Metacat base directory at: 
969

    
970
  ::
971

    
972
    C:/Program Files/metacat
973

    
974
2. Copy the Metacat WAR file to Tomcat (for information about obtaining a
975
   Metacat WAR file, see Download Metacat): 
976
  
977
  ::
978

    
979
    copy <metacat_package_dir>\metacat.war C:\Program Files\tomcat\webapps
980

    
981
3.  Restart Tomcat: 
982

    
983
  ::
984

    
985
    C:\Program Files\tomcat\shutdown.bat
986
    C:\Program Files\tomcat\startup.bat
987

    
988

    
989
Congratulations! You are now ready to configure Metacat. Please see the
990
Configuration Section for more information. 
991

    
992
Upgrade
993
.......
994
To upgrade an existing Metacat installation:
995

    
996
1. Download and extract the new version of Metacat. For more information about
997
   downloading and extracting Metacat, please see Download Metacat.
998

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

    
1003
  ::
1004

    
1005
    <web_app_dir>/metacat to <backup_dir>/metacat.<yyyymmdd>
1006
    <web_app_dir>/metacat.war to <backup_dir>/metacat.war.<yyyymmdd>
1007

    
1008
  Warning: Do not backup the metacat directory in the <web_app_dir> directory.
1009
  Tomcat will try to run the backup copy as a service.
1010

    
1011
3.  Copy the new Metacat WAR file in to Tomcat applications directory: 
1012

    
1013
  ::
1014

    
1015
    copy metacat.war C:\Program Files\tomcat\webapps
1016

    
1017
4.  Restart Tomcat: 
1018
  
1019
  ::
1020
  
1021
    C:\Program Files\tomcat\shutdown.bat
1022
    C:\Program Files\tomcat\startup.bat
1023

    
1024
Congratulations! You are now ready to configure Metacat. Please see Configuring
1025
Metacat for more information.
1026

    
(13-13/25)