Project

General

Profile

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

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_ 
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 PostgreSQL_ database
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 7`_, `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 Linux systems. 
103
metacat-site-ssl.conf   Sample SSL definition file used by Apache on Ubuntu/Debian Linux systems.
104
jk.conf                 Sample JkMount configuration file used by Apache on Ubuntu/Debian Linux systems. 
105
workers.properties      Sample workers definition file used by Apache on Ubuntu/Debian Linux systems. 
106
metacat-index.war       The Metacat Index WAR for supporting SOLR query features Optional unless Metacat UI is being used.
107
metacatui.war           The Metacat UI - can be deployed as a webapp or directly in webserverMetacat UI requires metacat-index be deployed and configured.
108
authority.war           The optional LSID Server application WAR
109
=====================   ==================================================================================================================================
110

    
111

    
112
Download Metacat Source Code
113
............................
114
To get the Metacat source distribution:
115

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

    
120
::
121

    
122
  tar -xvzf metacat-src-X.X.X.tar.gz
123

    
124
4. Rename the metacat-X.X.X directory to metacat. 
125

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

    
129

    
130
Check Out Metacat Source Code from SVN (for Developers)
131
.......................................................
132

    
133
.. sidebar:: Installing an SVN Client:
134

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

    
140
        sudo apt-get install subversion
141

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

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

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

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

    
158
To check out the head, type::
159

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

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

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

    
167

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

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

    
182
Java 7
183
......
184
To run Metacat, you should use Java 7. Make sure that the JAVA_HOME
185
environment variable is properly set and that both ``java`` and ``javac`` 
186
are on your PATH. 
187

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

    
190
  sudo apt-get install openjdk-7-jdk
191

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

    
194
.. _Ubuntu: http://www.ubuntu.com/
195

    
196
Apache Tomcat
197
.............
198
We recommend that you install Tomcat 6 or 7 into the directory of your choice.
199
Included with the Metacat download is a Tomcat-friendly start-up script that
200
should be installed as well.
201

    
202
Note: we will refer to the Tomcat installation directory as ``<tomcat_home>`` for
203
the remainder of the documentation. 
204

    
205
If you are running Ubuntu_/Debian, get Tomcat by typing::
206

    
207
  sudo apt-get install tomcat7
208

    
209
Otherwise, get Tomcat from the `Apache Tomcat`_ page.
210

    
211
After installing Tomcat, you can switch back to the Sun JDK by typing::
212

    
213
  sudo update-alternatives --config java
214
  
215
and selecting the correct Java installation.
216

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

    
219
  <tomcat_home>/conf/server.xml
220
  
221
For DataONE deployments edit::  
222

    
223
	/etc/tomcat7/catalina.properties
224
	
225
to include::
226

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

    
238
.. sidebar:: Configuring Apache on an OS other than Ubuntu/Debian 
239

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

    
245
  ::
246

    
247
    <apache_install_dir>/conf/httpd.conf
248

    
249
  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:
250

    
251
    ::
252

    
253
      <IfModule mod_jk.c> 
254
        JkLogFile "/var/log/tomcat/mod_jk.log" 
255
        JkLogLevel info 
256
      </IfModule> 
257

    
258
  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:
259

    
260
    ::
261

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

    
288
  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:
289

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

    
293
  4. Edit the workers.properties file and make sure the following properties are set correctly:
294

    
295
    ::
296

    
297
      workers.tomcat_home -  set to the Tomcat install directory. 
298
      workers.java_home - set to the Java install directory. 
299

    
300
  5. Restart Apache to bring in changes by typing:
301

    
302
    ::
303

    
304
      sudo /etc/init.d/apache2 restart
305

    
306
This section contains instructions for installing and configuring the Apache
307
Web server for Metacat on an Ubuntu_/Debian system. Instructions for configuring
308
Apache running on other Linux systems are included in the sidebar.
309

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

    
312
::
313

    
314
  sudo apt-get install apache2 libapache2-mod-jk
315

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

    
322
* the directory in which you extracted the distribution (for binary distribution)
323
* ``<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>``.
324

    
325
2. Set up Mod JK apache configuration by typing:
326

    
327
::
328

    
329
  sudo cp <metacat_helper_dir>/debian/jk.conf <apache_install_dir>/mods-available
330
  sudo cp <metacat_helper_dir>/debian/workers.properties <apache_install_dir>
331

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

    
334
::
335

    
336
  sudo a2dismod jk
337
  sudo a2enmod jk
338

    
339
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:
340

    
341
::
342

    
343
  sudo cp <metacat_helper_dir>/metacat-site.conf <apache_install_dir>/sites-available
344
  sudo a2ensite metacat-site.conf
345
  
346
5. Disable the default Apache site configuration:
347

    
348
::
349

    
350
  sudo a2dissite 000-default  
351

    
352
6. Restart Apache to bring in changes by typing:
353

    
354
::
355

    
356
  sudo /etc/init.d/apache2 restart
357

    
358

    
359
PostgreSQL Database
360
...................
361
Currently Metacat only supports PostgreSQL_. To install and configure PostgreSQL_:
362

    
363
1. If you are running Ubuntu_/Debian, get PostgreSQL by typing:
364

    
365
  ::
366

    
367
    sudo apt-get install postgresql
368

    
369
  On other systems, install the rpms for postgres.
370

    
371
2. Start the database by running:
372

    
373
  ::
374

    
375
    sudo /etc/init.d/postgresql-8.4 start
376

    
377
3. Change to postgres user: 
378

    
379
  ::
380

    
381
    sudo su - postgres
382

    
383

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

    
386
  ::
387

    
388
    gedit /etc/postgresql/8.4/main/pg_hba.conf
389

    
390

    
391
  Add the following line to the configuration file: 
392

    
393
  ::
394

    
395
    host metacat metacat 127.0.0.1 255.255.255.255 password
396

    
397

    
398
  Save the file and then create the Metacat instance: 
399

    
400
  ::
401

    
402
    createdb metacat
403

    
404

    
405
5. Log in to postgreSQL by typing: 
406

    
407
  ::
408

    
409
    psql metacat
410

    
411

    
412
6. At the psql prompt, create the Metacat user by typing:
413

    
414
  ::
415

    
416
    CREATE USER metacat WITH UNENCRYPTED PASSWORD 'your_password';
417

    
418
  where 'your_password' is whatever password you would like for the Metacat user. 
419

    
420
7. Exit PostgreSQL by typing 
421

    
422
  ::
423

    
424
    \q
425

    
426
8. Restart the PostgreSQL database to bring in changes: 
427

    
428
  ::
429

    
430
    /etc/init.d/postgresql-8.4 restart
431

    
432
9. Log out of the postgres user account by typing: 
433

    
434
  ::
435

    
436
    logout
437

    
438
10. Test the installation and Metacat account by typing: 
439

    
440
  ::
441

    
442
    psql -U metacat -W -h localhost metacat
443

    
444
11. Log out of postgreSQL: 
445

    
446
  ::
447

    
448
    \q
449

    
450

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

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

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

    
467
  sudo apt-get install ant
468

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

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

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

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

    
487
To install a new Metacat servlet:
488

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

    
491
  ::
492

    
493
    sudo mkdir /var/metacat
494

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

    
497
  ::
498

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

    
501

    
502
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:
503

    
504
  ::
505

    
506
    sudo cp <metacat_package_dir>/metacat.war <tomcat_app_dir>
507

    
508

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

    
511
  ::
512

    
513
    sudo /etc/init.d/tomcat7 restart
514

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

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

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

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

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

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

    
537
  ::
538

    
539
    /etc/init.d/tomcat7 stop
540

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

    
543
  ::
544

    
545
    cp <web_app_dir>/metacat <backup_dir>/metacat.<yyyymmdd>
546
    cp <web_app_dir>/metacat.war <backup_dir>/metacat.war.<yyyymmdd>
547

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

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

    
553
  ::
554

    
555
    sudo cp <metacat_package_dir>/metacat.war <tomcat_app_dir>
556

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

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

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

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

    
569
  ::
570

    
571
    /etc/init.d/tomcat7 restart
572

    
573

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

    
577
  ::
578

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

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

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

    
594
To install Metacat from source:
595

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

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

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

    
608
  ::
609

    
610
    sudo ant clean install
611

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

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

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

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

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

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

    
630
.. Note::
631

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

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

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

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

    
665
The format of an LSID is:: 
666

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

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

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

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

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

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

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

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

    
695
  ::
696

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

    
702
   ::
703

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

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

    
710
   ::
711

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

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

    
716
  ::
717

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

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

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

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

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

    
737
  ::
738

    
739
    sudo ant war-lsid
740

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

    
743
  ::
744

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

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

    
750
  ::
751

    
752
    /etc/init.d/tomcat7 restart
753

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

    
758
  ::
759

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

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

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

    
767
  ::
768

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

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

    
775
    ::
776

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

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

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

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

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

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

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

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

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

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

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

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

    
825

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

    
831
* `Java 7`_
832
* `Apache Tomcat`_
833
* PostgreSQL_ Database
834

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

    
841
To download and install Java:
842

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

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

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

    
851
  ::
852

    
853
    System Variable: JAVA_HOME C:\Program Files\Java\jdk1.7.0_79 
854
    (or whichever version you downloaded)
855

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

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

    
865
PostgreSQL Database
866
...................
867
Metacat only can be run with PostgreSQL_. Instructions for installing and 
868
configuring PostgreSQL for use with Metacat are included in this section.
869

    
870
To download and install PostgreSQL:
871

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

    
879
    host metacat metacat 127.0.0.1 255.255.255.255 password
880

    
881
4. Create a super user. At the command line, enter:
882

    
883
  ::
884

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

    
888
5. Log in to PostgreSQL: 
889

    
890
  ::
891

    
892
    psql -U postgres metacat (enter super user password)
893

    
894
6. Create a Metacat user:
895

    
896
  ::
897

    
898
    CREATE USER metacat WITH UNENCRYPTED PASSWORD 'your_password'
899

    
900
7. Exit PostgreSQL: 
901

    
902
  ::
903

    
904
    \q
905

    
906
8. Restart PostgreSQL from the start menu by selecting:
907
  
908
  ::
909

    
910
    run start/All Programs/PostgreSQL 8.3/Stop Server
911
    run start/All Programs/PostgreSQL 8.3/Start Server
912

    
913

    
914
9. Test the installation by logging in as the metacat user: 
915

    
916
  ::
917
  
918
    psql -U metacat -W -h localhost metacat
919

    
920
10. Exit PostgreSQL:
921

    
922
  ::
923

    
924
    \q
925

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

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

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

    
939
To install a new Metacat servlet:
940

    
941
1. Create the Metacat base directory at: 
942

    
943
  ::
944

    
945
    C:/Program Files/metacat
946

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

    
952
    copy <metacat_package_dir>\metacat.war C:\Program Files\tomcat\webapps
953

    
954
3.  Restart Tomcat: 
955

    
956
  ::
957

    
958
    C:\Program Files\tomcat\shutdown.bat
959
    C:\Program Files\tomcat\startup.bat
960

    
961

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

    
965
Upgrade
966
.......
967
To upgrade an existing Metacat installation:
968

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

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

    
976
  ::
977

    
978
    <web_app_dir>/metacat to <backup_dir>/metacat.<yyyymmdd>
979
    <web_app_dir>/metacat.war to <backup_dir>/metacat.war.<yyyymmdd>
980

    
981
  Warning: Do not backup the metacat directory in the <web_app_dir> directory.
982
  Tomcat will try to run the backup copy as a service.
983

    
984
3.  Copy the new Metacat WAR file in to Tomcat applications directory: 
985

    
986
  ::
987

    
988
    copy metacat.war C:\Program Files\tomcat\webapps
989

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

    
997
Congratulations! You are now ready to configure Metacat. Please see Configuring
998
Metacat for more information.