Project

General

Profile

« Previous | Next » 

Revision 4715

Added by daigle almost 16 years ago

change metacatconfigure.html to metacat-configure.html

View differences:

docs/user/metacatconfigure.html
1
<!-- 
2
  *   '$RCSfile$'
3
  *     Purpose: web page describing the installation of Metacat
4
  *   Copyright: 2008 Regents of the University of California and the
5
  *               National Center for Ecological Analysis and Synthesis
6
  *     Authors: Chad Berkley
7
  *
8
  *    '$Author$'
9
  *    '$Date$'
10
  *    '$Revision$'
11
  *
12
  *
13
  -->
14
  
15
<!DOCTYPE html PUBLIC "-//W3C//DTD html 4.0//EN">
16
<html>
17

  
18
<head>
19
  <title>Metacat Configuration Instructions</title>
20
  <link rel="stylesheet" type="text/css" href="./common.css">
21
  <link rel="stylesheet" type="text/css" href="./default.css">
22
</head>
23

  
24
<body>
25

  
26
<table class="tabledefault" width="100%">
27
<tr><td rowspan="2"><img src="./images/KNBLogo.gif"></td>
28
<td colspan="7">
29
<div class="title">Metacat Configuration</div>
30
</td>
31
</tr>
32
<tr>
33
  <td><a href="/" class="toollink"> KNB Home </a></td>
34
  <td><a href="/data.html" class="toollink"> Data </a></td>
35
  <td><a href="/people.html" class="toollink"> People </a></td>
36
  <td><a href="/informatics" class="toollink"> Informatics </a></td>
37
  <td><a href="/biodiversity" class="toollink"> Biocomplexity </a></td>
38
  <td><a href="/education" class="toollink"> Education </a></td>
39
  <td><a href="/software" class="toollink"> Software </a></td>
40
</tr>
41
</table>
42
<hr>
43

  
44
<div class="header1">Table of Contents</div>
45
<div class="toc">
46
  <div class="toc1"><a href="#Overview">Overview</a></div>
47
      <div class="toc2"><a href="#MetacatConfiguration">Metacat Configuration</a></div> 
48
      <div class="toc2"><a href="#ConfigurationRules">Configuration Rules</a></div>
49
  <div class="toc1"><a href="#authConfig">Authentication Configuration</a></div>
50
      <div class="toc2"><a href="#AuthOverview">Authentication Overview</a></div> 
51
      <div class="toc2"><a href="#GetToAuthConfig">Getting to the Authentication Configuration</a></div> 
52
      <div class="toc2"><a href="#ConfigAuthNoAuth">Changing Authentication Configuration Without Authentication</a></div>
53
  <div class="toc1"><a href="#AdminLogin">Admin Log In</a></div>
54
    <div class="toc2"><a href="#AdminLoginOverview">Admin Log In</a></div>
55
    <div class="toc2"><a href="#LoggingIn">Logging In</a></div>
56
  <div class="toc1"><a href="#MainConfig">Main Configuration Page</a></div>
57
    <div class="toc2"><a href="#MainConfigOverview">Main Configuration Overview</a></div>
58
  <div class="toc1"><a href="#GlobalConfig">Global Properties Configuration</a></div>
59
    <div class="toc2"><a href="#GlobalConfigOverview">Global Properties Overview</a></div>
60
    <div class="toc2"><a href="#AutoDetection">Property Auto-Detection</a></div>
61
    <div class="toc2"><a href="#GlobalConfigBackup">Global Property Backup</a></div>  
62
  <div class="toc1"><a href="#SkinsConfig">Skins Configuration</a></div>  
63
    <div class="toc2"><a href="#SkinsConfigOverview">Skins Overview</a></div>
64
    <div class="toc2"><a href="#ChoosingDefaultSkin">Choosing a Default Skin</a></div>
65
    <div class="toc2"><a href="#ConfigOnlineRegistry">Configuring Online Registry</a></div>
66
  <div class="toc1"><a href="#DatabaseConfig">Database Configuration</a></div>
67
    <div class="toc2"><a href="#DatabaseConfigOverview">Database Configuration Overview</a></div>
68
    <div class="toc2"><a href="#DatabaseNewInstall">New Database Installation</a></div>
69
    <div class="toc2"><a href="#DatabaseUpgrade">Database Upgrade</a></div>
70
  <div class="toc1"><a href="#GeoserverConfig">Geoserver Configuration</a></div>
71
    <div class="toc2"><a href="#GeoserverUpdatePassword">Geoserver Password Update</a></div>
72
    <div class="toc2"><a href="#GeoserverManualUpdate">Geoserver Manual Update</a></div>  
73
  <div class="toc1"><a href="#CompleteConfig">Complete the Metacat Configuration</a></div>
74
</div> 
75

  
76
<a name="Overview"></a><div class="header1">Overview</div>
77
<a name="MetacatConfiguration"></a><div class="header2">Metacat Configuration</div>
78
  <p>As of version 1.9.0, Metacat configuration is done internally by the application.  When
79
  Metacat (Tomcat) is started, it will check to see if it is configured.  If not, you will be 
80
  automatically sent to the configuration pages. </p>
81
  
82
  <p>If the installation is new, or the previous version is before 1.9.0, you will 
83
  need to pay close attention to the configuration values.  If you have upgraded 
84
  Metacat, and the previous version is 1.9.0 or later, Metacat will pull existing 
85
  values from a backup location.  You should still verify that the values are
86
  correct.</p>
87
  
88
  <p>Get to Metacat on your server by entering into the browser:</p>
89
  <div class="code">http://&lt;your_context_url&gt;</div>
90
  <p>Where &lt;your_context_url&gt is the url where Metacat will be served followed
91
  by the name of the war file(application context) that you installed.  For instance, 
92
  the KNB production Metacat url is:</p>
93
  <div class="code">http://knb.ecoinformatics.org/knb</div>
94
  
95
  <p>You can always go to the configuration screen from within Metacat by typing:
96
  <div class="code">&lt;your_context_url&gt;/admin</div>
97
  
98
<a name="ConfigurationRules"></a><div class="header2">Configuration Rules</div>   
99
  <p>The system will follow these rules in order to determine the order
100
  that the configuration will occur:</p>
101
  
102
  <ul>
103
    <li>
104
      Is Authentication Configured? If not, show 
105
      <a HREF="metacatconfigure.html#auth-config">Authentication Configuration Section</a>.  
106
      You will need to have authorizaiton configured in order to define administrative accounts
107
      and authenticate as one of these users.
108
    </li>
109
    <li>
110
      Are you logged in as an administrative user?  If not, show 
111
      <a HREF="metacatconfigure.html#admin-login">Administrator Login Page</a>.
112
      You can only configure Metacat as an administrator.
113
    </li>
114
    <li>
115
      Are main properties, skins or database unconfigured?  If so, show 
116
      <a HREF="metacatconfigure.html#main-config">Main Configuration Page</a>
117
      Note that you will not be able to select the database configuration utility 
118
      until main properties have been configured.
119
    </li>  
120
    <li>
121
      Are all sections configured?  If so, show 
122
      <a HREF="metacatconfigure.html#main-config">Main Configuration Page</a> which
123
      include instructions for going to Metacat server (or restarting Metacat if you 
124
      are reconfiguring a running server).
125
    </li> 
126
  </ul>
127
  
128
  <p> See the following sections for descriptions of how each of these work.  For more
129
  information on each field, click on the blue question mark icon to the right.</p>
130

  
131
<a name="AuthConfig"></a><div class="header1">Authentication Configuration</div>
132
<a name="AuthOverview"></a><div class="header2">Authentication Overview</div>
133
  <p>Metacat uses LDAP as it's primary authentication mechanism, but you can define
134
  your own mechanism by creating a java class that implements 
135
  AuthInterface. The configuration values needed are Authentication Class, Authentication URL, 
136
  Authentication Secure URL and Metacat Administrators.  You need 
137
  to verify that the the Authentication URL and Authentication Secure URL are correct (fig 1).  
138
  <span class="emphasis">You need to make sure that your user 
139
  account is entered into the Metacat Administrators field.  You will not be allowed
140
  to continue with configuration if this is missing.</span>
141

  
142
  <img class="screenshot" src="./images/auth-config.png"/>
143
  <div class="fig-text"> fig 1 </div>
144

  
145
<a name="GetToAdminConfig"></a><div class="header2">Getting to the Authentication Configuration</div>
146
  <p>You will automatically be sent to the Authentication Configuration page if this is a new
147
  installation or upgrade.</p>
148
  
149
  <p>You can also get to the Administrative configuration from a running Metacat by typing:</p>
150
  <div class="code">&lt;your_context_url&gt;/admin</div>
151
  <p>You will be required to log in as an administrator and restart Metacat once you
152
  make changes.</p>
153
  
154
  <a name="ConfigAuthNoAuth"></a><div class="header2">Changing Authentication Configuration Without Authentication</div>
155
  <p>There is one exception to the log in rule.  That is when you need to change or add 
156
  authentication information, but you can't authenticate using the existing setup.  For example:</p>
157
  
158
  <ul>
159
    <li>The existing Metacat administrator is no longer available</li>
160
    <li>You forgot the administrator password.</li>
161
    <li>The configured authentication urls are unavailable and you need to configure new ones.</li>  
162
  </ul>
163
  
164
  <p>In this case, you will need to edit the Metacat configuration file by hand and
165
  make the changes.  This insures that only a person who has access to the Metacat
166
  server and the configuration files on that server will be able to change the
167
  administrator accounts</p>
168

  
169
  <p>Stop Tomcat and edit the Metacat properties file at:</p>
170
  <div class="code">&lt;webapp_dir&gt;/&lt;context_dir&gt;/WEB-INF/metacat.properties</div>
171
  <p>where &lt;webapp_dir&gt; is the place that Tomcat looks for applications and 
172
  &lt;context_dir&gt; is the name of the Metacat application (usually knb).  Change the 
173
  following properties appropriately:</p>
174
  
175
  <ul>
176
    <li>auth.administrators - a colon separated list of administrators</li>
177
    <li>auth.url - the authenication server url</li>
178
    <li>auth.surl - the authentication secure server url</li>  
179
  </ul>
180
  
181
  <p>Save the metacat.properties file and start Tomcat.</p>
182
  
183
<a name="AdminLogin"></a><div class="header1">Admin Log In</div>
184
<a name="AdminLoginOverview"></a><div class="header2">Admin Log In Overview</div>
185
  <p>Once authentication has been configured, you will be required to login as an 
186
  administrative user if you haven't already.  You will be taken to 
187
  the administrator login screen (fig 2).  You can also get to the login
188
  screen by choosing the "log in as different user" link at the bottom of
189
  any configuration screen.</p>
190
  
191
  <img class="screenshot" src="./images/admin-login.png"/>
192
  <div class="fig-text"> fig 2 </div>
193

  
194
<a name="LoggingIn"></a><div class="header2">Logging In</div>
195
<p>You need to log in with an account that was configured as an administrative
196
user in the authentication configuration section.  If you did not set up the correct user 
197
there, you will need to go through the 
198
<a href="#ConfigAuthNoAuth">Changing Authentication Configuration Without Authentication</a>
199
instructions to set up the user.</p>
200

  
201
<p>Enter your user name.  This is one of the Metacat administrators that you 
202
entered in authenticationuthentication configuration.  Enter your password and
203
hit the "Login" button.  You should successfully log in.</p>
204

  
205
<a name="MainConfig"></a><div class="header1">Main Configuration Page</div>
206
<a name="MainConfigOverview"></a><div class="header2">Main Configuration Overview</div>
207
  <p>The main configuration screen acts as a gateway into individual configuration
208
  sections (fig 3).  You should see that the authentication is already configured.</p>  
209
  
210
  <p>Each section is listed with a status to the left which can be one of:</p>
211
  <ul>
212
    <li><font color="red">[unconfigured]</font> - the section has yet to be configured</li>
213
    <li><font color="green">[configured]</font> - the section has been configured</li>
214
    <li>
215
      <font color="green">[bypassed]</font> - this is currently only used for Geoserver 
216
      configuration.  The administrator can choose not to configure the Geoserver user/password.
217
      In essence, the bypass status acts like the configured status.
218
    </li>  
219
  </ul>
220
  
221
  <p>To the right of each section is an option which can be one of:
222
  <ul>
223
    <li>Configure Now - click on this link to configure that section</li>
224
    <li>Reconfigure Now - the section was already configured, but you can choose to reconfigure it.</li>
225
    <li>
226
      Configure Global Properties First - this section has a dependency on the global
227
      properties section.  Once global properties is configured, the option to configure
228
      this section should become available.
229
    </li>  
230
    <li>Version: X.X.X - this is used for the Database Installation/Upgrade section.  The system
231
      detects the database schema version.  If that version is the same as the application version,
232
      that version will be displayed (i.e. 1.9.0) and no further database configuration is
233
      required.
234
    </li>
235
  </ul>
236
  
237
  <p>All sections must be in a configured or bypassed state in order to run Metacat.</p>
238
  
239
  <img class="screenshot" src="./images/main-config.png"/>
240
  <div class="fig-text"> fig 3 </div>
241
  
242
<a name="GlobalConfig"></a><div class="header1">Global Properties Configuration</div>
243
<a name="GlobalConfigOverview"></a><div class="header2">Global Properties Overview</div>
244
  <p>Metacat global properties are the bulk of the core properties needed to run Metacat 
245
  (fig 4).  For detailed instructions on setting these properties, refer to the blue 
246
  question mark icon to the right of each property.  Be sure that each of these are set
247
  appropriately.</p>
248
  
249
  <img class="screenshot" src="./images/global-config.png"/>
250
  <div class="fig-text"> fig 4 </div>
251

  
252
<a name="AutoDetection"></a><div class="header2">Property Auto-Detection</div> 
253
   <p>The first time you install Metacat, the system will attempt to auto-detect
254
   some values.  These are:</p>
255
   
256
  <ul>
257
    <li>Metacat Context - Name of the context under which Metacat will run. This is the name 
258
        of the Metacat war file that was deployed (minus the .war extension).</li>
259
    <li>Server Name - The DNS name of the server where Metacat will be available, not including
260
        port numbers or the http:// header.</li>
261
    <li>HTTP Port - The non-secure port where Metacat will be available. </li>  
262
    <li>HTTP SSL Port - The secure port where Metacat will be available.</li>
263
    <li>Deploy Location - The directory where the application is deployed.</li>
264
  </ul>
265
  
266
  <p>You should be extra careful that these were detected correctly.</p>
267
  
268
<a name="GlobalConfigBackup"></a><div class="header2">Global Property Backup</div>
269
  <p>When you save global properties, they are saved in a backup file that is 
270
  located in the following directory on linux:</p>
271
  <div class="code">/var/metacat/.metacat</div>
272
  and on windows:
273
  <div class="code">C:\Program Files\metacat\.metacat</div>
274
  <p>When you update Metacat, the system will look for these backed up properties
275
  so you won't have to re-enter all the information from previous installs.</p>
276
  
277
<a name="SkinsConfig"></a><div class="header1">Skins Configuration</div>
278
<a name="SkinsConfigOverview"></a><div class="header2">Skins Overview</div>
279
  <p>Metacat allows for a customized look and feel for the Metacat front end and for the 
280
  online data registry services.  There are two major functions provided by the
281
  skins configuration.  The first is to choose which skin will be the default.  The
282
  second will be to configure the look and feel of the online data registry pages.  For
283
  more information on the online data registry option, refer to the 
284
  <a href="./registry_installation.html">Metacat Registry Installation</a> documentation.</p>
285
  
286
  <p>Note that if you are not using the online registry, and you don't have a custom skin,
287
  you can just save the default skins configuration and move on to the next configuration
288
  section.</p>
289
  
290
<a name="ChoosingDefaultSkin"></a><div class="header2">Choosing a Default Skin</div> 
291
  <p>There are several skins available to choose from in Metacat (fig 5).  If you have a 
292
  skin that has been developed specifically for your instance of Metacat, you should
293
  select the checkbox next to that skin.  When you do, the form will open up with 
294
  several options for that skin (fig 6).  choose the 'Make "skin_name" default" radio selection.
295
  You should see "(default)" appear next to that skin name.  Save the configuration
296
  and that skin will be the one that appears when users visit your Metacat site.  Note
297
  that if you do not have a custom skin, you should leave your skin as the "default" skin.</p>
298
  
299
  <img class="screenshot" src="./images/skins-config.png"/>
300
  <div class="fig-text"> fig 5 </div>  
301

  
302
<a name="ConfigOnlineRegistry"></a><div class="header2">Configuring Online Registry</div> 
303
  <p>The online registry code provides a web interface for entering data into Metacat.  The
304
  screens are somewhat configurable as far as which fields show up and which are required.
305
  You should select each for which you want to activate the registry and then select the
306
  appropriate fields for that skin.</p> 
307
   
308
  <img class="screenshot" src="./images/skins-config-2.png"/>
309
  <div class="fig-text"> fig 6 </div>  
310
  
311
<a name="DatabaseConfig"></a><div class="header1">Database Configuration</div>
312
<a name="DatabaseConfigOverview"></a><div class="header2">Database Configuration Overview</div>
313
  <p>Metacat will detect the schema version of your database, and upgrade it if necessary.  Once the
314
  global Metacat properties have been configured, the Database Installation/Upgrade link 
315
  will become active on the main Metacat configuration page (see fig 3).</p>
316

  
317
<a name="DatabaseNewInstall"></a><div class="header2">New Database Installation</div>
318
  <p>If this is a installation of Metacat, the database install/upgrade utility will
319
  inform you of this (fig 7).  It will list the sql scripts that will get run in order
320
  to create a database schema for the version of Metacat that you are installing.  If
321
  there is any question as to whether the database is new, you should choose to cancel.
322
  When you choose to continue, the server will run the scripts you saw earlier.</p>
323
  <img class="screenshot" src="./images/database-config.png"/>
324
  <div class="fig-text"> fig 7 </div> 
325
 
326
<a name="DatabaseUpgrade"></a><div class="header2">Database Upgrade</div> 
327
  <p>If this is an upgrade of Metacat, the database install/upgrade utility will
328
  inform you of the current version of the database (fig 7).  It will list the sql scripts 
329
  that will get run in order to update the database schema to the upgraded version of 
330
  Metacat.  If there is any question as to whether the detected database schema version is 
331
  correct, you should choose to cancel. When you choose to continue, the server will run 
332
  the scripts you saw earlier.</p>
333
  <img class="screenshot" src="./images/database-config-2.png"/>
334
  <div class="fig-text"> fig 8 </div> 
335
 
336
<a name="GeoserverConfig"></a><div class="header1">Geoserver Configuration</div>
337
<a name="GeoserverOverview"></a><div class="header2">Geoserver Configuration Overview</div> 
338
  <p>Metacat comes bundled with a Web Mapping Service called Geoserver which 
339
  converts spatial data into web-deliverable map images.  For more information, see the
340
  <a href="./spatial_option.html">Metacat Spatial Option documentation</a>.  Geoserver 
341
  installs with a default admin username and password.  You should change these so that
342
  only local administrators can make changes to Geoserver.</p>
343
<a name="GeoserverUpdatePassword"></a><div class="header2">Geoserver Password Update</div>
344
  <p>When you choose the Geoserver Configuration link on the main configuratio page, you
345
  will go to a page that will prompt you for a user name and password (fig 9).  When you 
346
  enter a user name and password, the metacat server will contact the embedded Geoserver
347
  server and change the login credentails.</p>
348
  <p>You also have the option of choosing "bypass".  This will leave Geoserver configured
349
  with the default user name and password.  The main configuration screen will show the 
350
  bypassed status.  The system will interpret the bypassed status the same as the configured
351
  status.</p>
352
  <img class="screenshot" src="./images/geoserver-config.png"/>
353
  <div class="fig-text"> fig 9 </div> 
354
<a name="GeoserverManualUpdate"></a><div class="header2">Geoserver Manual Update</div>
355
  <p>You also have the option of changeing the Geoserver username and password by logging
356
  in directly to the Geoserver.  For more information on changing the credentials directly,
357
  refer to the <a href="./geoserver-manual-configure.html">Geoserver Password Change documentation</a>.
358
  Note that once you change the credentails manually, you will not be able to use the 
359
  Metacat admin tool to change it again (until a new Metacat Upgrade or installation).
360
<a name="CompleteConfig"></a><div class="header1">Complete the Metacat Configuration</div>  
361
  At this point, all the sections of the main configuration should be in a configured or
362
  bypassed state (fig 10).  If you are configuring because of a Metacat install or upgrade,
363
  you will have the option to click on the "go to metacat" link and you should get taken
364
  directly to the running version of Metacat.  Note that this may take some time depending
365
  on the amount of data in your database, since Metacat goes through an indexing process
366
  at start-up time.</p>
367
  
368
  <p>If you are reconfiguring an already running version of Metacat, you will not have the
369
  option to go directly back to Metacat.  You will need to restart the server (Tomcat).</p>
370
  <img class="screenshot" src="./images/main-config-2.png"/>
371
  <div class="fig-text"> fig 10 </div> 
372 0

  
docs/dev/building-metacat.html
65 65
  <li>build.tomcat.dir - Metacat will look for some HttpServlet libraries in the local
66 66
  Tomcat directories.  Make sure this value is set to your local Tomcat installation 
67 67
  directory.</li>
68
  <li>dev.deploy.dir - the automated development build (dev-install) will deploy your
68
  <li>app.deploy.dir - the automated installation build (install) will deploy your
69 69
  war file for you and clean up old application directories.  Make sure this is set
70 70
  to the directory where Tomcat looks for its applications.</li>
71 71
  <li>cvsroot - if your cvs user is different than the user you are using to build metacat, 
......
113 113
  </ul>
114 114
  
115 115
  <a name="AutomatedBuild"></a><div class="header1">Automated Build</div>
116
  <p>There is an ant target called "dev-install" that was created specifically for
117
  local develoment building and deploying.  What it does is:
116
  <p>The ant "install" target controls deploying Metacat locally.  This can be 
117
  used for source distributions or code that was checked out of the repository.
118
  What is does is:</p>
118 119
  <ul>
119 120
  <li>Builds the Metacat project, resulting in a war file.</li>
120
  <li>Moves the war file to the dev.deploy.dir that you set in build.properties</li>
121
  <li>Removes the existing application directory from the dev.deploy.dir.</li>
121
  <li>Moves the war file to the app.deploy.dir that you set in build.properties</li>
122
  <li>Removes the existing application directory from the app.deploy.dir.</li>
122 123
  </ul>
123 124
  Typical usage would be something like:</p>
124
  <div class="code">ant fullclean dev-install</div>
125
  <div class="code">ant fullclean install</div>
125 126
  
126 127
  <a name="ManualBuild"></a><div class="header1">Manual Build</div>  
127 128
  <p>You can also build the Metacat war file and deploy manually.  To build and create the 
docs/user/properties.html
34 34
  </p>  
35 35
   
36 36
  <p> 
37
     The most dynamic properties are modified using the internal <a href="./metacatconfigure.html">Metacat configuration utility </a>.
37
     The most dynamic properties are modified using the internal <a href="./metacat-configure.html">Metacat configuration utility </a>.
38 38
     However, it may be necessary to manually edit a configuration file to update more static values.
39 39
  </p>   
40 40
   
......
48 48
       <li> <b>Set Method</b> - how does the value get set in the properties file.  There are
49 49
         two options:
50 50
         <ul>
51
           <li> Configuration Utility - the value is set via the internal <a href="./metacatconfigure.html">Metacat configuration utility </a></li>
51
           <li> Configuration Utility - the value is set via the internal <a href="./metacat-configure.html">Metacat configuration utility </a></li>
52 52
           <li> Manually - the value is set to a default that can only be changed by manually editing the configuration file. </li>
53 53
         </ul>  
54 54
       <li> <b>Example</b> - an example setting for the property.</li>
docs/user/metacat-configure.html
1
<!-- 
2
  *   '$RCSfile$'
3
  *     Purpose: web page describing the installation of Metacat
4
  *   Copyright: 2008 Regents of the University of California and the
5
  *               National Center for Ecological Analysis and Synthesis
6
  *     Authors: Chad Berkley
7
  *
8
  *    '$Author$'
9
  *    '$Date$'
10
  *    '$Revision$'
11
  *
12
  *
13
  -->
14
  
15
<!DOCTYPE html PUBLIC "-//W3C//DTD html 4.0//EN">
16
<html>
17

  
18
<head>
19
  <title>Metacat Configuration Instructions</title>
20
  <link rel="stylesheet" type="text/css" href="./common.css">
21
  <link rel="stylesheet" type="text/css" href="./default.css">
22
</head>
23

  
24
<body>
25

  
26
<table class="tabledefault" width="100%">
27
<tr><td rowspan="2"><img src="./images/KNBLogo.gif"></td>
28
<td colspan="7">
29
<div class="title">Metacat Configuration</div>
30
</td>
31
</tr>
32
<tr>
33
  <td><a href="/" class="toollink"> KNB Home </a></td>
34
  <td><a href="/data.html" class="toollink"> Data </a></td>
35
  <td><a href="/people.html" class="toollink"> People </a></td>
36
  <td><a href="/informatics" class="toollink"> Informatics </a></td>
37
  <td><a href="/biodiversity" class="toollink"> Biocomplexity </a></td>
38
  <td><a href="/education" class="toollink"> Education </a></td>
39
  <td><a href="/software" class="toollink"> Software </a></td>
40
</tr>
41
</table>
42
<hr>
43

  
44
<div class="header1">Table of Contents</div>
45
<div class="toc">
46
  <div class="toc1"><a href="#Overview">Overview</a></div>
47
      <div class="toc2"><a href="#MetacatConfiguration">Metacat Configuration</a></div> 
48
      <div class="toc2"><a href="#ConfigurationRules">Configuration Rules</a></div>
49
  <div class="toc1"><a href="#authConfig">Authentication Configuration</a></div>
50
      <div class="toc2"><a href="#AuthOverview">Authentication Overview</a></div> 
51
      <div class="toc2"><a href="#GetToAuthConfig">Getting to the Authentication Configuration</a></div> 
52
      <div class="toc2"><a href="#ConfigAuthNoAuth">Changing Authentication Configuration Without Authentication</a></div>
53
  <div class="toc1"><a href="#AdminLogin">Admin Log In</a></div>
54
    <div class="toc2"><a href="#AdminLoginOverview">Admin Log In</a></div>
55
    <div class="toc2"><a href="#LoggingIn">Logging In</a></div>
56
  <div class="toc1"><a href="#MainConfig">Main Configuration Page</a></div>
57
    <div class="toc2"><a href="#MainConfigOverview">Main Configuration Overview</a></div>
58
  <div class="toc1"><a href="#GlobalConfig">Global Properties Configuration</a></div>
59
    <div class="toc2"><a href="#GlobalConfigOverview">Global Properties Overview</a></div>
60
    <div class="toc2"><a href="#AutoDetection">Property Auto-Detection</a></div>
61
    <div class="toc2"><a href="#GlobalConfigBackup">Global Property Backup</a></div>  
62
  <div class="toc1"><a href="#SkinsConfig">Skins Configuration</a></div>  
63
    <div class="toc2"><a href="#SkinsConfigOverview">Skins Overview</a></div>
64
    <div class="toc2"><a href="#ChoosingDefaultSkin">Choosing a Default Skin</a></div>
65
    <div class="toc2"><a href="#ConfigOnlineRegistry">Configuring Online Registry</a></div>
66
  <div class="toc1"><a href="#DatabaseConfig">Database Configuration</a></div>
67
    <div class="toc2"><a href="#DatabaseConfigOverview">Database Configuration Overview</a></div>
68
    <div class="toc2"><a href="#DatabaseNewInstall">New Database Installation</a></div>
69
    <div class="toc2"><a href="#DatabaseUpgrade">Database Upgrade</a></div>
70
  <div class="toc1"><a href="#GeoserverConfig">Geoserver Configuration</a></div>
71
    <div class="toc2"><a href="#GeoserverUpdatePassword">Geoserver Password Update</a></div>
72
    <div class="toc2"><a href="#GeoserverManualUpdate">Geoserver Manual Update</a></div>  
73
  <div class="toc1"><a href="#CompleteConfig">Complete the Metacat Configuration</a></div>
74
</div> 
75

  
76
<a name="Overview"></a><div class="header1">Overview</div>
77
<a name="MetacatConfiguration"></a><div class="header2">Metacat Configuration</div>
78
  <p>As of version 1.9.0, Metacat configuration is done internally by the application.  When
79
  Metacat (Tomcat) is started, it will check to see if it is configured.  If not, you will be 
80
  automatically sent to the configuration pages. </p>
81
  
82
  <p>If the installation is new, or the previous version is before 1.9.0, you will 
83
  need to pay close attention to the configuration values.  If you have upgraded 
84
  Metacat, and the previous version is 1.9.0 or later, Metacat will pull existing 
85
  values from a backup location.  You should still verify that the values are
86
  correct.</p>
87
  
88
  <p>Get to Metacat on your server by entering into the browser:</p>
89
  <div class="code">http://&lt;your_context_url&gt;</div>
90
  <p>Where &lt;your_context_url&gt is the url where Metacat will be served followed
91
  by the name of the war file(application context) that you installed.  For instance, 
92
  the KNB production Metacat url is:</p>
93
  <div class="code">http://knb.ecoinformatics.org/knb</div>
94
  
95
  <p>You can always go to the configuration screen from within Metacat by typing:
96
  <div class="code">&lt;your_context_url&gt;/admin</div>
97
  
98
<a name="ConfigurationRules"></a><div class="header2">Configuration Rules</div>   
99
  <p>The system will follow these rules in order to determine the order
100
  that the configuration will occur:</p>
101
  
102
  <ul>
103
    <li>
104
      Always prompt the user for the backup directories with the  
105
      <a HREF="#BackupConfig">Backup Configuration Section</a>.  
106
      You will need to have backup directories configured in order 
107
      to continue with configuration.
108
    </li>
109
    <li>
110
      Is Authentication Configured? If not, show 
111
      <a HREF="#AuthConfig">Authentication Configuration Section</a>.  
112
      You will need to have authorizaiton configured in order to define administrative accounts
113
      and authenticate as one of these users.
114
    </li>
115
    <li>
116
      Are you logged in as an administrative user?  If not, show 
117
      <a HREF="#AdminLogin">Administrator Login Page</a>.
118
      You can only configure Metacat as an administrator.
119
    </li>
120
    <li>
121
      Are main properties, skins or database unconfigured?  If so, show 
122
      <a HREF="#MainConfig">Main Configuration Page</a>
123
      Note that you will not be able to select the database configuration utility 
124
      until main properties have been configured.
125
    </li>  
126
    <li>
127
      Are all sections configured?  If so, show 
128
      <a HREF="#MainConfig">Main Configuration Page</a> which
129
      include instructions for going to Metacat server (or restarting Metacat if you 
130
      are reconfiguring a running server).
131
    </li> 
132
  </ul>
133
  
134
  <p> See the following sections for descriptions of how each of these work.  For more
135
  information on each field, click on the blue question mark icon to the right.</p>
136

  
137
<a name="BackupConfig"></a><div class="header1">Backup Configuration</div>
138
  <a name="BackupOverview"></a><div class="header2">Backup Overview</div>
139
  <p>Metacat backs up all configured values to a directory outside the application
140
  installation directories.  This is so that we can preserve the configuration even
141
  after you upgrade Metacat (and the application directories get removed).</p>
142
  
143
  <p>Since a new installation/upgrade won't know where this external directory is, it will
144
  go through a discovery algorithm to give a best guess and pre-populate this value on the 
145
  Backup Directory Configuration screen (see fig 1).  The algorithm is:
146
  
147
  <ul>
148
  <li>Look for a saved backup location file in the user home dir - Is there a file named 
149
    &lt;user_home&gt;/.metacat/backup-location for the user that started tomcat? if so, does 
150
    it contain a single line which is a readable directory?  This directory was the backup 
151
    directory used during a previous install.  Return that directory.</li>
152
  <li>Look for an existing hidden (.metacat) directory in a default system directory.  Get 
153
   the default base directory for the OS.  (See application.windowsBackupBaseDir and 
154
   application.linuxBackupBaseDir in metacat.properties.)  If a directory called 
155
   &lt;base_dir&gt;/metacat/.metacat exists, return &lt;base_dir&gt;/metacat.</li>
156
  <li> Look for an existing hidden (.metacat) directory in the user directory. If a directory 
157
    called &lt;user_home&gt;/.metacat exists for the user that started tomcat, return &lt;user_home&gt;.</li>
158
  <li> Is the &lt;base_dir&gt; writable by the user that started tomcat?  If so, return &lt;base_dir&gt;</li>
159
  <li> Does the &lt;user_home&gt; exist?  If so, return &lt;user_home&gt;</li>
160
  <li> Otherwise, return null </li>
161
  </ul>
162
  <img class="screenshot" src="./images/backup-config.png"/>
163
  <div class="fig-text"> fig 1 </div>  
164

  
165
  <a name="ConfigBackup"></a><div class="header2">Configure Backup</div>
166
  <p>If the pre-populated value is incorrect, you should change it to the correct
167
  directory</p> 
168

  
169
<a name="AuthConfig"></a><div class="header1">Authentication Configuration</div>
170
  <a name="AuthOverview"></a><div class="header2">Authentication Overview</div>
171
  <p>Metacat uses LDAP as it's primary authentication mechanism, but you can define
172
  your own mechanism by creating a java class that implements 
173
  AuthInterface. The configuration values needed are Authentication Class, Authentication URL, 
174
  Authentication Secure URL and Metacat Administrators.  You need 
175
  to verify that the the Authentication URL and Authentication Secure URL are correct (fig 2).  
176
  <span class="emphasis">You need to make sure that your user 
177
  account is entered into the Metacat Administrators field.  You will not be allowed
178
  to continue with configuration if this is missing.</span>
179

  
180
  <img class="screenshot" src="./images/auth-config.png"/>
181
  <div class="fig-text"> fig 2 </div>
182

  
183
<a name="GetToAdminConfig"></a><div class="header2">Getting to the Authentication Configuration</div>
184
  <p>You will automatically be sent to the Authentication Configuration page if this is a new
185
  installation or upgrade.</p>
186
  
187
  <p>You can also get to the Administrative configuration from a running Metacat by typing:</p>
188
  <div class="code">&lt;your_context_url&gt;/admin</div>
189
  <p>You will be required to log in as an administrator and restart Metacat once you
190
  make changes.</p>
191
  
192
  <a name="ConfigAuthNoAuth"></a><div class="header2">Changing Authentication Configuration Without Authentication</div>
193
  <p>There is one exception to the log in rule.  That is when you need to change or add 
194
  authentication information, but you can't authenticate using the existing setup.  For example:</p>
195
  
196
  <ul>
197
    <li>The existing Metacat administrator is no longer available</li>
198
    <li>You forgot the administrator password.</li>
199
    <li>The configured authentication urls are unavailable and you need to configure new ones.</li>  
200
  </ul>
201
  
202
  <p>In this case, you will need to edit the Metacat configuration file by hand and
203
  make the changes.  This insures that only a person who has access to the Metacat
204
  server and the configuration files on that server will be able to change the
205
  administrator accounts</p>
206

  
207
  <p>Stop Tomcat and edit the Metacat properties file at:</p>
208
  <div class="code">&lt;webapp_dir&gt;/&lt;context_dir&gt;/WEB-INF/metacat.properties</div>
209
  <p>where &lt;webapp_dir&gt; is the place that Tomcat looks for applications and 
210
  &lt;context_dir&gt; is the name of the Metacat application (usually knb).  Change the 
211
  following properties appropriately:</p>
212
  
213
  <ul>
214
    <li>auth.administrators - a colon separated list of administrators</li>
215
    <li>auth.url - the authenication server url</li>
216
    <li>auth.surl - the authentication secure server url</li>  
217
  </ul>
218
  
219
  <p>Save the metacat.properties file and start Tomcat.</p>
220
  
221
<a name="AdminLogin"></a><div class="header1">Admin Log In</div>
222
<a name="AdminLoginOverview"></a><div class="header2">Admin Log In Overview</div>
223
  <p>Once authentication has been configured, you will be required to login as an 
224
  administrative user if you haven't already.  You will be taken to 
225
  the administrator login screen (fig 2).  You can also get to the login
226
  screen by choosing the "log in as different user" link at the bottom of
227
  any configuration screen.</p>
228
  
229
  <img class="screenshot" src="./images/admin-login.png"/>
230
  <div class="fig-text"> fig 3 </div>
231

  
232
<a name="LoggingIn"></a><div class="header2">Logging In</div>
233
<p>You need to log in with an account that was configured as an administrative
234
user in the authentication configuration section.  If you did not set up the correct user 
235
there, you will need to go through the 
236
<a href="#ConfigAuthNoAuth">Changing Authentication Configuration Without Authentication</a>
237
instructions to set up the user.</p>
238

  
239
<p>Enter your user name.  This is one of the Metacat administrators that you 
240
entered in authenticationuthentication configuration.  Enter your password and
241
hit the "Login" button.  You should successfully log in.</p>
242

  
243
<a name="MainConfig"></a><div class="header1">Main Configuration Page</div>
244
<a name="MainConfigOverview"></a><div class="header2">Main Configuration Overview</div>
245
  <p>The main configuration screen acts as a gateway into individual configuration
246
  sections (fig 4).  You should see that the authentication is already configured.</p>  
247
  
248
  <p>Each section is listed with a status to the left which can be one of:</p>
249
  <ul>
250
    <li><font color="red">[unconfigured]</font> - the section has yet to be configured</li>
251
    <li><font color="green">[configured]</font> - the section has been configured</li>
252
    <li>
253
      <font color="green">[bypassed]</font> - this is currently only used for Geoserver 
254
      configuration.  The administrator can choose not to configure the Geoserver user/password.
255
      In essence, the bypass status acts like the configured status.
256
    </li>  
257
  </ul>
258
  
259
  <p>To the right of each section is an option which can be one of:
260
  <ul>
261
    <li>Configure Now - click on this link to configure that section</li>
262
    <li>Reconfigure Now - the section was already configured, but you can choose to reconfigure it.</li>
263
    <li>
264
      Configure Global Properties First - this section has a dependency on the global
265
      properties section.  Once global properties is configured, the option to configure
266
      this section should become available.
267
    </li>  
268
    <li>Version: X.X.X - this is used for the Database Installation/Upgrade section.  The system
269
      detects the database schema version.  If that version is the same as the application version,
270
      that version will be displayed (i.e. 1.9.0) and no further database configuration is
271
      required.
272
    </li>
273
  </ul>
274
  
275
  <p>All sections must be in a configured or bypassed state in order to run Metacat.</p>
276
  
277
  <img class="screenshot" src="./images/main-config.png"/>
278
  <div class="fig-text"> fig 4 </div>
279
  
280
<a name="GlobalConfig"></a><div class="header1">Global Properties Configuration</div>
281
<a name="GlobalConfigOverview"></a><div class="header2">Global Properties Overview</div>
282
  <p>Metacat global properties are the bulk of the core properties needed to run Metacat 
283
  (fig 5).  For detailed instructions on setting these properties, refer to the blue 
284
  question mark icon to the right of each property.  Be sure that each of these are set
285
  appropriately.</p>
286
  
287
  <img class="screenshot" src="./images/global-config.png"/>
288
  <div class="fig-text"> fig 5 </div>
289

  
290
<a name="AutoDetection"></a><div class="header2">Property Auto-Detection</div> 
291
   <p>The first time you install Metacat, the system will attempt to auto-detect
292
   some values.  These are:</p>
293
   
294
  <ul>
295
    <li>Metacat Context - Name of the context under which Metacat will run. This is the name 
296
        of the Metacat war file that was deployed (minus the .war extension).</li>
297
    <li>Server Name - The DNS name of the server where Metacat will be available, not including
298
        port numbers or the http:// header.</li>
299
    <li>HTTP Port - The non-secure port where Metacat will be available. </li>  
300
    <li>HTTP SSL Port - The secure port where Metacat will be available.</li>
301
    <li>Deploy Location - The directory where the application is deployed.</li>
302
  </ul>
303
  
304
  <p>You should be extra careful that these were detected correctly.</p>
305
  
306
<a name="GlobalConfigBackup"></a><div class="header2">Global Property Backup</div>
307
  <p>When you save global properties, they are saved in a backup file that is 
308
  located in the following directory on linux:</p>
309
  <div class="code">/var/metacat/.metacat</div>
310
  and on windows:
311
  <div class="code">C:\Program Files\metacat\.metacat</div>
312
  <p>When you update Metacat, the system will look for these backed up properties
313
  so you won't have to re-enter all the information from previous installs.</p>
314
  
315
<a name="SkinsConfig"></a><div class="header1">Skins Configuration</div>
316
<a name="SkinsConfigOverview"></a><div class="header2">Skins Overview</div>
317
  <p>Metacat allows for a customized look and feel for the Metacat front end and for the 
318
  online data registry services.  There are two major functions provided by the
319
  skins configuration.  The first is to choose which skin will be the default.  The
320
  second will be to configure the look and feel of the online data registry pages.  For
321
  more information on the online data registry option, refer to the 
322
  <a href="./registry_installation.html">Metacat Registry Installation</a> documentation.</p>
323
  
324
  <p>Note that if you are not using the online registry, and you don't have a custom skin,
325
  you can just save the default skins configuration and move on to the next configuration
326
  section.</p>
327
  
328
<a name="ChoosingDefaultSkin"></a><div class="header2">Choosing a Default Skin</div> 
329
  <p>There are several skins available to choose from in Metacat (fig 6).  If you have a 
330
  skin that has been developed specifically for your instance of Metacat, you should
331
  select the checkbox next to that skin.  When you do, the form will open up with 
332
  several options for that skin (fig 6).  choose the 'Make "skin_name" default" radio selection.
333
  You should see "(default)" appear next to that skin name.  Save the configuration
334
  and that skin will be the one that appears when users visit your Metacat site.  Note
335
  that if you do not have a custom skin, you should leave your skin as the "default" skin.</p>
336
  
337
  <img class="screenshot" src="./images/skins-config.png"/>
338
  <div class="fig-text"> fig 6 </div>  
339

  
340
<a name="ConfigOnlineRegistry"></a><div class="header2">Configuring Online Registry</div> 
341
  <p>The online registry code provides a web interface for entering data into Metacat.  The
342
  screens are somewhat configurable as far as which fields show up and which are required.
343
  You should select each for which you want to activate the registry and then select the
344
  appropriate fields for that skin.</p> 
345
   
346
  <img class="screenshot" src="./images/skins-config-2.png"/>
347
  <div class="fig-text"> fig 7 </div>  
348
  
349
<a name="DatabaseConfig"></a><div class="header1">Database Configuration</div>
350
<a name="DatabaseConfigOverview"></a><div class="header2">Database Configuration Overview</div>
351
  <p>Metacat will detect the schema version of your database, and upgrade it if necessary.  Once the
352
  global Metacat properties have been configured, the Database Installation/Upgrade link 
353
  will become active on the main Metacat configuration page (see fig 4).</p>
354

  
355
<a name="DatabaseNewInstall"></a><div class="header2">New Database Installation</div>
356
  <p>If this is a installation of Metacat, the database install/upgrade utility will
357
  inform you of this (fig 8).  It will list the sql scripts that will get run in order
358
  to create a database schema for the version of Metacat that you are installing.  If
359
  there is any question as to whether the database is new, you should choose to cancel.
360
  When you choose to continue, the server will run the scripts you saw earlier.</p>
361
  <img class="screenshot" src="./images/database-config.png"/>
362
  <div class="fig-text"> fig 8 </div> 
363
 
364
<a name="DatabaseUpgrade"></a><div class="header2">Database Upgrade</div> 
365
  <p>If this is an upgrade of Metacat, the database install/upgrade utility will
366
  inform you of the current version of the database (fig 9).  It will list the sql scripts 
367
  that will get run in order to update the database schema to the upgraded version of 
368
  Metacat.  If there is any question as to whether the detected database schema version is 
369
  correct, you should choose to cancel. When you choose to continue, the server will run 
370
  the scripts you saw earlier.</p>
371
  <img class="screenshot" src="./images/database-config-2.png"/>
372
  <div class="fig-text"> fig 9 </div> 
373
 
374
<a name="GeoserverConfig"></a><div class="header1">Geoserver Configuration</div>
375
<a name="GeoserverOverview"></a><div class="header2">Geoserver Configuration Overview</div> 
376
  <p>Metacat comes bundled with a Web Mapping Service called Geoserver which 
377
  converts spatial data into web-deliverable map images.  For more information, see the
378
  <a href="./spatial_option.html">Metacat Spatial Option documentation</a>.  Geoserver 
379
  installs with a default admin username and password.  You should change these so that
380
  only local administrators can make changes to Geoserver.</p>
381
<a name="GeoserverUpdatePassword"></a><div class="header2">Geoserver Password Update</div>
382
  <p>When you choose the Geoserver Configuration link on the main configuratio page, you
383
  will go to a page that will prompt you for a user name and password (fig 10).  When you 
384
  enter a user name and password, the metacat server will contact the embedded Geoserver
385
  server and change the login credentails.</p>
386
  <p>You also have the option of choosing "bypass".  This will leave Geoserver configured
387
  with the default user name and password.  The main configuration screen will show the 
388
  bypassed status.  The system will interpret the bypassed status the same as the configured
389
  status.</p>
390
  
391
  <img class="screenshot" src="./images/geoserver-config.png"/>
392
  <div class="fig-text"> fig 10 </div> 
393
  
394
<a name="GeoserverManualUpdate"></a><div class="header2">Geoserver Manual Update</div>
395
  <p>You also have the option of changeing the Geoserver username and password by logging
396
  in directly to the Geoserver.  For more information on changing the credentials directly,
397
  refer to the <a href="./geoserver-manual-configure.html">Geoserver Password Change documentation</a>.
398
  Note that once you change the credentails manually, you will not be able to use the 
399
  Metacat admin tool to change it again (until a new Metacat Upgrade or installation).
400
<a name="CompleteConfig"></a><div class="header1">Complete the Metacat Configuration</div>  
401
  At this point, all the sections of the main configuration should be in a configured or
402
  bypassed state (fig 11).  If you are configuring because of a Metacat install or upgrade,
403
  you will have the option to click on the "go to metacat" link and you should get taken
404
  directly to the running version of Metacat.  Note that this may take some time depending
405
  on the amount of data in your database, since Metacat goes through an indexing process
406
  at start-up time.</p>
407
  
408
  <p>If you are reconfiguring an already running version of Metacat, you will not have the
409
  option to go directly back to Metacat.  You will need to restart the server (Tomcat).</p>
410
  <img class="screenshot" src="./images/main-config-2.png"/>
411
  <div class="fig-text"> fig 11 </div> 
0 412

  
docs/user/metacat-windows-install.html
157 157
	</ul>
158 158
	
159 159
  <a name="ConfigureMetacatInstall"></a><div class="header2">Configure Metacat</div> 
160
  <p>Refer to the documentation on <a href="./metacatconfigure.html">Metacat Confguration</a>
160
  <p>Refer to the documentation on <a href="./metacat-configure.html">Metacat Confguration</a>
161 161
  to complete your installation of Metacat.</p>
162 162
    
163 163
  <a name="QuickUpdate"></a><div class="header1">Quick Update</div>
......
195 195
    </ul>
196 196
	
197 197
  <a name="ConfigureMetacatUpdate"></a><div class="header2">Configure Metacat</div> 
198
    <p>Refer to the documentation on <a href="./metacatconfigure.html">Metacat Confguration</a>
198
    <p>Refer to the documentation on <a href="./metacat-configure.html">Metacat Confguration</a>
199 199
    to complete your installation of Metacat.</p>
200 200

  
201 201
  <br>

Also available in: Unified diff