Project

General

Profile

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

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 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/image009.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.png
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 Configuration, Skins Specific Properties, Database 
140
Installation/Upgrade, Geoserver, DataONE, and Replication Configuration), 
141
each of which is listed with its 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]      The administrator 
149
                can choose not to configure or skip the section.
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 edit them. 
156
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 and wheter or not you have opted to regenerate the spatial cache. 
169
If you are reconfiguring a running 
170
version of Metacat, you must restart the Tomcat server for the changes to 
171
take effect.
172
   
173
.. figure:: images/screenshots/image019.png
174
   :align: center
175

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

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

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

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

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

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

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

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

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

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

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

    
248
   Configuring Metacat skins.
249

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

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

    
262
* New Installation
263
* Upgrade
264

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

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

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

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

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

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

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

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

    
303
Geoserver Configuration (Highly Recommended)
304
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
305
.. sidebar:: Manual Geoserver Update
306

    
307
  Alternatively, you can change the Geoserver username and password manually by 
308
  directly logging in to the Geoserver. To configure the credentials manually: 
309

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

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

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

    
336
.. figure:: images/screenshots/image031.png
337
   :align: center
338

    
339
   Configuring Geoserver.
340

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

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

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

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

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

    
384
  <CONTEXT_DIR>/WEB_INF/metacat.properties
385

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

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

    
396
<SKIN_NAME>.properties
397
~~~~~~~~~~~~~~~~~~~~~~
398
The ``<SKIN_NAME>.properties`` file contains skin-specific properties 
399
(e.g., template information). For each skin, the skin-specific properties are 
400
found here::
401

    
402
  <CONTEXT_DIR>/style/skins/<SKIN_NAME>/<SKIN_NAME>.properties
403

    
404
Where ``<CONTEXT_DIR>`` is the directory in which the Metacat application code 
405
lives (described above) and ``<SKIN_NAME>`` is the name of the skin 
406
(e.g., ``default`` or ``nceas``).
407

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

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

    
419
1. Copy an exisiting skin directory. We recommend using the "default" directory.
420

    
421
  ::
422
  
423
    sudo cp -r <CONTEXT_DIR>/style/skins/default/ <CONTEXT_DIR>/style/skins/[yourSkin]/
424

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

    
428
2. In ``[yourSkin]`` directory, change all files named ``default.xxx`` to 
429
   ``yourSkin.xxx``. The following files should be changed:
430

    
431
  ::
432
  
433
    default.css
434
    default.js
435
    default.properties
436
    default.properties.metadata.xml
437
    default.xml
438

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

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

    
444
  ::
445
  
446
    /etc/init.d/tomcat6 restart
447

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

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