Project

General

Profile

metacat / docs / user / metacat / source / configuration.rst @ 8230

1
Configuring Metacat
2
===================
3

    
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. 
9

    
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.
15

    
16
To access your Metacat, open a Web browser and type::
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 Authentication Configuration without Authentication`_ 
38
are included at the end of this section.
39

    
40
Back-up Configuration
41
~~~~~~~~~~~~~~~~~~~~~
42
To preserve its configuration settings, Metacat backs up crucial configuration details 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
NOTE: If the metacat.properties file has many custom settings, it should be manually 
49
backed up before any Metacat upgrade as deploying a new Metacat war file will overwrite
50
the existing file.
51

    
52
.. figure:: images/screenshots/image011.png
53
   :align: center
54

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

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

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

    
77
If you make changes to the authentication settings, you must restart Tomcat to 
78
put them into effect.
79

    
80
.. figure:: images/screenshots/image009.png
81
   :align: center
82

    
83
   Configuring Authentication Values.
84

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

    
94
To edit the authentication configuration file:
95

    
96
1. Stop Tomcat and edit the Metacat properties (``metacat.properties``) file in the
97
   Metacat context directory inside the Tomcat application directory. The 
98
   Metacat context directory is the name of the application (usually knb):
99

    
100
  ::
101
  
102
    <tomcat_app_dir>/<context_dir>/WEB-INF/metacat.properties
103

    
104
2. Change the following properties appropriately:
105

    
106
  ::
107
  
108
    auth.administrators - a colon separated list of administrators 
109
    auth.url - the authentication server URL 
110
    auth.surl - the authentication secure server URL
111

    
112
3. Save the ``metacat.properties`` file and start Tomcat.
113

    
114

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

    
122
In the log-in screen enter your user name and password and click 
123
the "Login" button.
124

    
125
.. figure:: images/screenshots/image015.png
126
   :align: center
127

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

    
136
.. figure:: images/screenshots/image017.png
137
   :align: center
138

    
139
   Metacat configuration menu, showing each configuration section.  Once all
140
   sections are marked as green ``configured``, metacat can be accessed.
141

    
142
The configuration settings are grouped into five sections (Metacat Global 
143
Properties, Authentication Configuration, Skins Specific Properties, Database 
144
Installation/Upgrade, Geoserver, DataONE, and Replication Configuration), 
145
each of which is listed with its current status (see table).
146

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

    
168
All settings must be in a configured or bypassed state in order to run Metacat. 
169
For new installations or upgrades, click the "go to metacat" link that appears 
170
after configuration is complete to go directly to Metacat. Note that Metacat 
171
indexes at start-up time, so the initial start-up may take some time depending 
172
on the amount of data in your database and wheter or not you have opted to regenerate the spatial cache. 
173
If you are reconfiguring a running 
174
version of Metacat, you must restart the Tomcat server for the changes to 
175
take effect.
176
   
177
.. figure:: images/screenshots/image019.png
178
   :align: center
179

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

    
189
.. figure:: images/screenshots/image021.png
190
   :align: center
191

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

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

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

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

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

    
234
If your Metacat has a customized skin, it will appear as a choice in the 
235
Skins Configuration settings (see below screenshot). You can create your own skins as 
236
well. For more information about creating skins, please see the section called
237
`Creating a Custom Skin`_.
238

    
239
.. figure:: images/screenshots/image023.png
240
   :align: center
241

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

    
249
.. figure:: images/screenshots/image025.png
250
   :align: center
251

    
252
   Configuring Metacat skins.
253

    
254
Select the lists and modules that you would like to appear in the Registry 
255
form-interface by checking the box beside each. When you save the configuration, 
256
the customized interface will appear to site visitors.
257

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

    
266
* New Installation
267
* Upgrade
268

    
269
New Installation
270
................
271
If Metacat determines that your database is new, the Database Install/Upgrade 
272
utility lists the SQL scripts that will run in order to create a database 
273
schema for the new version of Metacat.
274

    
275
.. figure:: images/screenshots/image027.png
276
   :align: center
277

    
278
   Database installation creates tables needed for Metacat.
279
   
280
If the database is not new, or if you have any questions about whether it is 
281
new or not, choose Cancel and contact support at knb-help@nceas.ucsb.edu. 
282

    
283
When you choose Continue, Metacat runs the listed scripts and creates the 
284
database schema.
285

    
286
Upgrade
287
.......
288
If Metacat identifies a previous database schema, the Database Install/Upgrade 
289
utility notes the existing version and lists the SQL scripts that will run in 
290
order to update the schema for the new version of Metacat.
291

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

    
297
.. figure:: images/screenshots/image029.png
298
   :align: center
299

    
300
   Upgrading an existing database.
301
   
302
Additional upgrade tasks may also run after the database upgrade is complete.
303
For systems hosting large amounts of data, these upgrade routines can take time to complete.
304
It is important to let the process complete before using Metacat otherwise your deployment may become unstable.
305
   
306

    
307
Geoserver Configuration (Highly Recommended)
308
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
309
.. sidebar:: Manual Geoserver Update
310

    
311
  Alternatively, you can change the Geoserver username and password manually by 
312
  directly logging in to the Geoserver. To configure the credentials manually: 
313

    
314
  1. Go to the Geoserver admin page: http://<your_context_url>/geoserver/ 
315
  2. Log in using the default username and password ( admin / geoserver ) 
316
  3. Navigate to the Password Change Page.  Enter a new user and password and click Submit. 
317
  4. Click Apply then Save to save your new password. 
318
  
319
Metacat comes bundled with a Web Mapping Service called Geoserver, which 
320
converts spatial data into Web-deliverable map images. Geoserver installs with 
321
a default administrative username and password. *We highly recommend that you 
322
change the default credentials so that only local administrators can make 
323
changes to your Geoserver.* For more information about Geoserver, 
324
see :doc:`geoserver`.
325

    
326
When you choose the Geoserver Configuration link from the main configuration 
327
screen, Metacat will prompt you for a few important details about your Geoserver 
328
installation. The data directory and context settings allow Geoserver and 
329
Metacat to share the same spatial data store and render maps within Metacat skins. 
330
The security configuration prompts for a new admin password. After you enter 
331
the new settings, Metacat writes the information to the Geoserver deployment.
332

    
333
The default settings are typically appropriate for most Metacat deployments, 
334
but if you wish to skip the Geoserver configuration, click the Bypass button. 
335
Geoserver (if deployed) will remain with a default configuration and the main 
336
Metacat configuration screen will display the "bypassed" status beside the 
337
Geoserver settings. You will be able to run Metacat, but maps will not be 
338
rendered.
339

    
340
.. figure:: images/screenshots/image031.png
341
   :align: center
342

    
343
   Configuring Geoserver.
344

    
345
DataONE Configuration
346
~~~~~~~~~~~~~~~~~~~~~
347
Metacat can be configured to operate as a Member Node within the DataONE
348
federation of data repositories.  See :doc:`dataone` for background and details
349
on DataONE and details about configuring Metacat to act as a DataONE Member Node.
350

    
351
Replication Configuration
352
~~~~~~~~~~~~~~~~~~~~~~~~~
353
Metacat can be configured to replicate its metadata and/or data content to another
354
Metacat instance for backup and redundancy purposes, as well as to share data across
355
sites.  This feature has been used to create the Knowledge Network for Biocomplexity
356
(KNB), as well as other networks.  See :doc:`replication` for details on
357
the replication system and how to configure Metacat to replicate with another node.
358

    
359
.. Note:: 
360
  
361
  Note that much of the functionality provided by the replication subsystem in Metacat
362
  has now been generalized and standardized by DataONE, so consider utilizing the
363
  DataONE services for replication as it is a more general and standardized approach
364
  than this Metacat-specific replication system.  The Metacat replication system
365
  will be supported for a while longer, but will likely be deprecated in a future
366
  release in favor of using the DataONE replication approach. 
367

    
368
Additional Configuration
369
------------------------
370
The most dynamic Metacat properties are managed and modified with the 
371
form-based Metacat Configuration utility. These configuration properties can 
372
also be accessed directly (along with additional static properties) via 
373
Metacat's property files: ``metacat.properties`` (which contains global 
374
properties, e.g., authorization and database values) and 
375
``<SKIN_NAME>.properties`` (which contains skin-specific properties). Each of 
376
these property files is discussed in more depth in this section.
377

    
378
The ``metacat.properties`` file
379
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
380
Metacat's ``metacat.properties`` file contains all of Metacat's global 
381
properties, both the dynamic properties, which are managed with the 
382
Configuration utility, as well as the more static properties, which can only 
383
be modified manually in this file. The ``metacat.properties`` file also contains 
384
optional properties that are only relevant when optional Metacat features 
385
(such as the harvester or replication) are enabled. The `
386
`metacat.properties file`` is found here::
387

    
388
  <CONTEXT_DIR>/WEB_INF/metacat.properties
389

    
390
Where ``<CONTEXT_DIR>`` is the directory in which the Metacat application code 
391
lives (e.g., ``/var/lib/tomcat6/webapps/knb``). The path is a combination 
392
of the Web application directory (e.g., ``/var/lib/tomcat6/webapps/``) and 
393
the Metacat context directory (e.g., ``knb``). Both values depend upon how your 
394
system was set up during installation.
395

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

    
400
<SKIN_NAME>.properties
401
~~~~~~~~~~~~~~~~~~~~~~
402
The ``<SKIN_NAME>.properties`` file contains skin-specific properties 
403
(e.g., template information). For each skin, the skin-specific properties are 
404
found here::
405

    
406
  <CONTEXT_DIR>/style/skins/<SKIN_NAME>/<SKIN_NAME>.properties
407

    
408
Where ``<CONTEXT_DIR>`` is the directory in which the Metacat application code 
409
lives (described above) and ``<SKIN_NAME>`` is the name of the skin 
410
(e.g., ``default`` or ``nceas``).
411

    
412
Creating a custom skin
413
~~~~~~~~~~~~~~~~~~~~~~
414
Skins are used in Metacat to customize the appearance of the search and display
415
web interface that is presented by Metacat.  Skins can be used to make a Metacat
416
instance exactly integrate into an existing web site, and are fully customizable.
417

    
418
To create and customize your own Metacat skin, you must first create a skin 
419
directory. This is most easily accomplished by copying one of the existing skin 
420
directories. Step-by-step directions for creating and installing a custom skin 
421
are included below:
422

    
423
1. Copy an exisiting skin directory. We recommend using the "default" directory.
424

    
425
  ::
426
  
427
    sudo cp -r <CONTEXT_DIR>/style/skins/default/ <CONTEXT_DIR>/style/skins/[yourSkin]/
428

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

    
432
2. In ``[yourSkin]`` directory, change all files named ``default.xxx`` to 
433
   ``yourSkin.xxx``. The following files should be changed:
434

    
435
  ::
436
  
437
    default.css
438
    default.js
439
    default.properties
440
    default.properties.metadata.xml
441
    default.xml
442

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

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

    
448
  ::
449
  
450
    /etc/init.d/tomcat6 restart
451

    
452
Navigate to Metacat's Configuration utility  and select the Configure Skins 
453
option. Your custom skin should appear as a choice in the skins list. Change 
454
the layout and style by modifying the header, footer, css, and other files in 
455
your new skin directory.
456

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