Page History

...

• General Configuration - addresses general conventions used with configuring not only the dspacelocal.cfg file, but dspace.cfg and other configuration files which use similar conventions.
• The
build
• local.
properties
• cfg Configuration Properties
File - specifies the basic build.properties file settings (these basic settings are used when building/installing/upgrading DSpace)
• Files - describes how to use the local.cfg file to store all your locally customized configurations
• The dspace.cfg Configuration Properties File - specifies the basic dspace.cfg file settings (these settings are used when DSpace is actually runningspecify the default configuration for DSpace)

• Optional or Advanced Configuration Settings - contain other more advanced settings that are optional in the dspace.cfg configuration file.

  Info
  Much of the DSpace configuration has been moved to discrete configuration files related to specific functionality and is documented in subsequent sections of this document.

The full table of contents follows:

...

As most of these configurations are detailed in other areas of the DSpace documentation (see links above), this section concentrates primarily on the "*.cfg" configuration files (namely dspace.cfg and local.cfg).

...

Configuration File Syntax

We will use the dspace.cfg as our example for input conventions used throughout the system. These same input conventions apply to all DSpace *.cfg files.

...

This ability to include other files is also possible with the local.cfg file, should you want to subdivide your localized settings into several locally specific configuration files.

Update Reminder

...

Why are there multiple copies of some config files?

It is important to remember that there are * multiple dspace.cfg multiple copies of each configuration files in serveral places after an installation of DSpace. * The only two you should notice The primary ones to be aware of are:

1. The "source" file that is found configuration file(s) are found under in [dspace-source]/dspace/config/ or subdirectories.  This also includes the [dspace-source]/local.cfg
2. The "runtime" configuration file(s) that is are found in [dspace]/config/dspace.cfg

The

...

DSpace server (webapp) and command line programs only look at the runtime configuration file

...

(s).

When you are revising/changing your configuration values, it

...

may be tempting to only edit the runtime file. DO NOT do this.

...

Whenever you rebuild DSpace, it will "reset" your runtime configuration to whatever is in your source directories (the previous runtime configuration is copied to a date suffixed file, should you ever need to restore it).

Instead, we recommend to always make the same changes to the source version of

...

the configuration file in addition to the runtime file.

...

In other words, the source and runtime files should always be identical

...

/ kept in sync.

One way to To keep the two files in synchronization , you can is to edit your files in [dspace-source]/dspace/config/ and then you would run the following commands to rebuild DSpace and install the updated configs:

cd [dspace-source]/dspace/
mvn package
cd [dspace-source]/dspace/target/dspace-installer 
ant update_configs

This will copy the source dspace.cfg (along with other configuration files ) into the runtime ([dspace]/config) directory.  Another option to manually sync the files by copying them to each directory.

Please note that there are in fact two options available, choose whichever you prefer :-additional "ant" commands to help with configuration management:

• "ant update_configs" ==> Moves existing configs in [dspace]/config/ to *.old files and replaces them with what is in [dspace-source]/dspace/config/

...

As of DSpace 3.0, we now provide a 6, it is now possible to easily override default DSpace configurations (from dspace.cfg or modules/*.cfg files) in your own local.cfg configuration file.

A example [dspace-source]/build.properties as an easy means of configuration a subset of properties before you build DSpace (by running "mvn package" or similar).  Any properties set in this build.properties file will be automatically copied over to your final dspace.cfg file as part of the Maven build process.

Users/Developers may also choose to copy the build.properties under a different name for different environments (e.g. development, test & production), and choose which environment to build DSpace for by passing a "-Denv" (environment) flag to the Maven build process (e.g. "mvn package -Denv=test" would build DSpace using a custom "test.properties" file).

Here's a basic example of how build.properties (or any *.properties) file may be used to simplify installation & development:

1. A developer or user downloads a copy of DSpace to build & install
2. He/She can edit the [dspace-source]/build.properties to specify the very basic settings for building & installing DSpace
   
   1. OR, alternatively he/she can copy/rename the "build.properties" to a different "*.properties" file & edit it.  For example, you could choose  to create a separate properties file for each environment (dev.properties, test.properties, prod.properties)
3. He/She can then build the DSpace Installation Package using the *.properties file they choose
   
   1. Running simply "mvn package" will always use the default "build.properties" settings.
   2. Passing in the "-Denv" (environment) flag, will cause the build process to use a custom properties file.  Some examples:
      
      1. "mvn package -Denv=test" would build DSpace using a custom file named [dspace-source]/test.properties
      2. "mvn package -Denv=local" would build DSpace using a custom file named [dspace-source]/local.properties
      3. "mvn package -Denv=john" would build DSpace using a custom file named [dspace-source]/john.properties
4. No matter which build options are used, the values in the enabled properties file will be automatically copied over to your [dspace-source]/dspace/target/dspace-[version]-build/dspace.cfg file in the DSpace Installation Package. That way they can be installed using the appropriate Apache Ant command (see Installing DSpace for all the details of the full install.)

...

local.cfg.EXAMPLE is provided wtih DSpace. The example only provides a few key configurations which most DSpace sites are likely to need to customize. However, you may add (or remove) any other configuration to your local.cfg to customize it as you see fit.

To get started, simply create your own [dspace-source]/local.cfg based on the example, e.g.

cd [dspace-source]
cp local.cfg.EXAMPLE local.cfg

You can then begin to edit your local.cfg with your local settings for DSpace. There are a few key things to note about the local.cfg file:

• Override any default configurations: Any setting in your local.cfg will automatically OVERRIDE a setting of the same name in the dspace.cfg or any modules/*.cfg file.  This also means that you can copy ANY configuration (from dspace.cfg or any modules/*.cfg file) into your local.cfg to specify a new value.
  
  • For example, specifying dspace.url in local.cfg will override the default value of dspace.url in dspace.cfg.
  • Also, specifying oai.solr.url in local.cfg will override the default value of oai.solr.url in config/modules/oai.cfg
• Configuration Syntax:The local.cfg file uses the Apache Commons Configuration Property file syntax (like all *.cfg files) . For more information see the section on Configuration File Syntax above.
  
  • This means the local.cfg also supports enhanced features like the ability to include other config files (via "include=" statements).
• Override local.cfg via System Properties: As needed, you also are able to OVERRIDE settings in your local.cfg by specifying them as System Properties or Environment Variables.
  • For example, if you wanted to change your dspace.dir in development/staging environment, you could specify it as a System Property (e.g. -Ddspace.dir=[new-location]). This new value will override any value in both local.cfg and dspace.cfg.

When you build DSpace (e.g. mvn package), this local.cfg file will be automatically copied to [dspace]/config/local.cfg.  Similar to the dspace.cfg, the "runtime" configuration (used by DSpace) is the one in [dspace]/config/local.cfg. See the Why are there multiple copies of some config files? question above for more details on the runtime vs source configuration.

Here's a very basic example of settings you could place into your local.cfg file (with inline comments):

# This is a simple example local.cfg file which shows off options
# for creating your own local.cfg

# This overrides the default value of "dspace.dir" in dspace.cfg
dspace.dir = C:/dspace/

# This overrides the default value of "dspace.baseUrl" in dspace.cfg
dspace.baseUrl = http://dspace.myuniversity.edu

# The overrides the default "dspace.url" setting it to the same value as my "baseUrl" above
dspace.url = ${dspace.baseUrl}

# If our database settings are the same as the default ones in dspace.cfg, 
# then, we may be able to simply customize the db.username and db.password
db.username = myuser
db.password = mypassword

# For DSpace, we want the LDAP and Password authentication plugins enabled
# This overrides the default AuthenticationMethod in /config/modules/authentication.cfg
# Since we specified the same key twice, these two values are appended (see Configuration File Syntax above)
plugin.sequence.org.dspace.authenticate.AuthenticationMethod = org.dspace.authenticate.LDAPAuthentication
plugin.sequence.org.dspace.authenticate.AuthenticationMethod = org.dspace.authenticate.PasswordAuthentication

# For the example, we'll override the default oai.url in /config/modules/oai.cfg
oai.url = ${dspace.baseUrl}/oaipmh

# We'll also override the default oai.solr.url in /config/modules/oai.cfg
# Notice here we're referencing a configuration (solr.server) that only exists in dspace.cfg
# This is allowed. Your local.cfg can reference configs from other *.cfg files.
oai.solr.url=${solr.server}/oaipmh

# Finally, this local.cfg also supports adding "include=" statements, to include
# additional local configuration files.
# In this example, a local-rest.cfg and local-curate.cfg (in the same directory)
# will automatically be included as part of this local.cfg.
# This allows you to subdivide you local configs in as many (or few) config files
# as you desire.
include = local-rest.cfg
include = local-curate.cfg

The dspace.cfg Configuration Properties File

The dspace.cfg contains basic information about a DSpace installation, including system path information, network host information, and other like items.  It is the primary default configuration file for DSpace, used by DSpace when it is actively running.  However, as noted above, any of these default configurations may be overridden in your own local.cfg configuraiton file.

In ordinary use, this file is assumed to be [dspace]/config/dspace.cfg.  If you define a system property -Ddspace.configuration=/some/path/to/a/file then that file will be used instead.

...