Project

General

Profile

Revision 6839

Added by Matt Jones almost 9 years ago

Updated the configuration section, converted word doc to RST.

View differences:

configuration.rst
1 1
Configuring Metacat
2 2
===================
3 3

  
4
Under construction!
4
.. contents::
5
  
6
When Metacat (Tomcat) is started, the Metacat servlet checks to see if it is 
7
configured. If not, Metacat will automatically send you to the configuration 
8
pages. 
5 9

  
6
Heading 1
7
------------
10
If the installation is new, or the previous version is before 1.9.0, pay close 
11
attention to the configuration values. If you have upgraded Metacat, and the 
12
previous version is 1.9.0 or later, Metacat will pull existing configuration 
13
settings from a backup location. You should still verify that the values are 
14
correct.
8 15

  
9
Heading 2
10
------------
16
To access your Metacat, open a Web browser and type::
11 17

  
18
  http://<your_context_url>
19

  
20
Where <your_context_url> is the URL of the server hosting the Metacat followed 
21
by the name of the WAR file (i.e., the application context) that you installed.
22
For instance, the context URL for the KNB Metacat is: http://knb.ecoinformatics.org/knb
23

  
24
You can always open the configuration screen from within Metacat by typing::
25

  
26
  http://<your_context_url>/admin
27

  
28
Initial Configuration
29
---------------------
30
Before you can log in to the Metacat and configure it, you are required to 
31
confirm Metacat's back-up location and authentication configuration (if not 
32
already configured). Metacat will automatically attempt to locate an existing 
33
back-up directory, but you may need to correct the value or specify a directory 
34
(if the installation is new, or if Metacat was unable to determine the location 
35
of an existing back-up directory). The authentication configuration is required 
36
for logging in to the Metacat and for defining administrative accounts. 
37
Instructions for changing the authentication configuration without 
38
authentication are included at the end of this section.
39

  
40
Back-up Configuration
41
~~~~~~~~~~~~~~~~~~~~~
42
To preserve its configuration settings, Metacat backs up all configurations to 
43
a directory outside the application directories. Because a new installation/upgrade 
44
does not know where this external directory is, Metacat uses a discovery 
45
algorithm to locate it. If Metacat cannot identify a backup directory, you will 
46
see the Backup Directory Configuration screen.
47

  
48
.. figure:: images/screenshots/image011.png
49
   :align: center
50

  
51
   Configuring the Backup Directory.
52
   
53
Authentication Configuration
54
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
55
Whether you are installing or upgrading the Metacat servlet, you will 
56
automatically be sent to the Authentication Configuration page. You can also 
57
reach the Authentication Configuration page from a running Metacat by typing::
58
  
59
  http://<your_context_url>/admin
60

  
61
Metacat uses LDAP as its primary authentication mechanism, but you can define 
62
your own authentication mechanism by creating a Java class that implements 
63
``AuthInterface``. Required configuration values are: Authentication Class, 
64
Authentication URL, Authentication Secure URL, and Metacat Administrators. 
65
Make sure that your user account information is entered into the Metacat 
66
Administrators field (e.g., uid=daigle,o=nceas,dc=ecoinformatics,dc=org). You 
67
will not be allowed to continue with configuration if this is missing. 
68

  
69
NOTE: To create an LDAP account on the KNB LDAP server (specified as the 
70
default LDAP server), go to http://knb.ecoinformatics.org and select the 
71
"create a new user account" link.
72

  
73
If you make changes to the authentication settings, you must restart Tomcat to 
74
put them into effect.
75

  
76
.. figure:: images/screenshots/image013.png
77
   :align: center
78

  
79
   Configuring Authentication Values.
80

  
81
Changing Authentication Configuration without Authentication
82
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
83
If you need to change or add authentication information and cannot authenticate 
84
using the existing authentication settings (e.g., the existing Metacat 
85
administrator is no longer available or you forgot the administrator password), 
86
you must edit the Metacat configuration file by hand. This ensures that only a 
87
person who has access to the Metacat server and the configuration files on that 
88
server will be able to change the administrator accounts.
89

  
90
To edit the authentication configuration file:
91

  
92
1. Stop Tomcat and edit the Metacat properties (``metacat.properties``) file in the
93
   Metacat context directory inside the Tomcat application directory. The 
94
   Metacat context directory is the name of the application (usually knb):
95

  
96
  ::
97
  
98
    <tomcat_app_dir>/<context_dir>/WEB-INF/metacat.properties
99

  
100
2. Change the following properties appropriately:
101

  
102
  ::
103
  
104
    auth.administrators - a colon separated list of administrators 
105
    auth.url - the authentication server URL 
106
    auth.surl - the authentication secure server URL
107

  
108
3. Save the ``metacat.properties`` file and start Tomcat.
109

  
110

  
111
Logging in to Metacat
112
---------------------
113
In order to configure Metacat, you must log in with an administrative account 
114
that has been configured in the Authentication Configuration settings. If you 
115
did not set up the correct administrative user there, you must change the 
116
authentication configuration by hand before you can log in.
117

  
118
In the log-in screen enter your user name and password and click 
119
the "Login" button.
120

  
121
.. figure:: images/screenshots/image015.jpg
122
   :align: center
123

  
124
   Logging into Metacat.
125
   
126
Required Configuration
127
----------------------
128
All required Metacat settings can be accessed from the Metacat Configuration 
129
utility, which becomes available after the initial configurations 
130
have been specified and an authorized administrator logs in. 
131

  
132
.. figure:: images/screenshots/image017.png
133
   :align: center
134

  
135
   Metacat configuration menu, showing each configuration section.  Once all
136
   sections are marked as green ``configured``, metacat can be accessed.
137

  
138
The configuration settings are grouped into five sections (Metacat Global 
139
Properties, Authentication Configuraion, Skins Specific Properties, Database 
140
Installation/Upgrade, Geoserver Configuration), each of which is listed with its 
141
current status (see table).
142

  
143
==============  =============================================================
144
Status          Description
145
==============  =============================================================
146
[unconfigured]  The section has yet to be configured 
147
[configured]    The section has been configured. 
148
[bypassed]      Used only for the Geoserver configurations. The administrator 
149
                can choose not to configure the Geoserver user/password.
150
==============  =============================================================
151
 
152
To the right of each configuration section is one of the following options: 
153
Configure Now, Reconfigure Now, Configure Global Properties First, or 
154
Version:X.X.X. If the option is linked (e.g., Configure Now or Reconfigure Now), 
155
you can select the link to open the associated configuration settings and add 
156
or edit them, respectively. If the option is not linked (e.g., Configure Global 
157
Properties First), the settings cannot be specified until the global properties 
158
are set. Once the global properties are configured, the option to configure this 
159
section becomes available. The Version:X.X.X option is used only for the 
160
Database Installation/Upgrade section. If the database schema version detected 
161
by Metacat matches the application version (eg, 1.9.0), then no further database 
162
configuration is required.
163

  
164
All settings must be in a configured or bypassed state in order to run Metacat. 
165
For new installations or upgrades, click the "go to metacat" link that appears 
166
after configuration is complete to go directly to Metacat. Note that Metacat 
167
indexes at start-up time, so the initial start-up may take some time depending 
168
on the amount of data in your database. If you are reconfiguring a running 
169
version of Metacat, you must restart the Tomcat server for the changes to 
170
take effect.
171

  
172
.. figure:: images/screenshots/image019.png
173
   :align: center
174

  
175
   The Metacat settings as they appear after having been configured.
176
   
177
Global Properties (server, ports, etc)
178
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
179
The Metacat configurations included under Global Properties represent the bulk 
180
of the settings required to run Metacat. Click a blue question-mark 
181
icon beside any setting for detailed instructions. More information about each 
182
property is also included in the :doc:`metacat-properties`.
183

  
184
.. figure:: images/screenshots/image021.png
185
   :align: center
186

  
187
   The Metacat Global Properties editing screen.
188
   
189
When you save global properties, Metacat also saves a back-up file that is 
190
located in ``/var/metacat/.metacat`` (on Linux) or 
191
``C:\Program Files\metacat\.metacat`` (on Windows). When you update Metacat, 
192
the system automatically locates the back-up file so you do not have to re-enter 
193
the configuration settings.
194

  
195
The first time you install Metacat, the system attempts to automatically detect 
196
the values for a number of settings (see table). It is important to ensure that 
197
these values are correct.
198

  
199
================  ============================================================
200
Property          Description
201
================  ============================================================
202
Metacat Context   The name of the deployed Metacat WAR file (minus the .war 
203
                  extension). E.g., "knb"
204
Server Name       The DNS name of the server hosting Metacat, not including 
205
                  port numbers or the "http://" header. 
206
HTTP Port         The non-secure port where Metacat will be available.
207
HTTP SSL Port     The secure port where Metacat will be available. 
208
Deploy Location   The directory where the application is deployed. 
209
================  ============================================================
210

  
211
Authentication Configuration
212
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
213
Because you must specify the Authentication settings before you can access the 
214
main configuration page, the settings will always be configured when you view 
215
them in the admin interface. If you wish to change the authentication settings, 
216
you must restart Metacat to put the changes into effect. For more information 
217
about the Authentication configurations, please see Initial Configurations.
218

  
219
Skins Configuration
220
~~~~~~~~~~~~~~~~~~~
221
Customizing the look and feel of Metacat's Web interface is done via skins, 
222
which are applied in the Skins Configuration section. If you have installed 
223
the optional Registry, which provides a Web interface for creating, editing, 
224
and submitting content to the Metacat, you can also choose which form fields 
225
appear in that interface and which are required. Note that if you do not have 
226
a custom skin AND you are not using the Registry, you can simply save the 
227
default configuration.
228

  
229
If your Metacat has a customized skin, it will appear as a choice in the 
230
Skins Configuration settings (Figure 3.7). You can creat your own skins as 
231
well. For more information about creating skins, please see the section called
232
Creating a Custom Skin.
233

  
234
.. figure:: images/screenshots/image023.png
235
   :align: center
236

  
237
   Configuring Metacat skins.
238
   
239
Select the checkbox next to your customized skin and click the 
240
``Make <skin_name> default`` radio button. If you do not have a custom skin, 
241
select the ``default`` skin. Once you have selected a skin, Metacat will open 
242
a list of options that apply to the Registry interface.
243

  
244
.. figure:: images/screenshots/image025.png
245
   :align: center
246

  
247
   Configuring Metacat skins.
248

  
249
Select the lists and modules that you would like to appear in the Registry 
250
form-interface by checking the box beside each. When you save the configuration, 
251
the customized interface will appear to site visitors.
252

  
253
Database Configuration
254
~~~~~~~~~~~~~~~~~~~~~~
255
Because the Database Configuration is dependent on values specified in the 
256
Global Configuration section, the link to these settings does not become active 
257
until after the global settings have been saved. Once the global settings have 
258
been saved, Metacat automatically detects the database schema version and 
259
upgrades it if necessary (and with your permission). 
260

  
261
* New Installation
262
* Upgrade
263

  
264
New Installation
265
................
266
If Metacat determines that your database is new, the Database Install/Upgrade 
267
utility lists the SQL scripts that will run in order to create a database 
268
schema for the new version of Metacat.
269

  
270
.. figure:: images/screenshots/image027.png
271
   :align: center
272

  
273
   Database installation creates tables needed for Metacat.
274
   
275
If the database is not new, or if you have any questions about whether it is 
276
new or not, choose Cancel and contact support at knb-help@nceas.ucsb.edu. 
277

  
278
When you choose Continue, Metacat runs the listed scripts and creates the 
279
database schema.
280

  
281
Upgrade
282
.......
283
If Metacat identifies a previous database schema, the Database Install/Upgrade 
284
utility notes the existing version and lists the SQL scripts that will run in 
285
order to update the schema for the new version of Metacat.
286

  
287
If the detected schema version is incorrect, or if you have any questions about 
288
whether it is correct or not, click the Cancel button and contact support at 
289
knb-help@nceas.ucsb.edu.When you choose to continue, Metacat runs the listed 
290
scripts and updates the database schema.
291

  
292
.. figure:: images/screenshots/image029.png
293
   :align: center
294

  
295
   Upgrading an existing database.
296

  
297
Geoserver Password Configuration (Highly Recommended)
298
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
299
.. sidebar:: Manual Geoserver Update
300

  
301
  Alternatively, you can change the Geoserver username and password manually by 
302
  directly logging in to the Geoserver. To configure the credentials manually: 
303

  
304
  1. Go to the Geoserver admin page: http://<your_context_url>/geoserver.jsp. 
305
  2. Log in using the default username and password ( admin / geoserver ) 
306
  3. Navigate to the Password Change Page.  Enter a new user and password and click Submit. 
307
  4. Click Apply then Save to save your new password. 
308

  
309
  Note that once you change the Geoserver credentials manually, you cannot use 
310
  the Metacat configuration tool to change it again (until a new Metacat 
311
  upgrade or installation).
312
  
313
Metacat comes bundled with a Web Mapping Service called Geoserver, which 
314
converts spatial data into Web-deliverable map images. Geoserver installs with 
315
a default administrative username and password. We highly recommend that you 
316
change the default log-in information so that only local administrators can make 
317
changes to your Geoserver. For more information about Geoserver, 
318
see :doc:`geoserver`.
319

  
320
When you choose the Geoserver Configuration link from the main configuration 
321
screen, Metacat will prompt you for a new user name and password. After you 
322
enter the new credentials, the Metacat server contacts the embedded Geoserver s
323
erver and updates the log-in settings.
324

  
325
If you wish to reset the Geoserver credentials at another time, click the 
326
Bypass button. The Geoserver will remain configured with the default user name 
327
and password, and the main configuration screen will display the "bypassed" 
328
status beside the Geoserver settings. You will be able to run Metacat, just as 
329
if the settings were configured.
330

  
331
.. figure:: images/screenshots/image031.png
332
   :align: center
333

  
334
   Resetting the Geoserver password.
335

  
336
Additional Configuration
337
------------------------
338
The most dynamic Metacat properties are managed and modified with the 
339
form-based Metacat Configuration utility. These configuration properties can 
340
also be accessed directly (along with additional static properties) via 
341
Metacat's property files: ``metacat.properties`` (which contains global 
342
properties, e.g., authorization and database values) and 
343
``<SKIN_NAME>.properties`` (which contains skin-specific properties). Each of 
344
these property files is discussed in more depth in this section.
345

  
346
The ``metacat.properties`` file
347
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
348
Metacat's ``metacat.properties`` file contains all of Metacat's global 
349
properties, both the dynamic properties, which are managed with the 
350
Configuration utility, as well as the more static properties, which can only 
351
be modified manually in this file. The ``metacat.properties`` file also contains 
352
optional properties that are only relevant when optional Metacat features 
353
(such as the harvester or replication) are enabled. The `
354
`metacat.properties file`` is found here::
355

  
356
  <CONTEXT_DIR>/WEB_INF/metacat.properties
357

  
358
Where ``<CONTEXT_DIR>`` is the directory in which the Metacat application code 
359
lives (e.g., ``/usr/share/tomcat5.5/webapps/knb``). The path is a combination 
360
of the Web application directory (e.g., ``/usr/share/tomcat5.5/webapps/``) and 
361
the Metacat context directory (e.g., ``knb``). Both values depend upon how your 
362
system was set up during installation.
363

  
364
For information about each property and default or example settings, please 
365
see the :doc:`metacat-properties`. Properties that can only be edited manually 
366
in the metacat.properties file are highlighted in the appendix.
367

  
368
<SKIN_NAME>.properties
369
~~~~~~~~~~~~~~~~~~~~~~
370
The ``<SKIN_NAME>.properties`` file contains skin-specific properties 
371
(e.g., template information). For each skin, the skin-specific properties are 
372
found here::
373

  
374
  <CONTEXT_DIR>/style/skins/<SKIN_NAME>/<SKIN_NAME>.properties
375

  
376
Where ``<CONTEXT_DIR>`` is the directory in which the Metacat application code 
377
lives (described above) and ``<SKIN_NAME>`` is the name of the skin 
378
(e.g., ``default`` or ``nceas``).
379

  
380
Creating a custom skin
381
~~~~~~~~~~~~~~~~~~~~~~
382
Skins are used in Metacat to customize the appearance of the search and display
383
web interface that is presented by Metacat.  Skins can be used to make a Metacat
384
instance exactly integrate into an existing web site, and are fully customizable.
385

  
386
To create and customize your own Metacat skin, you must first create a skin 
387
directory. This is most easily accomplished by copying one of the existing skin 
388
directories. Step-by-step directions for creating and installing a custom skin 
389
are included below:
390

  
391
1. Copy an exisiting skin directory. We recommend using the "default" directory.
392

  
393
  ::
394
  
395
    sudo cp -r <CONTEXT_DIR>/style/skins/default/ <CONTEXT_DIR>/style/skins/[yourSkin]/
396

  
397
  Where ``<CONTEXT_DIR>`` is the directory in which the Metacat application 
398
  code lives  and ``[yourSkin]`` is the name you wish to apply to your skin.
399

  
400
2. In ``[yourSkin]`` directory, change all files named ``default.xxx`` to 
401
   ``yourSkin.xxx``. The following files should be changed:
402

  
403
  ::
404
  
405
    default.css
406
    default.js
407
    default.properties
408
    default.properties.metadata.xml
409
    default.xml
410

  
411
3. In the metacat.properties file(``<CONTEXT_DIR>/WEB_INF/metacat.properties``), 
412
   add ``[yourSkin]`` to the value of the skin.names property.
413

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

  
416
  ::
417
  
418
    /etc/init.d/tomcat5.5 restart
419

  
420
Navigate to Metacat's Configuration utility  and select the Configure Skins 
421
option. Your custom skin should appear as a choice in the skins list. Change 
422
the layout and style by modifying the header, footer, css, and other files in 
423
your new skin directory.
424

  
425
It is important to note that all customized skins will be overwritten when 
426
Metacat is reinstalled or upgraded. Please remember to back up your skins before
427
reinstalling or upgrading Metacat.

Also available in: Unified diff