Project

General

Profile

1 4080 daigle
<!--
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 4558 daigle
  <link rel="stylesheet" type="text/css" href="./common.css">
21 4080 daigle
  <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 4558 daigle
<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 4597 daigle
  <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 4558 daigle
  <div class="toc1"><a href="#AdminLogin">Admin Log In</a></div>
54 4565 daigle
    <div class="toc2"><a href="#AdminLoginOverview">Admin Log In</a></div>
55
    <div class="toc2"><a href="#LoggingIn">Logging In</a></div>
56 4558 daigle
  <div class="toc1"><a href="#MainConfig">Main Configuration Page</a></div>
57 4565 daigle
    <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 4558 daigle
  <div class="toc1"><a href="#DatabaseConfig">Database Configuration</a></div>
67 4565 daigle
    <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 4558 daigle
  <div class="toc1"><a href="#GeoserverConfig">Geoserver Configuration</a></div>
71 4565 daigle
    <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 4558 daigle
</div>
75 4080 daigle
76 4558 daigle
<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 4080 daigle
82 4558 daigle
  <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 4080 daigle
  <ul>
103
    <li>
104 4597 daigle
      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 4080 daigle
    </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 4558 daigle
      Are main properties, skins or database unconfigured?  If so, show
116 4080 daigle
      <a HREF="metacatconfigure.html#main-config">Main Configuration Page</a>
117 4558 daigle
      Note that you will not be able to select the database configuration utility
118
      until main properties have been configured.
119
    </li>
120 4080 daigle
    <li>
121 4558 daigle
      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 4080 daigle
    </li>
126
  </ul>
127
128 4565 daigle
  <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 4080 daigle
131 4597 daigle
<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 4558 daigle
  to continue with configuration if this is missing.</span>
141
142 4597 daigle
  <img class="screenshot" src="./images/auth-config.png"/>
143 4558 daigle
  <div class="fig-text"> fig 1 </div>
144
145 4597 daigle
<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 4558 daigle
  installation or upgrade.</p>
148
149 4597 daigle
  <p>You can also get to the Administrative configuration from a running Metacat by typing:</p>
150 4558 daigle
  <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 4597 daigle
  <a name="ConfigAuthNoAuth"></a><div class="header2">Changing Authentication Configuration Without Authentication</div>
155 4558 daigle
  <p>There is one exception to the log in rule.  That is when you need to change or add
156 4597 daigle
  authentication information, but you can't authenticate using the existing setup.  For example:</p>
157 4558 daigle
158
  <ul>
159
    <li>The existing Metacat administrator is no longer available</li>
160
    <li>You forgot the administrator password.</li>
161 4597 daigle
    <li>The configured authentication urls are unavailable and you need to configure new ones.</li>
162 4558 daigle
  </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 4579 daigle
    <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 4558 daigle
  </ul>
180
181
  <p>Save the metacat.properties file and start Tomcat.</p>
182
183 4565 daigle
<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 4597 daigle
  <p>Once authentication has been configured, you will be required to login as an
186 4565 daigle
  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 4597 daigle
user in the authentication configuration section.  If you did not set up the correct user
197 4565 daigle
there, you will need to go through the
198 4597 daigle
<a href="#ConfigAuthNoAuth">Changing Authentication Configuration Without Authentication</a>
199 4565 daigle
instructions to set up the user.</p>
200
201 4597 daigle
<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 4565 daigle
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 4597 daigle
  sections (fig 3).  You should see that the authentication is already configured.</p>
209 4565 daigle
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:</p>
271
  <div class="code">/var/metacat/.metacat</div>
272
  <p>When you update Metacat, the system will look for these backed up properties
273
  so you won't have to re-enter all the information from previous installs.</p>
274
275
<a name="SkinsConfig"></a><div class="header1">Skins Configuration</div>
276
<a name="SkinsConfigOverview"></a><div class="header2">Skins Overview</div>
277
  <p>Metacat allows for a customized look and feel for the Metacat front end and for the
278
  online data registry services.  There are two major functions provided by the
279
  skins configuration.  The first is to choose which skin will be the default.  The
280
  second will be to configure the look and feel of the online data registry pages.  For
281
  more information on the online data registry option, refer to the
282
  <a href="./registry_installation.html">Metacat Registry Installation</a> documentation.</p>
283
284
  <p>Note that if you are not using the online registry, and you don't have a custom skin,
285
  you can just save the default skins configuration and move on to the next configuration
286
  section.</p>
287
288
<a name="ChoosingDefaultSkin"></a><div class="header2">Choosing a Default Skin</div>
289
  <p>There are several skins available to choose from in Metacat (fig 5).  If you have a
290
  skin that has been developed specifically for your instance of Metacat, you should
291
  select the checkbox next to that skin.  When you do, the form will open up with
292
  several options for that skin (fig 6).  choose the 'Make "skin_name" default" radio selection.
293
  You should see "(default)" appear next to that skin name.  Save the configuration
294
  and that skin will be the one that appears when users visit your Metacat site.  Note
295
  that if you do not have a custom skin, you should leave your skin as the "default" skin.</p>
296
297
  <img class="screenshot" src="./images/skins-config.png"/>
298
  <div class="fig-text"> fig 5 </div>
299
300
<a name="ConfigOnlineRegistry"></a><div class="header2">Configuring Online Registry</div>
301
  <p>The online registry code provides a web interface for entering data into Metacat.  The
302
  screens are somewhat configurable as far as which fields show up and which are required.
303
  You should select each for which you want to activate the registry and then select the
304
  appropriate fields for that skin.</p>
305
306
  <img class="screenshot" src="./images/skins-config-2.png"/>
307
  <div class="fig-text"> fig 6 </div>
308
309
<a name="DatabaseConfig"></a><div class="header1">Database Configuration</div>
310 4570 daigle
<a name="DatabaseConfigOverview"></a><div class="header2">Database Configuration Overview</div>
311 4565 daigle
  <p>Metacat will detect the schema version of your database, and upgrade it if necessary.  Once the
312
  global Metacat properties have been configured, the Database Installation/Upgrade link
313
  will become active on the main Metacat configuration page (see fig 3).</p>
314
315
<a name="DatabaseNewInstall"></a><div class="header2">New Database Installation</div>
316
  <p>If this is a installation of Metacat, the database install/upgrade utility will
317
  inform you of this (fig 7).  It will list the sql scripts that will get run in order
318
  to create a database schema for the version of Metacat that you are installing.  If
319
  there is any question as to whether the database is new, you should choose to cancel.
320
  When you choose to continue, the server will run the scripts you saw earlier.</p>
321
  <img class="screenshot" src="./images/database-config.png"/>
322
  <div class="fig-text"> fig 7 </div>
323
324
<a name="DatabaseUpgrade"></a><div class="header2">Database Upgrade</div>
325
  <p>If this is an upgrade of Metacat, the database install/upgrade utility will
326
  inform you of the current version of the database (fig 7).  It will list the sql scripts
327
  that will get run in order to update the database schema to the upgraded version of
328
  Metacat.  If there is any question as to whether the detected database schema version is
329
  correct, you should choose to cancel. When you choose to continue, the server will run
330
  the scripts you saw earlier.</p>
331
  <img class="screenshot" src="./images/database-config-2.png"/>
332
  <div class="fig-text"> fig 8 </div>
333
334
<a name="GeoserverConfig"></a><div class="header1">Geoserver Configuration</div>
335
<a name="GeoserverOverview"></a><div class="header2">Geoserver Configuration Overview</div>
336
  <p>Metacat comes bundled with a Web Mapping Service called Geoserver which
337
  converts spatial data into web-deliverable map images.  For more information, see the
338
  <a href="./spatial_option.html">Metacat Spatial Option documentation</a>.  Geoserver
339
  installs with a default admin username and password.  You should change these so that
340
  only local administrators can make changes to Geoserver.</p>
341
<a name="GeoserverUpdatePassword"></a><div class="header2">Geoserver Password Update</div>
342
  <p>When you choose the Geoserver Configuration link on the main configuratio page, you
343
  will go to a page that will prompt you for a user name and password (fig 9).  When you
344
  enter a user name and password, the metacat server will contact the embedded Geoserver
345
  server and change the login credentails.</p>
346
  <p>You also have the option of choosing "bypass".  This will leave Geoserver configured
347
  with the default user name and password.  The main configuration screen will show the
348
  bypassed status.  The system will interpret the bypassed status the same as the configured
349
  status.</p>
350
  <img class="screenshot" src="./images/geoserver-config.png"/>
351
  <div class="fig-text"> fig 9 </div>
352
<a name="GeoserverManualUpdate"></a><div class="header2">Geoserver Manual Update</div>
353
  <p>You also have the option of changeing the Geoserver username and password by logging
354
  in directly to the Geoserver.  For more information on changing the credentials directly,
355
  refer to the <a href="./geoserver-manual-configure.html">Geoserver Password Change documentation</a>.
356
  Note that once you change the credentails manually, you will not be able to use the
357
  Metacat admin tool to change it again (until a new Metacat Upgrade or installation).
358
<a name="CompleteConfig"></a><div class="header1">Complete the Metacat Configuration</div>
359
  At this point, all the sections of the main configuration should be in a configured or
360
  bypassed state (fig 10).  If you are configuring because of a Metacat install or upgrade,
361
  you will have the option to click on the "go to metacat" link and you should get taken
362
  directly to the running version of Metacat.  Note that this may take some time depending
363
  on the amount of data in your database, since Metacat goes through an indexing process
364
  at start-up time.</p>
365
366
  <p>If you are reconfiguring an already running version of Metacat, you will not have the
367
  option to go directly back to Metacat.  You will need to restart the server (Tomcat).</p>
368
  <img class="screenshot" src="./images/main-config-2.png"/>
369
  <div class="fig-text"> fig 10 </div>