The Fedora web-application supports several deploy-time, system-level configuration options. These configuration elements are set via the definition of System Properties.
Deployments
Four means of deploying Fedora have been verified
- Tomcat 9 servlet container
- Jetty 9 servlet container
- Maven jetty:run plugin - for testing
- One-Click Run - for testing
Each of these deployment approaches has its own way of setting System Properties.
Tomcat 9
On Debian Linux systems, the typical way of setting System Properties is to update the following file:
/etc/default/tomcat9
Within that file, new properties can be added per the example below:
JAVA_OPTS="${JAVA_OPTS} -Dfcrepo.home=/mnt/fedora-data"
Additional information regarding the configuration of System Properties in Tomcat 9 can be found here.
Windows notes
Alternatively on Windows systems you can set the following file:
CATALINA_BASE/bin/setenv.bat (windows)
Within that file, new properties can be added per the example below:
set CATALINA_OPTS=%CATALINA_OPTS% -Dfcrepo.home=/mnt/fedora-data
Jetty 9
On Debian Linux systems, one way of setting System Properties is to update the following file:
/etc/default/jetty
Within that file, new properties can be added per the example below (note the use of JAVA_OPTIONS instead of JAVA_OPTS):
JAVA_OPTIONS="${JAVA_OPTIONS} -Dfcrepo.home=/mnt/fedora-data"
Additional information regarding the configuration of System Properties in Jetty 9 can be found here.
Windows notes
Alternatively on Windows systems you can set the following file:
{JETTY_DIST}/start.ini
Within that file, new properties can be added per the example below:
--exec -Dfcrepo.home=/mnt/fedora-data Maven jetty:run
System Properties can be set when using the Maven jetty:run plugin by passing them per the example below:
mvn -Dfcrepo.home=/mnt/fedora-data jetty:run
One-Click Run
One option is to use the "one click" application, which comes with an embedded Jetty servlet. This can be optionally built by running:
mvn install -pl fcrepo-webapp -P one-click
and can be started by either double-clicking on the jar file or by running the following command:
java -jar ./fcrepo-webapp/target/fcrepo-webapp-<version>-jetty-console.jar
By default, a Fedora home directory, fcrepo, is created in the current directory. You can change the default location by passing in an argument when starting the one-click, e.g.:
java -Dfcrepo.home=/data/fedora-home -jar fcrepo-webapp-6.0.0-SNAPSHOT-jetty-console.jar
Configuration Elements
Two ways of passing configuration: property file or command-line argument
Before we enumerate the configurable properties and their defaults it should be noted that there are two ways of passing this configuration to your Fedora instance. As noted above you can use the -D<param.name>=<param.value> syntax. Optionally you can pass all the parameters at once by putting them in a java properties file and passing the path of the file as a command line argument. For example, to pass two parameters at once using a property file, by file simply create a file with any arbitrary name and path such as "my_fcrepo.properties". Then add your parameters as you would in any Java properties file, like this:
# add any number of properties below fcrepo.home: my_fcrepo_home_directory fcrepo.autoversioning.enabled: true
Then pass these parameters to Fedora like this:
java -Dfcrepo.config.file=my_fcrepo.properties -jar fcrepo-webapp-6.0.0-SNAPSHOT-jetty-console.jar
IMPORTANT NOTE ON PROPERTY PRECEDENCE
You may pass parameters simultaneously via the command-line params as well as by property file. However, please keep in mind that command-line parameter values will overwrite any values defined in your properties file. So using the above mentioned property file as an example
java -Dfcrepo.config.file=my_fcrepo.properties -jar fcrepo-webapp-6.0.0-SNAPSHOT-jetty-console.jar
will have an fcrepo.home value of "my_fcrepo_home_directory" whereas
java -Dfcrepo.home=overridden_fcrepo_home -Dfcrepo.config.file=my_fcrepo.properties -jar fcrepo-webapp-6.0.0-SNAPSHOT-jetty-console.jar
will have an fcrepo.home value of "overridden_fcrepo_home".
Table of Configurable Properties
There are a number of configuration elements that can be optionally be set when starting the Fedora web-application, noted below within brackets: <>.
fcrepo4 references purged from pom files? | Property Name | Description | Default Value | Constraints |
---|---|---|---|---|
fcrepo.home | The home directory for all Fedora generated output and state. Unless otherwise specified, all logs, metadata, binaries, and internally generated indexes, etc. | <cwd/fcrepo-home> | ||
fcrepo.config.file | The path to a properties file containing any property name value pair specified below. If the file does not exist, Fedora will silently ignore it. Important note: if you create the properties file in the default location (specfied in the next column) know that any definition of fcrepo.home in that file will be ignored. The fcrepo.home property will be read from the properties file only when the following two conditions are present: 1) you are using the -Dfcrepo.config.file=... option and 2) you have not specified -Dfcrepo.home=... | <fcreop.home>/config/fcrepo.properties | ||
fcrepo.spring.configuration | The path to the spring configuration. While it is generally not recommended to use this option, in some cases you may need to make adjustments to the default spring configuration. This can be set to a path (relative to the current working directory or absolute) to which Fedora repository content will be written. | <classpath:/config/spring/fcrepo-config.xml> | file:/path/to/fcrepo-config.xml | |
java.io.tmpdir | This specifies the directory for writing temp files. You may need to set this property to a larger disk/filesystem to upload large files, particularly on Linux where /tmp is sometimes on a small partition. | </tmp on Linux, $TMPDIR on MacOSX, and %TEMP% on Windows> | ||
fcrepo.dynamic.jms.port | This specifies the ports used by the embedded JMS-based message broker for OpenWire protocol. Note: If you have multiple instances of Fedora running, this property must be set to avoid messaging port conflicts. | 61616 | ||
fcrepo.dynamic.stomp.port | This specifies the ports used by the embedded JMS-based message broker for STOMP protocol. Note: If you have multiple instances of Fedora running, this property must be set to avoid messaging port conflicts. | 61613 | ||
fcrepo.activemq.directory | Contains the reliable messaging information maintained by ActiveMQ. | <fcrepo.home>/data/ActiveMQ/kahadb | ||
fcrepo.external.content.allowed | This provides the path to a file defining a list of allowed external binary content paths. If this parameter is not provided, then clients will be disallowed from creating external binary resources. See the external content allowed paths configuration for more details. | </path/to/allowed.txt> | ||
fcrepo.autoversioning.enabled | This results in every change to Fedora resources being persisted in the OCFL "mutable-head" extension, as opposed in a new OCFL version. | true | ||
Database (more info) | ||||
fcrepo.db.url | This parameter allows you to set the database connection url. In general the format is as follows: jdbc:<database_type>://<database_host>:<database_port>/<database_name> Fedora currently supports H2, PostgresQL 12.3, MariaDB 10.5.3, and MySQL 8.0 So using the default ports for the supported databases here are the values we typically use:
MariaDB: jdbc:mariadb://localhost:3306/fcrepo If you wish to configure h2, there are a variety of options detailed in the H2 Reference docs. | By default Fedora uses an embedded H2 database. | ||
fcrepo.db.user=<database_username> - | The database username | None - H2 doesn't require it | ||
fcrepo.db.password=<database_password> | The database password | None - H2 doesn't require it | ||
fcrepo.db.connection.checkout.timeout | The amount of time to wait before assuming checkout failed in milliseconds | 10000 | ||
fcrepo.db.connection.idle.test.period | The amount of time in seconds between idle connection tests. | 300 | ||
fcrepo.db.connection.test.on.checkout | Specifies whether or not to test a database connection on checkout. | true | ||
Messaging | ||||
fcrepo.jms.baseUrl | This specifies the baseUrl to use when generating JMS messages. You can specify the hostname with or without port and with or without path. If your system is behind a NAT firewall you may need this to avoid your message consumers trying to access the system on an invalid port. If this system property is not set, the host, port and context from the user's request will be used in the emitted JMS messages. | <http://localhost:8080/fcrepo/rest> | ||
fcrepo.velocity.runtime.log | The HTML template code uses Apache Velocity, which generates a runtime log called velocity.log . By default this is placed inside fcrepo.home , but it is possible to override the location to have it written to an alternate location. | <$fcrepo.home/velocity.log> | ||
Persistence | ||||
fcrepo.session.timeout | This sets the duration for which a transaction will stay active before auto-rolling back. Defaults to 180000 ms, or 3 minutes. | 180000 | ||
fcrepo.persistence.defaultDigestAlgorithm | This sets the default digest algorithm on ingested binary resources. Valid values: [sha512|sha256] | sha512 | ||
OCFL | ||||
fcrepo.ocfl.root | Sets the root directory of the OCFL. | <fcrepo.home>/data/ocfl-root | ||
fcrepo.ocfl.temp | Sets the temp directory used by OCFL. | <fcrepo.home>/data/ocfl-temp | ||
fcrepo.ocfl.staging | Sets the staging directory used by OCFL. | <fcrepo.home>/data/ocfl-staging | ||
fcrepo.ocfl.reindex.failOnError | Indicate whether reindexing should fail on error. | true | ||
fcrepo.ocfl.reindex.batchSize | The size of batches of OCFL ids used by the reindexer. | 100 | ||
fcrepo.ocfl.reindex.threads | The number of threads to be used by the reindexer. | -1 | ||
fcrepo.storage | The type of backend storage format: Valid values: ocfl-fs, ocfl-s3 | ocfl-fs | ||
OCFL/S3 Configuration (more info) | ||||
fcrepo.ocfl.s3.bucket | The s3 bucket to host the OCFL. | |||
fcrepo.ocfl.s3.prefix | A prefix can be provided to partition the S3 bucket so that Fedora uses only a portion of the bucket. | |||
fcrepo.aws.region | The default region used by the client. The region codes found in the table provided by Amazon's documentation are all available, such as "us-east-2", "eu-west-1", etc. | us-east-1 | ||
fcrepo.aws.access-key | The AWS access key | |||
fcrepo.aws.secret-key | The AWS secret key |