Project

General

Profile

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

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 metacat):
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., "metacat"
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 or
227
MetacatUI themes, however as of Version 2.2.0, skins have been deprecated. 
228
Use MetacatUI themes instead. Themes can be deployed separately from the 
229
Metacat server allowing easier independent user interface customization.
230

    
231
MetacatUI Themes
232
................
233
Themes are applied in the Skins Configuration section. If you have installed 
234
the optional Registry, which provides a web interface for creating, editing, 
235
and submitting content to Metacat, you can also choose which form fields 
236
appear in that interface and which are required. Note that if you do not have 
237
a custom theme AND you are not using the Registry, you can simply save the 
238
``metacatui`` default configuration.
239

    
240
To use the new MetacatUI theming system, select ``metacatui`` and click the 
241
``Make metacatui default`` radio button. Metacat will open a list of options 
242
that apply to the Registry interface. For more information about creating 
243
custom themes, see the section called :doc:`themes </Modifying and Creating Themes>`.
244

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

    
248
   Configuring Metacat themes.
249

    
250
Skins
251
................
252
.. deprecated:2.2.0
253
   Use themes instead
254
   
255
If your Metacat has a customized skin, it will appear as a choice in the 
256
Skins Configuration settings (see below screenshot). Select the checkbox next 
257
to your customized skin or and click the ``Make <skin_name> default`` radio button. 
258
If you do not have a custom skin, select the ``default`` skin. 
259

    
260
Once you have selected a skin, Metacat will open a list of options that apply to the Registry 
261
interface. For more information about creating skins, see the Creating a Custom Skin
262
section in :doc:`themes </Modifying and Creating Themes>`.
263

    
264
.. figure:: images/screenshots/image023.png
265
   :align: center
266

    
267
   Configuring Metacat skins.
268
   
269
Select the checkbox next to your customized skin or and click the 
270
``Make <skin_name> default`` radio button. If you do not have a custom skin, 
271
select the ``default`` skin. Once you have selected a skin, Metacat will open 
272
a list of options that apply to the Registry interface.
273

    
274
.. figure:: images/screenshots/image025.png
275
   :align: center
276

    
277
   Configuring Metacat skins.
278

    
279
Select the lists and modules that you would like to appear in the Registry 
280
form-interface by checking the box beside each. When you save the configuration, 
281
the customized interface will appear to site visitors.
282

    
283
Database Configuration
284
~~~~~~~~~~~~~~~~~~~~~~
285
Because the Database Configuration is dependent on values specified in the 
286
Global Properties section, the link to these settings does not become active 
287
until after the global settings have been saved. Once the global settings have 
288
been saved, Metacat automatically detects the database schema version and 
289
upgrades it if necessary (and with your permission). 
290

    
291
* New Installation
292
* Upgrade
293

    
294
New Installation
295
................
296
If Metacat determines that your database is new, the Database Install/Upgrade 
297
utility lists the SQL scripts that will run in order to create a database 
298
schema for the new version of Metacat.
299

    
300
.. figure:: images/screenshots/image027.png
301
   :align: center
302

    
303
   Database installation creates tables needed for Metacat.
304
   
305
If the database is not new, or if you have any questions about whether it is 
306
new or not, choose Cancel and contact support at knb-help@nceas.ucsb.edu. 
307

    
308
When you choose Continue, Metacat runs the listed scripts and creates the 
309
database schema.
310

    
311
Upgrade
312
.......
313
If Metacat identifies a previous database schema, the Database Install/Upgrade 
314
utility notes the existing version and lists the SQL scripts that will run in 
315
order to update the schema for the new version of Metacat.
316

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

    
322
.. figure:: images/screenshots/image029.png
323
   :align: center
324

    
325
   Upgrading an existing database.
326
   
327
Additional upgrade tasks may also run after the database upgrade is complete.
328
For systems hosting large amounts of data, these upgrade routines can take time to complete.
329
It is important to let the process complete before using Metacat otherwise your deployment may become unstable.
330
   
331

    
332
Geoserver Configuration (Highly Recommended)
333
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
334
.. sidebar:: Manual Geoserver Update
335

    
336
  Alternatively, you can change the Geoserver username and password manually by 
337
  directly logging in to the Geoserver. To configure the credentials manually: 
338

    
339
  1. Go to the Geoserver admin page: http://<your_context_url>/geoserver/ 
340
  2. Log in using the default username and password ( admin / geoserver ) 
341
  3. Navigate to the Password Change Page.  Enter a new user and password and click Submit. 
342
  4. Click Apply then Save to save your new password. 
343
  
344
Metacat comes bundled with a Web Mapping Service called Geoserver, which 
345
converts spatial data into Web-deliverable map images. Geoserver installs with 
346
a default administrative username and password. *We highly recommend that you 
347
change the default credentials so that only local administrators can make 
348
changes to your Geoserver.* For more information about Geoserver, 
349
see :doc:`geoserver`.
350

    
351
When you choose the Geoserver Configuration link from the main configuration 
352
screen, Metacat will prompt you for a few important details about your Geoserver 
353
installation. The data directory and context settings allow Geoserver and 
354
Metacat to share the same spatial data store and render maps within Metacat skins. 
355
The security configuration prompts for a new admin password. After you enter 
356
the new settings, Metacat writes the information to the Geoserver deployment.
357

    
358
The default settings are typically appropriate for most Metacat deployments, 
359
but if you wish to skip the Geoserver configuration, click the Bypass button. 
360
Geoserver (if deployed) will remain with a default configuration and the main 
361
Metacat configuration screen will display the "bypassed" status beside the 
362
Geoserver settings. You will be able to run Metacat, but maps will not be 
363
rendered.
364

    
365
.. figure:: images/screenshots/image031.png
366
   :align: center
367

    
368
   Configuring Geoserver.
369

    
370
DataONE Configuration
371
~~~~~~~~~~~~~~~~~~~~~
372
Metacat can be configured to operate as a Member Node within the DataONE
373
federation of data repositories.  See :doc:`dataone` for background and details
374
on DataONE and details about configuring Metacat to act as a DataONE Member Node.
375

    
376
Replication Configuration
377
~~~~~~~~~~~~~~~~~~~~~~~~~
378
Metacat can be configured to replicate its metadata and/or data content to another
379
Metacat instance for backup and redundancy purposes, as well as to share data across
380
sites.  This feature has been used to create the Knowledge Network for Biocomplexity
381
(KNB), as well as other networks.  See :doc:`replication` for details on
382
the replication system and how to configure Metacat to replicate with another node.
383

    
384
.. Note:: 
385
  
386
  Note that much of the functionality provided by the replication subsystem in Metacat
387
  has now been generalized and standardized by DataONE, so consider utilizing the
388
  DataONE services for replication as it is a more general and standardized approach
389
  than this Metacat-specific replication system.  The Metacat replication system
390
  will be supported for a while longer, but will likely be deprecated in a future
391
  release in favor of using the DataONE replication approach. 
392

    
393
Additional Configuration
394
------------------------
395
The most dynamic Metacat properties are managed and modified with the 
396
form-based Metacat Configuration utility. These configuration properties can 
397
also be accessed directly (along with additional static properties) via 
398
Metacat's property files: ``metacat.properties`` (which contains global 
399
properties, e.g., authorization and database values) and 
400
``<SKIN_NAME>.properties`` (which contains skin-specific properties). Each of 
401
these property files is discussed in more depth in this section.
402

    
403
The ``metacat.properties`` file
404
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
405
Metacat's ``metacat.properties`` file contains all of Metacat's global 
406
properties, both the dynamic properties, which are managed with the 
407
Configuration utility, as well as the more static properties, which can only 
408
be modified manually in this file. The ``metacat.properties`` file also contains 
409
optional properties that are only relevant when optional Metacat features 
410
(such as the harvester or replication) are enabled. The `
411
`metacat.properties file`` is found here::
412

    
413
  <CONTEXT_DIR>/WEB_INF/metacat.properties
414

    
415
Where ``<CONTEXT_DIR>`` is the directory in which the Metacat application code 
416
lives (e.g., ``/var/lib/tomcat6/webapps/metacat``). The path is a combination 
417
of the Web application directory (e.g., ``/var/lib/tomcat6/webapps/``) and 
418
the Metacat context directory (e.g., ``metacat``). Both values depend upon how your 
419
system was set up during installation.
420

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

    
425
<SKIN_NAME>.properties
426
~~~~~~~~~~~~~~~~~~~~~~
427
The ``<SKIN_NAME>.properties`` file contains skin-specific properties 
428
(e.g., template information). For each skin, the skin-specific properties are 
429
found here::
430

    
431
  <CONTEXT_DIR>/style/skins/<SKIN_NAME>/<SKIN_NAME>.properties
432

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