|
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: daigle $'
|
|
9
|
* '$Date: 2008-11-19 16:48:24 -0800 (Wed, 19 Nov 2008) $'
|
|
10
|
* '$Revision: 4597 $'
|
|
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://<your_context_url></div>
|
|
90
|
<p>Where <your_context_url> 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"><your_context_url>/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"><your_context_url>/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"><webapp_dir>/<context_dir>/WEB-INF/metacat.properties</div>
|
|
171
|
<p>where <webapp_dir> is the place that Tomcat looks for applications and
|
|
172
|
<context_dir> 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:</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
|
<a name="DatabaseConfigOverview"></a><div class="header2">Database Configuration Overview</div>
|
|
311
|
<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>
|
