Project

General

Profile

Revision 4716

Added by daigle about 12 years ago

Add source build instructions

View differences:

docs/user/metacat-linux-install.html
43 43

  
44 44
<div class="header1">Table of Contents</div>
45 45
  <div class="toc">
46
    <div class="toc1"><a href="#Intro">Introduction</a></div> 
47
      <div class="toc2"><a href="#DifferentOptions">Different Installation Options</a></div> 
48
      <div class="toc2"><a href="#ThisDoc">Organization Of This Page</a></div>
46 49
    <div class="toc1"><a href="#QuickInstallation">Quick Installation</a></div> 
47 50
      <div class="toc2"><a href="#DownloadMetacatInstall">Download Metacat Package</a></div> 
48 51
      <div class="toc2"><a href="#CreateDirs">Create Metacat Directories</a></div> 
......
69 72
      <div class="toc2"><a href="#AdditionalSoftwareAnt">Ant</a></div>
70 73
      <div class="toc2"><a href="#AdditionalSoftwareTomcat">Tomcat</a></div>
71 74
    <div class="toc1"><a href="#DownloadingMetacat">Download Metacat and Get War File</a></div>
72
      <div class="toc2"><a href="#DownloadMetacatBinary">Download Metacat Binary and Create War File</a></div>
73
      <div class="toc2"><a href="#DownloadMetacatSource">Download Metacat Source and Create War File</a></div>
75
      <div class="toc2"><a href="#DownloadMetacatBinary">Download Metacat Binary and Get War File</a></div>
76
      <div class="toc2"><a href="#DownloadMetacatSourceDist">Download Metacat Source Distribution</a></div>
77
      <div class="toc2"><a href="#DownloadMetacatSourceSVN">Download Metacat Source From SVN</a></div>
78
      <div class="toc2"><a href="#CreateSourceWar">Create War From Source</a></div>
74 79
    <div class="toc1"><a href="#InstallingMetacat">Installing Metacat</a></div>
75 80
      <div class="toc2"><a href="#CreateMetacatDirs">Create Metacat Directories</a></div>
76
      <div class="toc2"><a href="#InstallMetacatWar">Install Metacat War</a></div>
81
      <div class="toc2"><a href="#InstallMetacatWar">Install Metacat Binary (War)</a></div>
82
      <div class="toc2"><a href="#InstallMetacatSource">Install Metacat From Source</a></div>
77 83
    <div class="toc1"><a href="#UpgradingMetacat">Upgrading Existing Metacat</a></div>
78 84
      <div class="toc2"><a href="#UpgradeStopMetacat">Stop the Running Metacat</a></div>
79 85
      <div class="toc2"><a href="#UpgradeDownloadMetacat">Download Latest Metacat Application</a></div>
80
      <div class="toc2"><a href="#UpgradeMetacatWar">Upgrade Metacat War</a></div>
86
      <div class="toc2"><a href="#UpgradeMetacatWar">Upgrade Metacat Binary (War)</a></div>
87
      <div class="toc2"><a href="#UpgradeMetacatSource">Upgrade Metacat From Source</a></div>
81 88
   <div class="toc1"><a href="#RestartTomcat">Restart Tomcat</a></div>
82 89
      <div class="toc2"><a href="#UpgradeTroubleshooting">Troubleshooting</a></div>
83 90
      <div class="toc2"><a href="#UpgradeConfigureMetacat">Configure Metacat</a></div>       
84 91
    <div class="toc1"><a href="#Registry">Web Based Registry</a></div>
85 92
  </div> 
86 93

  
94
<a name="Intro"></a><div class="header1">Introduction</div>
95
  <a name="DifferentOptions"></a><div class="header2">Different Installation Options</div>
96
  <p>There are many different options to consider when installing Metacat.  Some of these
97
  are: </p>
98
  <ul>
99
  <li>Operating System - Metacat is a Java servlet application.  As such, you can run
100
  it on many different operating system.  It has been tested against Linux, MacOS and 
101
  MicroSoft Windows.  The optimal installation is on Ubuntu Linux.</li>
102
  <li>Tomcat standalone or in conjunction with Apache web server - The Tomcat server 
103
  can be run alone as a web server.  However, it is not as robust a server,
104
  and does't allow for the same level of customization as Apache.  The recommended 
105
  configuration is Tomcat running in conjunction with Apache</li>
106
  <li>Binary versus source installation - There are three ways to get and install 
107
  the Metacat installation.
108
    <ul>
109
  	<li>Binary Distribution Installation - download the Metacat war distribution and install it 
110
  	into the web applications directory</li>
111
  	<li>Source Distribution Installation - download the source code distribution, build it and 
112
  	install the resultant war file into the web application directory.</li>
113
  	<li>Source Checkout Installation - check the source code out from the Subversion 
114
  	repository, build it and install the resultant war file into the web application directory.</li>
115
  	</ul>
116
  The recommended installation procedure is binary distribution installation.</li>
117
  </ul>
118
  
119
  <p>The administrator will need to decide which combinations of these option are best
120
  suited to their system</p>
121
  
122
  <a name="ThisDoc"></a><div class="header2">Organization Of This Page</div>
123
  <p> The first couple of sections on this page deal with quick command line 
124
  instructions for installing and upgrading Metacat in the optimal environment, which
125
  is a binary distribution installation with Apache on Ubuntu Linux.</p>
126
  
127
  <p>The remainder of the page deals with more detailed instructions including other 
128
  installation options.</p>
129

  
87 130
<a name="QuickInstallation"></a><div class="header1">Quick Installation</div>
88 131
  <p>These are the installation instructions for a system that has Ubuntu 8.04 installed
89 132
  and has never had Metacat installed on it:</p>
......
197 240
	</ul>
198 241
		
199 242
  <a name="ConfigureMetacatInstall"></a><div class="header2">Configure Metacat</div> 
200
    <p>Refer to the documentation on <a href="./metacatconfigure.html">Metacat Confguration</a>
243
    <p>Refer to the documentation on <a href="./metacat-configure.html">Metacat Confguration</a>
201 244
    to complete your installation of Metacat.</p>
202 245
    
203 246
  <a name="QuickUpdate"></a><div class="header1">Quick Update</div>
......
244 287
	</ul>
245 288
		
246 289
  <a name="ConfigureMetacatUpdate"></a><div class="header2">Configure Metacat</div> 
247
    <p>Refer to the documentation on <a href="./metacatconfigure.html">Metacat Confguration</a>
290
    <p>Refer to the documentation on <a href="./metacat-configure.html">Metacat Confguration</a>
248 291
    to complete your installation of Metacat.</p>
249 292

  
250 293
<a name="PreInstallation"></a><div class="header1">Pre-Installation</div>
......
383 426
  <p>Since downloading the binary distribution is the easiest and most common install, it
384 427
  will be discussed here in detail.  Links to source download/build instructions are also
385 428
  included in case you would like to go that route.</p>
386
  <a name="DownloadMetacatBinary"></a><div class="header2">Download Metacat Binary and Create War File</div>
387 429

  
430
<a name="DownloadMetacatBinary"></a><div class="header2">Download Metacat Binary and Get War File</div>
388 431
    <p>Browse to the 
389 432
      <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
390 433
      In the Metacat section, for Linux based systems, select the link that looks like:</p>
......
399 442
    were extracted will be refered to as the the &lt;metacat_package_dir&gt; for the remainder 
400 443
    of this documentation.
401 444
    
402
  <a name="DownloadMetacatSource"></a><div class="header2">Download Metacat Source and Create War File</div>
445
<a name="DownloadMetacatSourceDist"></a><div class="header2">Download Metacat Source Distribution</div>	
446
  <p>To get the Metacat source distribution, browse to the 
447
      <a href="http://knb.ecoinformatics.org/software/download.html">KNB Software Download Page</a>.
448
      In the Metacat section, for Linux based systems, select the link that looks like:</p>
449
	  <div class="code">metacat-src-X.X.X.tar.gz</div>
450
	  <p>for Windows systems, select the link that looks like:</p>
451
	  <div class="code">metacat-src-X.X.X.zip</div>
452
    <p>where X.X.X is the latest version of Metacat.  Choose to save the file locally in the directory 
453
    where your source should live.</p>
454
    <p>Extract the Metacat package files on Linux systems by typing:
455
      <div class="code">tar -xvzf metacat-src-X.X.X.tar.gz</div>
456
    <p>or, on Windows, use your system unzip utility to extract the zip file.</p>
457
    <p>Rename the metacat-X.X.X directory to metacat.</p>
458
    <p>Note that you do not need to create the war file directly with a source installation
459
    since the Ant build file has an "install" target that will build and deploy the war
460
    for you.  See the <a href="#InstallingMetacat">Installing Metacat</a> for instructions.</p>
403 461

  
404
    <p>If you would like to download the Metacat source distribution or checkout the source
405
    code from SVN, go to the  
406
      <a href="./metacat-source-build.html">Download and Build Metacat From Source</a> page.
462
<a name="DownloadMetacatSourceSVN"></a><div class="header2">Download Metacat Source From SVN</div>
463
  <p>If you are checking out Metacat code from the SVN repository, you will need both 
464
  Subversion (SVN) and CVS clients installed and configured on your system.  Both are needed
465
  because, while Metacat has been migrated to SVN, some of its supporting libraries (eml, 
466
  utilities and seek) have not yet been migrated.  Eventually, SVN will be the only versioning 
467
  client you will need.  You will need to make sure you have the appropriate accounts on these 
468
  systems.  You won't have to worry about SVN or CVS if you are installing from a Metacat
469
  source distribution.  These have all the required dependencies built in.</p>
470
  
471
  <p>If you have not already installed Subversion and you are running Ubuntu/Debian, you can 
472
  get it by typing:</p>
473
    <div class="code">sudo apt-get install subversion</div>
474
    
475
  <p>Otherwise, you can get if from <a href="http://subversion.tigris.org">The Subversion homepage</a></p>
476
  
477
  <p>If you have not already installed CVS and you are running Ubuntu/Debian, you can 
478
  get it by typing:</p>
479
    <div class="code">sudo apt-get install cvs</div>
480
    
481
  <p>Otherwise, you can get it from <a href="http://ximbiot.com/cvs/wiki/">The Ximbiot CVS homepage</a></p>
482
  
483
  <p>To check out the code from SVN, go to the directory where you would like the code 
484
    to live and type:</p>
485
      <div class="code">svn co https://code.ecoinformatics.org/code/metacat/tags/METACAT_&lt;rev&gt; metacat</div>
486
    <p>Where &lt;rev&gt; is the version of the code you want to check out (like 1_9). </p>
487
    
488
    <p>If you are trying to check out the head, type:</p>
489
      <div class="code">svn co https://code.ecoinformatics.org/code/metacat/trunk metacat</div>
490
      
491
    <p>You should see a list of files as they check out.</p>
492
    
493
    <p>Note that you do not need to create the war file directly with a source installation
494
    since the Ant build file has an "install" target that will build and deploy the war
495
    for you.  See the <a href="#InstallingMetacat">Installing Metacat</a> for instructions.</p>
407 496

  
497

  
408 498
<a name="InstallingMetacat"></a><div class="header1">Installing Metacat</div>
409 499
  <p>This section is only for a new installation. If you are upgrading an existing Metacat, please skip
410 500
  this section and go to the next one - <a href="#UpgradingMetacat">Upgrading Existing Metacat</a></p>
......
421 511
    upgrade. Create the metacat utility base directory 
422 512
    by typing:</p>
423 513
      <div class="code">sudo mkdir <metacat_base_dir></div>
424
    <p>(Typically <metacat_base_dir> is '/var/metacat'.)  Remeber the directory you 
514
    <p>(Typically <metacat_base_dir> is '/var/metacat'.)  Remember the directory you 
425 515
    choose, since you will be asked to configure Metacat to point to it after startup.</p>
426 516
    
427 517
    <p>Change the ownership of the directory by typing:</p>   
......
429 519
    <p>where &lt;tomcat_user&gt; is the user that will start Tomcat.  If you are 
430 520
	starting Tomcat as the root user, you do not need to run the chown command.</p>
431 521
	
432
  <a name="InstallMetacatWar"></a><div class="header2">Install Metacat War</div> 
522
  <a name="InstallMetacatWar"></a><div class="header2">Install Metacat Binary (War)</div> 
433 523
    <p>Copy the war file to Tomcat:</p>
434 524
	  <div class="code">sudo cp knb.war &lt;tomcat_app_dir&gt;</div>
525
  
526
  <a name="InstallMetacatSource"></a><div class="header2">Install Metacat From Source</div> 
527
    <p>You will need Apache Ant to do the build.  If you have not already 
528
    installed Ant and you are running Ubuntu/Debian, you can get it by typing:</p>
529
      <div class="code">sudo apt-get install ant</div>
530
  
531
    <p>Otherwise, you can get ant from
532
    <a href="http://ant.apache.org/">The Apache Ant homepage</a></p>
533

  
534
    <p>You should now have the Metacat source in a directory named "metacat" in your
535
    code directory (We will refer to the metacat source directory as &lt;metacat_src_dir&gt;.
536
       
537
    <p>To prepare for the build, edit the file at:</p>
538
      <div class="code">&lt;metacat_src_dir&gt;/build.properties</div> 
539
    <p>Make sure that the "build.tomcat.dir" property is set to your tomcat installation
540
    directory.  For instance:</p>
541
      <div class="code">build.tomcat.dir=/usr/local/tomcat</div>
542
    <p>Metacat will use some of the native Tomcat libraries during the build.</p>
543
    
544
    <p>Make sure that the "app.deploy.dir" property is set to your application deployment
545
    directory.  For instance:</p>
546
      <div class="code">app.deploy.dir=/usr/local/tomcat/webapps</div>
547
    
548
    <p>If your cvs user is something other than the user your are logged in as, you
549
    will need to change the ${env.USER} part of the cvsroot property to be your cvs 
550
    user.  For instance:</p>
551
      <div class="code">cvsroot=:ext:cvs-user@cvs.ecoinformatics.org:/cvs</div>
552
    <p> where your cvs user name is "cvs-user"</p> 
553
    
554
    <p>In the &lt;metacat_src_dir&gt;, run: </p>
555
      <div class="code">ant clean install</div>
556
      
557
    <p>You will see the individual modules get built.  You will be prompted
558
    for your cvs password several times.  You should see a "BUILD SUCCESSFUL"
559
    message at the end.</p>
560
    
561
    <p>You should see a new file named knb.war in your application deployment directory.</div>
435 562
	  
436 563
  <a name="ApacheConfig"></a><div class="header2">Configure Apache</div> 
437 564
    <p>You have the option of running Tomcat stand-alone or with with the Apache web
......
473 600
    were extracted will be refered to as the the &lt;metacat_package_dir&gt; for the remainder 
474 601
    of this documentation.</p>
475 602
 
476
   <a name="UpgradeMetacatWar"></a><div class="header2">Upgrade Metacat War</div> 
603
   <a name="UpgradeMetacatWar"></a><div class="header2">Upgrade Metacat Binary (War)</div> 
477 604
    <p>Tomcat will look for it's application files (war files) in a configured directory.  
478 605
    This is typically the &lt;tomcat_home&gt;/webapps directory, but your instance of Tomcat may 
479 606
    be configured to look in a different directory.  We will refer to your Tomcat application directory 
......
492 619
	  <div class="code">sudo /etc/init.d/tomcat5.5 restart</div>
493 620
	<p>Tomcat will expand your war file into a new application directory at startup time.</p>
494 621
 
622
  <a name="UpgradeMetacatSource"></a><div class="header2">Upgrade Metacat From Source</div>
623
    <p>The steps to upgrade Metacat from source are the same as installing from source.  See
624
    the <a href="#InstallMetacatSource">Install Metacat From Source</a> section above.</p>
625
 
495 626
  <a name="RestartTomcat"></a><div class="header1">Restart Tomcat</div>
496 627
    <p>Once you have successfully installed Metacat, there is one more step.  Tomcat
497 628
    (and Apache if you have Tomcat integrated with it) must be restarted.  To do
......
530 661
  
531 662
  <a name="UpgradeConfigureMetacat"></a><div class="header2">Configure Metacat</div>
532 663
  <p>Once you see the Metacat configuration screen, you can follow the instructions in the 
533
  <a href="./metacatconfigure.html"> Configuring Metacat Section</a> 
664
  <a href="./metacat-configure.html"> Configuring Metacat Section</a> 
534 665
  to complete the internal configuration of Metacat.</p>
535 666

  
536 667
<a name="Registry"></a><div class="header1">Web Based Registry</div>

Also available in: Unified diff