1
|
Downloading and Installing Metacat
|
2
|
==================================
|
3
|
|
4
|
Instructions for both Linux and Windows systems are included in this section.
|
5
|
|
6
|
.. contents::
|
7
|
|
8
|
System Requirements
|
9
|
-------------------
|
10
|
In addition to meeting the recommended system requirements, the server on which
|
11
|
you wish to install Metacat must have the following software installed and
|
12
|
running correctly:
|
13
|
|
14
|
* PostgreSQL_ (or another SQL92-compliant RDBMS like Oracle_)
|
15
|
* `Apache Ant`_ (if building from source)
|
16
|
* `Apache Tomcat`_
|
17
|
* `Apache HTTPD Server`_ (recommended)
|
18
|
|
19
|
* In order to use the Metacat Registry (and for a more robust Web-serving environment in general), the Apache Web server should be installed with Tomcat and the two should be integrated. See the installing Apache for more information.
|
20
|
|
21
|
* `Java 6`_ (Note: Java 5 is deprecated)
|
22
|
|
23
|
.. _PostgreSQL: http://www.postgresql.org/
|
24
|
|
25
|
.. _Oracle: http://www.oracle.com/
|
26
|
|
27
|
.. _Apache Ant: http://ant.apache.org/
|
28
|
|
29
|
.. _Apache Tomcat: http://tomcat.apache.org/
|
30
|
|
31
|
.. _Apache HTTPD Server: http://httpd.apache.org/
|
32
|
|
33
|
.. _Java 6: http://www.oracle.com/technetwork/java/javaee/overview/index.html
|
34
|
|
35
|
System requirements for running Metacat:
|
36
|
|
37
|
* a server running an SQL92-compliant database (PostgreSQL_ recommended)
|
38
|
* at least 512MB RAM
|
39
|
* 200 MB disk space (Note: The amount of disk space required depends on the size of your RDBMS tablespace and the the size and number of documents stored. Metacat itself requires only about 140 MB of free space after installation).
|
40
|
|
41
|
|
42
|
Installing on Linux
|
43
|
-------------------
|
44
|
This section contains instructions for downloading and installing Metacat on
|
45
|
Linux systems. As Mac OS X is based on BSD Unix, these Linux instructions can
|
46
|
be adapted to also work on Mac OS X (although the exact commands for
|
47
|
downloading and installing packages will differ due to the different package
|
48
|
management approaches on the Mac).
|
49
|
|
50
|
Quick Start Overview
|
51
|
~~~~~~~~~~~~~~~~~~~~
|
52
|
For the impatient or those who have already installed Metacat and know what
|
53
|
they are doing, here are the steps needed to install Metacat. Detailed
|
54
|
instructions for each step are in the next section.
|
55
|
|
56
|
1. Download and install prerequisites (`Java 6`_, `Apache Tomcat`_ 6, PostgreSQL_, `Apache HTTPD Server`_)
|
57
|
2. Create a database in PostgreSQL named 'metacat' and authorize access to it in ``pb_hba.conf`` for the user 'metacat'
|
58
|
3. Log in to PostgreSQL and create the 'metacat' user
|
59
|
4. Download Metacat from the `Metacat Download Page`_ and extract the archive
|
60
|
5. ``sudo mkdir /var/metacat; sudo chown -R <tomcat_user> /var/metacat``
|
61
|
6. ``sudo cp <metacat_package_dir>/knb.war <tomcat_app_dir>``
|
62
|
7. ``sudo /etc/init.d/tomcat6 restart``
|
63
|
8. Configure Metacat through the Web interface
|
64
|
|
65
|
.. _Metacat Download Page: http://knb.ecoinformatics.org/software/metacat/
|
66
|
|
67
|
Downloading Metacat
|
68
|
~~~~~~~~~~~~~~~~~~~
|
69
|
Before installing Metacat, please ensure that all required software is
|
70
|
installed and running correctly. To obtain a Metacat WAR file, which is needed
|
71
|
for installation, download one of the following:
|
72
|
|
73
|
* the Metacat installer, which has a pre-built WAR file,
|
74
|
* the Metacat source distribution, which must be built in order to create a WAR file,
|
75
|
* the Metacat source code from SVN. You must build the source code in order to create a WAR file.
|
76
|
|
77
|
Instructions for all three options are discussed below. Note that downloading
|
78
|
the installer (described in the next section) is the simplest way to get
|
79
|
started.
|
80
|
|
81
|
Download the Metacat Installer
|
82
|
..............................
|
83
|
Downloading the Metacat Installer is the simplest way to get started with the
|
84
|
application. To download the installer:
|
85
|
|
86
|
1. Browse to the `Metacat Download Page`_. In the Metacat section, select the link to the "GZIP file" (the link should look like: metacat-bin-X.X.X.tar.gz, where X.X.X is the latest version of Metacat e.g., 1.9.0)
|
87
|
2. Save the file locally.
|
88
|
3. Extract the Metacat package files by typing:
|
89
|
|
90
|
::
|
91
|
|
92
|
tar -xvzf metacat-bin-X.X.X.tar.gz
|
93
|
|
94
|
You should see a WAR file and several supporting files (Table 2.1). The
|
95
|
extraction location will be referred to as the ``<metacat_package_dir>`` for the
|
96
|
remainder of this documentation.
|
97
|
|
98
|
================== ===========================================================
|
99
|
File Description
|
100
|
================== ===========================================================
|
101
|
knb.war The Metacat Web archive file (WAR)
|
102
|
knb The Web definition file used by Apache on Ubuntu/Debian
|
103
|
Linux systems.
|
104
|
knb.ssl The SSL definition file used by Apache on Ubuntu/Debian
|
105
|
Linux systems.
|
106
|
jk.conf The JkMount configuration file used by Apache on
|
107
|
Ubuntu/Debian Linux systems.
|
108
|
workers.properties The workers definition file used by Apache on Ubuntu/Debian
|
109
|
Linux systems.
|
110
|
authority The optional LSID Server application WAR
|
111
|
================== ===========================================================
|
112
|
|
113
|
|
114
|
Download Metacat Source Code
|
115
|
............................
|
116
|
To get the Metacat source distribution:
|
117
|
|
118
|
1. Browse to the `Metacat Download Page`_. In the Metacat section, select the link to the Metacat Source code (it will look something like this: metacat-src-X.X.X.tar.gz, where X.X.X is the latest version of Metacat, e.g., 1.9.0).
|
119
|
2. Save the file locally.
|
120
|
3. Extract the Metacat package files by typing (replace X.X.X with the current version number):
|
121
|
|
122
|
::
|
123
|
|
124
|
tar -xvzf metacat-src-X.X.X.tar.gz
|
125
|
|
126
|
4. Rename the metacat-X.X.X directory to metacat.
|
127
|
|
128
|
Note that you do not need to create the WAR file directly because the Ant
|
129
|
build-file has an "install" target that will build and deploy the WAR for you.
|
130
|
|
131
|
|
132
|
Check Out Metacat Source Code from SVN (for Developers)
|
133
|
.......................................................
|
134
|
If you wish to work with the most recent Metacat code, or you'd like to extend
|
135
|
the Metacat code yourself, you may wish to check out the Metacat source code
|
136
|
from SVN. You will need a Subversion (SVN) client installed and configured on
|
137
|
your system (see the end of this section for information about obtaining an SVN
|
138
|
client).
|
139
|
|
140
|
.. sidebar:: Installing an SVN Client:
|
141
|
|
142
|
If you have not already installed Subversion and you are running Ubuntu/Debian,
|
143
|
you can get the SVN client by typing:
|
144
|
|
145
|
::
|
146
|
|
147
|
sudo apt-get install subversion
|
148
|
|
149
|
Otherwise, you can get the SVN client from The Subversion homepage
|
150
|
(http://subversion.tigris.org/).
|
151
|
|
152
|
To check out the code from SVN, go to the directory where you would like the
|
153
|
code to live and type::
|
154
|
|
155
|
svn co https://code.ecoinformatics.org/code/metacat/tags/METACAT_<rev> metacat
|
156
|
|
157
|
Where ``<rev>`` is the version of the code you want to check out (like 1_9).
|
158
|
|
159
|
To check out the head, type::
|
160
|
|
161
|
svn co https://code.ecoinformatics.org/code/metacat/trunk metacat
|
162
|
|
163
|
You should see a list of files as they check out.
|
164
|
|
165
|
Note that you do not need to create the WAR file directly because the Ant
|
166
|
build-file has an "install" target that will build and deploy the WAR for you.
|
167
|
|
168
|
|
169
|
Installing and Configuring Required Software
|
170
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
171
|
Before you can install and run Metacat, you must ensure that a recent Java SDK,
|
172
|
PostgreSQL (or another SQL92-compliant RDBMS like Oracle 8i), Ant (if
|
173
|
installing from source), and Tomcat are installed and running correctly. We
|
174
|
also highly recommend that you install Apache Web server, as it provides a more
|
175
|
robust Web-serving environment and is required by some Metacat functionality.
|
176
|
|
177
|
* `Java 6`_
|
178
|
* `Apache Tomcat`_
|
179
|
* `Apache HTTPD Server`_ (Highly Recommended)
|
180
|
* PostgreSQL_ Database (or Oracle_)
|
181
|
* `Apache Ant`_ (if building from Source)
|
182
|
|
183
|
Java 6
|
184
|
......
|
185
|
To run Metacat, you should use Java 6 (Java 5 is deprecated and will not be
|
186
|
supported after Metacat version 1.9.2). Make sure that the JAVA_HOME
|
187
|
environment variable is properly set and that both ``java`` and ``javac``
|
188
|
are on your PATH.
|
189
|
|
190
|
To install Java if you are running Ubuntu_/Debian, type::
|
191
|
|
192
|
sudo apt-get install sun-java6-jdk
|
193
|
|
194
|
Click "ok" then "yes" for license agreement.
|
195
|
|
196
|
If you are not using Ubuntu_/Debian, you can get Java from the Oracle_ website.
|
197
|
|
198
|
.. _Ubuntu: http://www.ubuntu.com/
|
199
|
|
200
|
Apache Tomcat
|
201
|
.............
|
202
|
We recommend that you install Tomcat 6 into the directory of your choice.
|
203
|
Included with the Metacat download is a Tomcat-friendly start-up script that
|
204
|
should be installed as well.
|
205
|
|
206
|
Note: we will refer to the Tomcat installation directory as ``<tomcat_home>`` for
|
207
|
the remainder of the documentation.
|
208
|
|
209
|
If you are running Ubuntu_/Debian, get Tomcat by typing::
|
210
|
|
211
|
sudo apt-get install tomcat6
|
212
|
|
213
|
Otherwise, get Tomcat from the `Apache Tomcat`_ page.
|
214
|
|
215
|
Apache HTTPD Server (Highly Recommended)
|
216
|
........................................
|
217
|
Although you have the option of running Metacat with only the Tomcat server, we
|
218
|
highly recommend that you run it behind the Apache Web server for several
|
219
|
reasons; running Tomcat with the Apache server provides a more robust Web
|
220
|
serving environment, and the Apache Web server is required if you wish to
|
221
|
install and run the Metacat Registry.
|
222
|
|
223
|
.. sidebar:: Configuring Apache on an OS other than Ubuntu/Debian
|
224
|
|
225
|
If you are running on an O/S other than Ubuntu/Debian (e.g., Fedora Core or
|
226
|
RedHat Linux) or if you installed the Apache source or binary, you must
|
227
|
manually edit the Apache configuration file, where <apache_install_dir> is the
|
228
|
directory in which Apache is installed:
|
229
|
|
230
|
::
|
231
|
|
232
|
<apache_install_dir>/conf/httpd.conf
|
233
|
|
234
|
1. Configure the log location and level for Mod JK. If your configuration file does not already have the following section, add it and set the log location to any place you'd like:
|
235
|
|
236
|
::
|
237
|
|
238
|
<IfModule mod_jk.c>
|
239
|
JkLogFile "/var/log/tomcat/mod_jk.log"
|
240
|
JkLogLevel info
|
241
|
</IfModule>
|
242
|
|
243
|
2. Configure apache to route traffic to the Metacat application. ServerName should be set to the DNS name of the Metacat server. ScriptAlias and the following Directory section should both point to the cgi-bin directory inside your Metacat installation:
|
244
|
|
245
|
::
|
246
|
|
247
|
<VirtualHost XXX.XXX.XXX.XXX:80>
|
248
|
DocumentRoot /var/www
|
249
|
ServerName dev.nceas.ucsb.edu
|
250
|
ErrorLog /var/log/httpd/error_log
|
251
|
CustomLog /var/log/httpd/access_log common
|
252
|
ScriptAlias /cgi-bin/ "/var/www/cgi-knb/"
|
253
|
<Directory /var/www/cgi-knb/>
|
254
|
AllowOverride None
|
255
|
Options ExecCGI
|
256
|
Order allow,deny
|
257
|
Allow from all
|
258
|
</Directory>
|
259
|
ScriptAlias /knb/cgi-bin/ "/var/www/webapps/knb/cgi-bin/"
|
260
|
<Directory "/var/www/webapps/knb/cgi-bin/">
|
261
|
AllowOverride None
|
262
|
Options ExecCGI
|
263
|
Order allow,deny
|
264
|
Allow from all
|
265
|
</Directory>
|
266
|
JkMount /knb ajp13
|
267
|
JkMount /knb/* ajp13
|
268
|
JkMount /knb/metacat ajp13
|
269
|
JkUnMount /knb/cgi-bin/* ajp13
|
270
|
JkMount /*.jsp ajp13
|
271
|
JkMount /metacat ajp13
|
272
|
JkMount /metacat/* ajp13
|
273
|
</VirtualHost>
|
274
|
|
275
|
3. Copy the "workers.properties" file provided by Metacat into your Apache configuration directory (<apache_install_dir>/conf/). Depending on whether you are installing from binary distribution or source, the workers.properties file will be in one of two locations:
|
276
|
|
277
|
* the directory in which you extracted the Metacat distribution (for binary distribution)
|
278
|
* <metacat_code_dir>/src/scripts/workers.properties (for both the source distribution and source code checked out from SVN)
|
279
|
|
280
|
4. Edit the workers.properties file and make sure the following properties are set correctly:
|
281
|
|
282
|
::
|
283
|
|
284
|
workers.tomcat_home - set to the Tomcat install directory.
|
285
|
workers.java_home - set to the Java install directory.
|
286
|
|
287
|
5. Restart Apache to bring in changes by typing:
|
288
|
|
289
|
::
|
290
|
|
291
|
sudo /etc/init.d/apache2 restart
|
292
|
|
293
|
This section contains instructions for installing and configuring the Apache
|
294
|
Web server for Metacat on an Ubuntu_/Debian system. Instructions for configuring
|
295
|
Apache running on other Linux systems are included in the sidebar.
|
296
|
|
297
|
1. Install the Apache and Mod JK packages (Mod JK is the module Apache uses to talk to Tomcat applications) by typing:
|
298
|
|
299
|
::
|
300
|
|
301
|
sudo apt-get install apache2 libapache2-mod-jk
|
302
|
|
303
|
If you are installing the Apache server on an Ubuntu/Debian system, and you
|
304
|
installed Apache using apt-get as described above, the Metacat code will have
|
305
|
helper files that can be dropped into directories to configure Apache.
|
306
|
Depending on whether you are installing from binary distribution or source,
|
307
|
these helper files will be in one of two locations:
|
308
|
|
309
|
* the directory in which you extracted the distribution (for binary distribution)
|
310
|
* ``<metacat_code_dir>/src/scripts`` (for both the source distribution and source code checked out from SVN). We will refer to the directory with the helper scripts as ``<metacat_helper_dir>`` and the directory where Apache is installed (e.g., ``/etc/apache2/``) as ``<apache_install_dir>``.
|
311
|
|
312
|
2. Set up Mod JK apache configuration by typing:
|
313
|
|
314
|
::
|
315
|
|
316
|
sudo cp <metacat_helper_dir>/jk.conf <apache_install_dir>/mods-available
|
317
|
sudo cp <metacat_helper_dir>/workers.properties <apache_install_dir>
|
318
|
|
319
|
3. Disable and re-enable the Apache Mod JK module to pick up the new changes:
|
320
|
|
321
|
::
|
322
|
|
323
|
sudo a2dismod jk
|
324
|
sudo a2enmod jk
|
325
|
|
326
|
4. Apache needs to know about the Metacat site. The helper file named "knb" has rules that tell Apache which traffic to route to Metacat. Set up the knb (Metacat) site by dropping the knb file into the sites-available directory and running a2ensite to enable the site:
|
327
|
|
328
|
::
|
329
|
|
330
|
sudo cp <metacat_helper_dir>/knb <apache_install_dir>/sites-available
|
331
|
sudo a2ensite knb
|
332
|
|
333
|
5. Restart Apache to bring in changes by typing:
|
334
|
|
335
|
::
|
336
|
|
337
|
sudo /etc/init.d/apache2 restart
|
338
|
|
339
|
|
340
|
PostgreSQL Database
|
341
|
...................
|
342
|
Metacat has been most widely tested with PostgreSQL_ and we recommend using it.
|
343
|
Instructions for installing and configuring Oracle are also included in the
|
344
|
next section. To install and configure PostgreSQL_:
|
345
|
|
346
|
1. If you are running Ubuntu_/Debian, get PostgreSQL by typing:
|
347
|
|
348
|
::
|
349
|
|
350
|
sudo apt-get install postgresql
|
351
|
|
352
|
On other systems, install the rpms for postgres.
|
353
|
|
354
|
2. Start the database by running:
|
355
|
|
356
|
::
|
357
|
|
358
|
/etc/init.d/postgresql start
|
359
|
|
360
|
3. Change to postgres user:
|
361
|
|
362
|
::
|
363
|
|
364
|
sudo su - postgres
|
365
|
|
366
|
|
367
|
4. Set up an empty Metacat database instance by editing the postgreSQL configuration file:
|
368
|
|
369
|
::
|
370
|
|
371
|
gedit /etc/postgresql/8.3/main/pg_hba.conf
|
372
|
|
373
|
|
374
|
Add the following line to the configuration file:
|
375
|
|
376
|
::
|
377
|
|
378
|
host metacat metacat 127.0.0.1 255.255.255.255 password
|
379
|
|
380
|
|
381
|
Save the file and then create the Metacat instance:
|
382
|
|
383
|
::
|
384
|
|
385
|
createdb metacat
|
386
|
|
387
|
|
388
|
5. Log in to postgreSQL by typing:
|
389
|
|
390
|
::
|
391
|
|
392
|
psql metacat
|
393
|
|
394
|
|
395
|
6. At the psql prompt, create the Metacat user by typing:
|
396
|
|
397
|
::
|
398
|
|
399
|
CREATE USER metacat WITH UNENCRYPTED PASSWORD 'your_password';
|
400
|
|
401
|
where 'your_password' is whatever password you would like for the Metacat user.
|
402
|
|
403
|
7. Exit PostgreSQL by typing
|
404
|
|
405
|
::
|
406
|
|
407
|
\q
|
408
|
|
409
|
8. Restart the PostgreSQL database to bring in changes:
|
410
|
|
411
|
::
|
412
|
|
413
|
/etc/init.d/postgresql-8.3 restart
|
414
|
|
415
|
9. Log out of the postgres user account by typing:
|
416
|
|
417
|
::
|
418
|
|
419
|
logout
|
420
|
|
421
|
10. Test the installation and Metacat account by typing:
|
422
|
|
423
|
::
|
424
|
|
425
|
psql -U metacat -W -h localhost metacat
|
426
|
|
427
|
11. Log out of postgreSQL:
|
428
|
|
429
|
::
|
430
|
|
431
|
\q
|
432
|
|
433
|
|
434
|
The Metacat servlet automatically creates the required database schema. For
|
435
|
more information about configuring the database, please see Database
|
436
|
Configuration.
|
437
|
|
438
|
Installing and Configuring Oracle 8i
|
439
|
....................................
|
440
|
To use Oracle 8i with Metacat, the Oracle RDBMS must be installed and running
|
441
|
as a daemon on the system. In addition the JDBC listener must be enabled.
|
442
|
Enable it by logging in as an Oracle user and typing::
|
443
|
|
444
|
lsnrctl start
|
445
|
|
446
|
Your instance should have a table space of at least 5 MB (10 MB or higher
|
447
|
recommended). You must also create and enable a username specific to Metacat.
|
448
|
The Metacat user must have most normal permissions including: CREATE SESSION,
|
449
|
CREATE TABLE, CREATE INDEX, CREATE TRIGGER, EXECUTE PROCEDURE, EXECUTE TYPE,
|
450
|
etc. If an action is unexplainably rejected by Metacat, the user permissions
|
451
|
are (most likely) not correctly set.
|
452
|
|
453
|
The Metacat servlet automatically creates the required database schema. For
|
454
|
more information, please see Database Configuration.
|
455
|
|
456
|
Apache Ant (if building from Source)
|
457
|
....................................
|
458
|
If you are building Metacat from a source distribution or from source code
|
459
|
checked out from SVN, Ant is required. (Users installing Metacat from the
|
460
|
binary distribution do not require it.) Ant is a Java-based build application
|
461
|
similar to Make on UNIX systems. It takes build instructions from a file named
|
462
|
"build.xml", which is found in the root installation directory. Metacat source
|
463
|
code comes with a default "build.xml" file that may require some modification
|
464
|
upon installation.
|
465
|
|
466
|
If you are running Ubuntu/Debian, get Ant by typing::
|
467
|
|
468
|
sudo apt-get install ant
|
469
|
|
470
|
Otherwise, get Ant from the `Apache Ant`_ homepage.
|
471
|
|
472
|
Ant should be installed on your system and the "ant" executable shell script
|
473
|
should be available in the user's path. The latest Metacat release was tested
|
474
|
with Ant 1.8.2.
|
475
|
|
476
|
Installing Metacat
|
477
|
~~~~~~~~~~~~~~~~~~
|
478
|
Instructions for a new install, an upgrade, and a source install are included
|
479
|
below.
|
480
|
|
481
|
New Install
|
482
|
...........
|
483
|
Before installing Metacat, please ensure that all required applications are
|
484
|
installed, configured to run with Metacat, and running correctly. If you are
|
485
|
upgrading an existing Metacat servlet, please skip to Upgrade. For information
|
486
|
about installing from source, skip to Source Install and Upgrade.
|
487
|
|
488
|
To install a new Metacat servlet:
|
489
|
|
490
|
1. Create the Metacat directory. Metacat uses a base directory to store data, metadata, temporary files, and configuration backups. This directory should be outside of the Tomcat application directory so that it will not get wiped out during an upgrade. Typically, the directory is '/var/metacat', as shown in the instructions. If you choose a different location, remember it. You will be asked to configure Metacat to point to the base directory at startup. Create the Metacat directory by typing:
|
491
|
|
492
|
::
|
493
|
|
494
|
sudo mkdir /var/metacat
|
495
|
|
496
|
2. Change the ownership of the directory to the user that will start Tomcat by typing (note: If you are starting Tomcat as the root user, you do not need to run the chown command):
|
497
|
|
498
|
::
|
499
|
|
500
|
sudo chown -R <tomcat_user> /var/metacat
|
501
|
|
502
|
|
503
|
3. Install the Metacat WAR in the Tomcat web-application directory. For instructions on downloading the Metacat WAR, please see Downloading Metacat. Typically, Tomcat will look for its application files (WAR files) in the <tomcat_home>/webapps directory (e.g., /usr/share/tomcat6/webapps). Your instance of Tomcat may be configured to look in a different directory. We will refer to the Tomcat application directory as <tomcat_app_dir>. NOTE: The name of the WAR file (e.g., knb.war) provides the application context, which appears in the URL of the Metacat (e.g., http://yourserver.com/knb/). To change the context, simply change the name of the WAR file to the desired name before copying it. To install the Metacat WAR:
|
504
|
|
505
|
::
|
506
|
|
507
|
sudo cp <metacat_package_dir>/knb.war <tomcat_app_dir>
|
508
|
|
509
|
|
510
|
4. Restart Tomcat. Log in as the user that runs your Tomcat server (often "tomcat") and type:
|
511
|
|
512
|
::
|
513
|
|
514
|
/etc/init.d/tomcat6 restart
|
515
|
|
516
|
Congratulations! You have now installed Metacat. If everything is installed
|
517
|
correctly, you should see the Authentication Configuration screen (Figure 2.1)
|
518
|
when you type http://yourserver.com/yourcontext/ (e.g.,
|
519
|
http://knb.ecoinformatics.org/knb) into a browser. For more information about
|
520
|
configuring Metacat, please see the Configuration Section.
|
521
|
|
522
|
.. figure:: images/screenshots/image009.png
|
523
|
:align: center
|
524
|
|
525
|
The Authentication Configuration screen appears the first time you open a
|
526
|
new installation of Metacat.
|
527
|
|
528
|
Upgrade Metacat
|
529
|
...............
|
530
|
To upgrade an existing binary Metacat installation follow the steps in this
|
531
|
section. The steps for upgrading Metacat from source are the same as the
|
532
|
instructions for installing from source:
|
533
|
|
534
|
1. Download and extract the new version of Metacat. For more information about downloading and extracting Metacat, please see Downloading Metacat.
|
535
|
|
536
|
2. Stop running Metacat. To stop Metacat, log in as the user that runs your Tomcat server (often "tomcat") and type:
|
537
|
|
538
|
::
|
539
|
|
540
|
/etc/init.d/tomcat6 stop
|
541
|
|
542
|
3. Back up the existing Metacat installation. Although not required, we highly recommend that you back up your existing Metacat to a backup directory (<backup_dir>) before installing a new one. You can do so by typing:
|
543
|
|
544
|
::
|
545
|
|
546
|
cp <web_app_dir>/knb <backup_dir>/knb.<yyyymmdd>
|
547
|
cp <web_app_dir>/knb.war <backup_dir>/knb.war.<yyyymmdd>
|
548
|
|
549
|
Warning: Do not backup the files to the ``<web_app_dir>`` directory. Tomcat will
|
550
|
try to run the backup copy as a service.
|
551
|
|
552
|
4. Copy the new Metacat WAR file in to the Tomcat applications directory:
|
553
|
|
554
|
::
|
555
|
|
556
|
sudo cp <metacat_package_dir>/knb.war <tomcat_app_dir>
|
557
|
|
558
|
Note: Typically, Tomcat will look for its application files (WAR files) in the
|
559
|
``<tomcat_home>/webapps`` directory. Your instance of Tomcat may be configured to
|
560
|
look in a different directory.
|
561
|
|
562
|
5. If you have been (or would like to start) running an LSID server, copy the new authority.war file to the Tomcat applications directory. For more information about the LSID server, please see Optional Installation Options.
|
563
|
|
564
|
::
|
565
|
|
566
|
sudo cp <metacat_package_dir>/authority.war <tomcat_app_dir>
|
567
|
|
568
|
6. Restart Tomcat (and Apache if you have Tomcat integrated with it). Log in as the user that runs your Tomcat server (often "tomcat"), and type:
|
569
|
|
570
|
::
|
571
|
|
572
|
/etc/init.d/tomcat6 restart
|
573
|
|
574
|
|
575
|
7. Run your new Metacat servlet. Go to a Web browser and visit your installed
|
576
|
Metacat application, using a URL of the form:
|
577
|
|
578
|
::
|
579
|
|
580
|
http://yourserver.yourdomain.com/yourcontext/
|
581
|
|
582
|
You should substitute your context name for "yourcontext" in the URL above
|
583
|
(your context will be "knb" unless you change the name of the knb.war file to
|
584
|
something else). If everything is working correctly, you should be presented
|
585
|
with Metacat's Authorization Configuration screen. Note that if you do not have
|
586
|
Tomcat integrated with Apache you will probably have to type
|
587
|
http://yourserver.yourdomain.com:8080/yourcontext/
|
588
|
|
589
|
Source Install and Upgrade
|
590
|
..........................
|
591
|
Whether you are building Metacat from the source distribution or source code
|
592
|
checked out from SVN, you will need Apache Ant to do the build (see Installing
|
593
|
and Configuring Required Software for more information about Ant).
|
594
|
|
595
|
To install Metacat from source:
|
596
|
|
597
|
1. Edit the build.properties file found in the directory in which you
|
598
|
downloaded Metacat. Note: Throughout the instructions, we will refer to this
|
599
|
directory as ``<metacat_src_dir>``.
|
600
|
|
601
|
* Set the build.tomcat.dir property to your Tomcat installation directory.
|
602
|
Metacat will use some of the native Tomcat libraries during the build. For
|
603
|
instance: build.tomcat.dir=/usr/local/tomcat
|
604
|
* Set the app.deploy.dir property to your application deployment directory.
|
605
|
For instance: app.deploy.dir=/usr/local/tomcat/webapps
|
606
|
|
607
|
2. In the ``<metacat_src_dir>``, run:
|
608
|
|
609
|
::
|
610
|
|
611
|
sudo ant clean install
|
612
|
|
613
|
You will see the individual modules get built. You should see a "BUILD
|
614
|
SUCCESSFUL" message at the end.
|
615
|
|
616
|
You should see a new file named knb.war in your application deployment
|
617
|
directory.
|
618
|
|
619
|
To run your new Metacat servlet, open a Web browser and type::
|
620
|
|
621
|
http://yourserver.yourdomain.com/yourcontext/
|
622
|
(e.g. http://knb.ecoinformatics.org/knb/)
|
623
|
|
624
|
Your context will be "knb" unless you changed the name of the knb.war file to
|
625
|
something else. The servlet may require a few seconds to start up, but once it
|
626
|
is running, you will be presented with the Authorization Configuration screen.
|
627
|
|
628
|
Optional Installation Options (LSID Server)
|
629
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
630
|
|
631
|
.. Note::
|
632
|
|
633
|
The support for LSID identifiers is deprecated, and is being replaced with
|
634
|
support for DOI_ identifiers in a future release. We are maintaining support
|
635
|
for LSIDs on one particular site, but this support will be removed in a
|
636
|
future version of Metacat.
|
637
|
|
638
|
.. _DOI: http://www.doi.org/
|
639
|
|
640
|
Metacat's optional LSID server allows Metacat to use a standardized syntax for
|
641
|
identifying data sets, in addition to Metacat's internal, custom scheme for
|
642
|
identifiers. LSID's were designed to identify complex biological entities with
|
643
|
short identifiers (much like DOIs in publishing) that are both computer and
|
644
|
human readable. LSID identifiers are URIs and are therefore usable in many
|
645
|
Internet applications, but they also cleanly separate the identity of a data
|
646
|
set (i.e., its permenant identifier) from its current location (e.g., the list
|
647
|
of URLs from which it might be retrieved). LSIDs accomplish this by using a
|
648
|
level of indirection; the identifier represents simply a name without location,
|
649
|
but an associated resolver service can be used to locate the current location
|
650
|
of the data and medata for the data set. This is accomplished by establishing
|
651
|
a well-known location for the resolution service for each authority using an
|
652
|
infrequently used feature of the domain name system called SRV records. At its
|
653
|
most basic, resolution of an identifier is performed when a client looks up the
|
654
|
SRV record for an LSID by querying DNS, which returns the current host and port
|
655
|
of the authority web service, which is in turn used to locate the data and
|
656
|
metadata.
|
657
|
|
658
|
Using LSIDs to identify data records is being debated among members of the
|
659
|
Taxonomic Databases Working Group (TDWG). There are several alternate
|
660
|
technologies that are under consideration (e.g., DOI_, plain http URIs), and so
|
661
|
at this time the support for LSIDs in Metacat has been created on an
|
662
|
experimental basis only. If the LSID approach is ratified by the broader
|
663
|
community, we will expand support for LSIDs in Metacat, but until then it is an
|
664
|
optional and experimental feature.
|
665
|
|
666
|
The format of an LSID is::
|
667
|
|
668
|
urn:lsid:<Authority>:<Namespace>:<ObjectID>[:<Version>]
|
669
|
e.g., urn:lsid:ecoinformatics.org:tao:12039:1
|
670
|
|
671
|
When you enable the Metacat LSID support, you can use LSID clients (such as
|
672
|
LSID Launchpad) and LSID notation to query Metacat for data and metadata. LSID
|
673
|
notation can be used directly in Metacat HTTP queries as well. For example, a
|
674
|
data package with an ID tao.12039.1 that is stored in a Metacat available at:
|
675
|
http://example.com:9999 can be accessed by the following HTTP Metacat queries::
|
676
|
|
677
|
http://example.com:9999/authority/data?lsid=urn:lsid:ecoinformatics.org:tao:12039:1
|
678
|
(To return the data)
|
679
|
|
680
|
http://example.com:9999/authority/metadata?lsid=urn:lsid:ecoinformatics.org:tao:12039:1
|
681
|
(To return the metadata)
|
682
|
|
683
|
Notice that in the HTTP query strings, the periods in the data package ID have
|
684
|
been replaced with colons. The authority (ecoinformatics.org) must be properly
|
685
|
configured by the Metacat administrator. Note: In order to configure the
|
686
|
authority, you must have access to the DNS server for the Metacat domain.
|
687
|
Further instructions are provided below.
|
688
|
|
689
|
Install and configure the LSID Server shipped with Metacat
|
690
|
..........................................................
|
691
|
|
692
|
To install the LSID server using the binary installation:
|
693
|
|
694
|
1. Copy the authority.war file to Tomcat:
|
695
|
|
696
|
::
|
697
|
|
698
|
sudo cp <metacat_package_directory>/authority.war /usr/share/tomcat6/webapps
|
699
|
|
700
|
2. Set up the LSID server by dropping the authority file into Apache's
|
701
|
sites-available directory and running a2ensite to enable the site:
|
702
|
|
703
|
::
|
704
|
|
705
|
sudo cp <metacat_helper_dir>/authority /etc/apache2/sites-available
|
706
|
sudo a2ensite authority
|
707
|
|
708
|
3. Restart Tomcat. Log in as the user that runs your Tomcat server (often
|
709
|
"tomcat") and type:
|
710
|
|
711
|
::
|
712
|
|
713
|
/etc/init.d/tomcat5.5 restart
|
714
|
|
715
|
4. Restart Apache to bring in changes by typing:
|
716
|
|
717
|
::
|
718
|
|
719
|
sudo /etc/init.d/apache2 restart
|
720
|
|
721
|
5. See notes beneath LSID server source installation for instructions for
|
722
|
modifying the SRV record(s)
|
723
|
|
724
|
To install the LSID server from a source
|
725
|
........................................
|
726
|
|
727
|
1. In the build.properties file found in the directory into which you
|
728
|
extracted the Metacat source code, set the authority and config.lsidauthority
|
729
|
properties. For example:
|
730
|
|
731
|
::
|
732
|
|
733
|
authority.context=authority
|
734
|
config.lsidauthority=ecoinformatics.org
|
735
|
|
736
|
2. In the <metacat-src-dirctory> create the authority.war by running:
|
737
|
|
738
|
::
|
739
|
|
740
|
sudo ant war-lsid
|
741
|
|
742
|
3. Copy the LSID WAR file into the Tomcat application directory.
|
743
|
|
744
|
::
|
745
|
|
746
|
sudo cp <metacat_package_dir>/dist/authority.war <tomcat_app_dir>
|
747
|
|
748
|
4. Restart Tomcat. Log in as the user that runs your Tomcat server (often
|
749
|
"tomcat") and type:
|
750
|
|
751
|
::
|
752
|
|
753
|
/etc/init.d/tomcat6 restart
|
754
|
|
755
|
5. If you are running Tomcat behind the Apache server (the recommended
|
756
|
configuration), set up and enable the authority service site configurations by
|
757
|
typing:
|
758
|
|
759
|
::
|
760
|
|
761
|
sudo cp <metacat_helper_dir>/authority <apache_install_dir>/sites-available
|
762
|
sudo a2ensite authority
|
763
|
|
764
|
Where <metacat_helper_dir> can be found in <metacat_code_dir>/src/scripts
|
765
|
|
766
|
6. Restart Apache to bring in changes by typing:
|
767
|
|
768
|
::
|
769
|
|
770
|
sudo /etc/init.d/apache2 restart
|
771
|
|
772
|
Once the authority.war is installed, you must also modify the SRV record(s)
|
773
|
on the DNS server for the domain hosting the Metacat. The record should be
|
774
|
added to the master zone file for the metacat's DNS server:
|
775
|
|
776
|
::
|
777
|
|
778
|
_lsid._tcp IN SRV 1 0 8080 <metacat.edu>.
|
779
|
|
780
|
Where <metacat.edu> is the name of the machine that will serve as the
|
781
|
physical location of the AuthorityService.
|
782
|
|
783
|
For example, the value of <metacat.edu> for the below example URL would be
|
784
|
example.com:
|
785
|
|
786
|
::
|
787
|
|
788
|
http://example.com:9999/authority/data?lsid=urn:lsid:ecoinformatics.org:tao:12039:1
|
789
|
|
790
|
For more information, please see http://www.ibm.com/developerworks/opensource/library/os-lsid/
|
791
|
|
792
|
Troubleshooting
|
793
|
~~~~~~~~~~~~~~~
|
794
|
We keep and update a list of common problems and their solutions on the KNB
|
795
|
website. See http://knb.ecoinformatics.org/software/metacat/troubleshooting.html
|
796
|
for more information.
|
797
|
|
798
|
Installing on Windows
|
799
|
---------------------
|
800
|
Metacat can be installed on Windows. Please follow the instructions in this
|
801
|
section for downloading Metacat, installing the required software, and
|
802
|
installing Metacat. Note that Registry and Data Upload functionality has not
|
803
|
been tested on Windows.
|
804
|
|
805
|
Download Metacat
|
806
|
~~~~~~~~~~~~~~~~
|
807
|
To obtain a Metacat WAR file, which is used when installing the Metacat
|
808
|
servlet:
|
809
|
|
810
|
1. Browse to the KNB Software Download Page. In the Metacat section, select
|
811
|
the link that looks like: metacat-bin-X.X.X.zip, where X.X.X is the latest
|
812
|
version of Metacat (e.g., 2.0.0).
|
813
|
|
814
|
2. Choose to download and Save the file locally.
|
815
|
|
816
|
3. Extract the Metacat package files using your Windows zip utility. You
|
817
|
should see a WAR file and several supporting files (we will only use the WAR
|
818
|
file when installing Metacat).
|
819
|
|
820
|
Note: The location where these files were extracted will be referred to as the
|
821
|
``<metacat_package_dir>`` for the remainder of this documentation.
|
822
|
|
823
|
Note: Before installing Metacat, please ensure that all required software is
|
824
|
installed and running correctly.
|
825
|
|
826
|
|
827
|
Install Required Software
|
828
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
829
|
Before you can install and run Metacat, you must ensure that a recent Java SDK,
|
830
|
PostgreSQL and Tomcat are installed, configured, and running correctly.
|
831
|
|
832
|
* `Java 6`_
|
833
|
* `Apache Tomcat`_
|
834
|
* PostgreSQL_ Database
|
835
|
|
836
|
Java 6
|
837
|
......
|
838
|
To run Metacat, you must have Java 6. (Java 5 is deprecated). Make sure that
|
839
|
the JAVA_HOME environment variable is properly set and that both java and javac
|
840
|
are on your PATH.
|
841
|
|
842
|
To download and install Java:
|
843
|
|
844
|
1. Browse to: http://java.sun.com/javase/downloads/widget/jdk6.jsp and follow
|
845
|
the instructions to download JDK 6.
|
846
|
|
847
|
2. Run the downloaded installer to install Java.
|
848
|
|
849
|
3. Set the JAVA_HOME environment variable: In "My Computer" properties, go to
|
850
|
"advanced settings > environment variables". Add:
|
851
|
|
852
|
::
|
853
|
|
854
|
System Variable: JAVA_HOME C:\Program Files\Java\jdk1.6.0_18
|
855
|
(or whichever version you downloaded)
|
856
|
|
857
|
Apache Tomcat
|
858
|
.............
|
859
|
We recommend that you install Tomcat version 6. To download and install Tomcat:
|
860
|
|
861
|
1. Browse to: http://tomcat.apache.org/
|
862
|
2. Download the Tomcat core zip file
|
863
|
3. Extract Tomcat files to C:\Program Files\tomcat using the windows zip
|
864
|
utility.
|
865
|
|
866
|
PostgreSQL Database
|
867
|
...................
|
868
|
Metacat can be run with several SQL92-compliant database systems, but it has
|
869
|
been most widely tested with PostgreSQL_. Instructions for installing and
|
870
|
configuring PostgreSQL for use with Metacat are included in this section.
|
871
|
|
872
|
To download and install PostgreSQL:
|
873
|
|
874
|
1. Browse to http://www.postgresql.org/download/windows and download the
|
875
|
one-click installer
|
876
|
2. Run the installer
|
877
|
3. Edit C:\Program Files\PostgreSQL\8.3\data and add:
|
878
|
|
879
|
::
|
880
|
|
881
|
host metacat metacat 127.0.0.1 255.255.255.255 password
|
882
|
|
883
|
4. Create a super user. At the command line, enter:
|
884
|
|
885
|
::
|
886
|
|
887
|
C:\Program Files\PostgreSQL\8.3\bin
|
888
|
createdb -U postgres metacat (enter super user password)
|
889
|
|
890
|
5. Log in to PostgreSQL:
|
891
|
|
892
|
::
|
893
|
|
894
|
psql -U postgres metacat (enter super user password)
|
895
|
|
896
|
6. Create a Metacat user:
|
897
|
|
898
|
::
|
899
|
|
900
|
CREATE USER metacat WITH UNENCRYPTED PASSWORD 'your_password'
|
901
|
|
902
|
7. Exit PostgreSQL:
|
903
|
|
904
|
::
|
905
|
|
906
|
\q
|
907
|
|
908
|
8. Restart PostgreSQL from the start menu by selecting:
|
909
|
|
910
|
::
|
911
|
|
912
|
run start/All Programs/PostgreSQL 8.3/Stop Server
|
913
|
run start/All Programs/PostgreSQL 8.3/Start Server
|
914
|
|
915
|
|
916
|
9. Test the installation by logging in as the metacat user:
|
917
|
|
918
|
::
|
919
|
|
920
|
Psql –U metacat –W –h localhost metacat
|
921
|
|
922
|
10. Exit PostgreSQL:
|
923
|
|
924
|
::
|
925
|
|
926
|
\q
|
927
|
|
928
|
The Metacat servlet automatically creates the required database schema. For
|
929
|
more information, please see Database Configuration.
|
930
|
|
931
|
Installing Metacat
|
932
|
~~~~~~~~~~~~~~~~~~
|
933
|
Instructions for a new install and for an upgrade are included below.
|
934
|
|
935
|
New Install
|
936
|
...........
|
937
|
Before installing Metacat, please ensure that all required applications are
|
938
|
installed, configured to run with Metacat, and running correctly. If you are
|
939
|
upgrading an existing Metacat servlet, please skip to Upgrade.
|
940
|
|
941
|
To install a new Metacat servlet:
|
942
|
|
943
|
1. Create the Metacat base directory at:
|
944
|
|
945
|
::
|
946
|
|
947
|
C:/Program Files/metacat
|
948
|
|
949
|
2. Copy the Metacat WAR file to Tomcat (for information about obtaining a
|
950
|
Metacat WAR file, see Download Metacat):
|
951
|
|
952
|
::
|
953
|
|
954
|
copy <metacat_package_dir>\knb.war C:\Program Files\tomcat\webapps
|
955
|
|
956
|
3. Restart Tomcat:
|
957
|
|
958
|
::
|
959
|
|
960
|
C:\Program Files\tomcat\shutdown.bat
|
961
|
C:\Program Files\tomcat\startup.bat
|
962
|
|
963
|
|
964
|
Congratulations! You are now ready to configure Metacat. Please see the
|
965
|
Configuration Section for more information.
|
966
|
|
967
|
Upgrade
|
968
|
.......
|
969
|
To upgrade an existing Metacat installation:
|
970
|
|
971
|
1. Download and extract the new version of Metacat. For more information about
|
972
|
downloading and extracting Metacat, please see Download Metacat.
|
973
|
|
974
|
2. Back up the existing Metacat installation. Although not required, we highly
|
975
|
recommend that you back up your existing Metacat to a backup directory
|
976
|
(<backup_dir>) before installing a new version. You can do so by copying:
|
977
|
|
978
|
::
|
979
|
|
980
|
<web_app_dir>/knb to <backup_dir>/knb.<yyyymmdd>
|
981
|
<web_app_dir>/knb.war to <backup_dir>/knb.war.<yyyymmdd>
|
982
|
|
983
|
Warning: Do not backup the knb directory in the <web_app_dir> directory.
|
984
|
Tomcat will try to run the backup copy as a service.
|
985
|
|
986
|
3. Copy the new Metacat WAR file in to Tomcat applications directory:
|
987
|
|
988
|
::
|
989
|
|
990
|
copy knb.war C:\Program Files\tomcat\webapps
|
991
|
|
992
|
4. Restart Tomcat:
|
993
|
|
994
|
::
|
995
|
|
996
|
C:\Program Files\tomcat\shutdown.bat
|
997
|
C:\Program Files\tomcat\startup.bat
|
998
|
|
999
|
Congratulations! You are now ready to configure Metacat. Please see Configuring
|
1000
|
Metacat for more information.
|
1001
|
|