Throughout this article, the string
cms-directory refers to the installation directory of the entire Sophora application. The central configuration file of each Sophora Server is called sophora.properties and is located within the config folder of the sophora directory. Subsequently, an exemplary configuration is displayed:
# Installation directory of the Sophora Server
sophora.home=/cms/ts/sophora
# RMI ports
sophora.rmi.servicePort=1398
sophora.rmi.registryPort=1399
sophora.remote.jmsbroker.port=1397
# For fall-back and Sophora Staging Servers you have to specify the Sophora Primary Server server here
sophora.remote.jmsbroker.host=194.113.141.96
sophora.replication.slaveHostname=server1
# Type of the Sophora Server. Possible values are "cluster", "master" (Sophora Primary Server), "slave" (meaning the fall-back Sophora Replica Server) and "stagingslave" (Sophora Staging Server)
sophora.replication.mode=stagingslave
# Vmargs for the java process
vmargs=-XX:+UseParallelGC -XX:+UseParallelOldGC -Xss512K -Xmn640M -Xms2G -Xmx2G -XX:-UseGCOverheadLimit
Configuration Parameters of the Sophora Server
The following tables list all valid parameters for the sophora.properties file.
Messaging and Interfaces
| Parameter | Description |
|---|---|
sophora.http.proxy.host | HTTP proxy host address for the RemoteDataManager (See the section on Java network properties for an alternative solution) |
sophora.http.proxy.port | HTTP proxy port for the RemoteDataManager |
sophora.http.proxy.username | HTTP proxy username for the RemoteDataManager |
sophora.http.proxy.password | HTTP proxy password for the RemoteDataManager |
sophora.http.proxy.noProxy | List of excluded host names. Default is "127.0.0.1,localhost" |
sophora.jmx.enabled | Activate the JMX interface: true or false |
sophora.jmx.username, sophora.jmx.password | Username and password for the JMX interface (optional). If no username and password are given, no authentication is required to use the JMX interface. |
sophora.local.jmsbroker.host,sophora.remote.jmsbroker.host | Use sophora.local.jmsbroker.host to specify the host name or IP address of the embedded JMS Broker. sophora.remote.jmsbroker.host refers to the host name or IP address of its Sophora Primary Server.On Sophora Staging Servers, sophora.remote.jmsbroker.host must be configured. But as Sophora Staging Servers do not have an embedded JMS Broker, the configuration of sophora.local.jmsbroker.host is not necessary. Default is localhost. |
sophora.local.jmsbroker.port,sophora.remote.jmsbroker.port | Use sophora.local.jmsbroker.port to specify the port of the actual configured Sophora Server and sophora.remote.jmsbroker.port to specify the port of the Sophora Server to which this server is connected.On Sophora Staging Servers, only the property sophora.remote.jmsbroker.port is required. As Sophora Staging Servers do not have an embedded JMS Broker, the configuration of sophora.local.jmsbroker.port is not necessary.Default is 1197. |
sophora.remote.api.http.address | IP address to bind the HTTP port to |
sophora.remote.api.http.port | HTTP port to access the content manager API via HTTP. If this property is blank, the port will be calculated as follows: sophora.remote.api.http.port = sophora.rmi.registryPort - 3. Thus, by default this is 1196. |
sophora.remote.api.https.enabled | Defines whether the HTTPS port is enabled or not (Default: false). For client connection using HTTPS see here. |
sophora.remote.api.https.port | HTTPS port to access the content manager API via HTTPS. If this property is blank, the port will be calculated as follows: sophora.remote.api.https.port = sophora.rmi.registryPort - 4. Thus, by default this is 1195. |
sophora.remote.api.https.keyPassword | Password for the key in the keystore (Default: sophora) |
sophora.remote.api.https.keyStore | The file name for the keystore. This file must be located in the directory sophora.home/config. (Default: "sophora.keystore") |
sophora.remote.api.https.password | Password for the keystore (Default: sophora) |
sophora.remote.api.external.hostname | An external hostname that points to this server and should be used by clients to connect to the server. Clients switching their connection to this server will prefer the external connection URL if defined unless they are configured to only use internal connections The 3 external properties are intended to be used when the server is in various networks and uses internal connections for server-to-server communication (e.g in a Kubernetes setup) and external connections for clients (e.g. through ingresses). The external properties are not set by default. Important: The external properties are new in server version 4.1.0 and are only taken into account by Sophora Clients of version 4.2.0 or newer. Older clients can still be used but will ignore these external settings. |
sophora.remote.api.external.port | Port counterpart for sophora.remote.api.external.hostname. |
sophora.remote.api.external.protocol | Protocol counterpart for sophora.remote.api.external.hostname.The protocol can be different from the servers preferred protocol. You can use SSL termination in front of a Sophora Server running on http. |
sophora.rmi.registryPort | RMI registry port. Default is 1199. |
sophora.rmi.servicePort | RMI port. Default is 1198. |
Server Cluster and Replication
| Parameter | Description |
|---|---|
sophora.cluster.readAnywhere.available | En- or disables the Sophora Replica Server's availability for readAnywhere connections. Default value is trueChange the state in JMX, go to ContentManager-MBean and you will see the current value for ReadAnywhereAvailable. There is also an operation toggleReadAnywhereStatus() to toggle the value. |
sophora.replication.delivery.<index>.groups | Associates the delivery to at least one group (see sophora.replication.delivery.<index>.url). Multiple groups are associated using a comma separated list of group names (an example is given below). |
sophora.replication.delivery.<index>.url | URL of the delivery web app that is bound to this server. Hereby, <index> is a key to associate certain delivery groups (see sophora.replication.delivery.<index>.groups). For each URL there has to be an assigned group with the same <index>. |
sophora.replication.ignoreWebsites | Comma separated list of websites' UUIDs. Only applicable if sophora.replication.mode=stagingslave. A Sophora Staging Server ignores documents located at the given websites. The documents are not transferred to the Sophora Staging Servers' repositories. |
sophora.replication.maxQueueSizeForAvailableState | Number of events in the replication queue before the Sophora Replica Server is marked as unavailable. Default: 500 |
sophora.replication.maxSystemDocumentVersionsSyncCnt | Limits the number of document versions of system and structurenode documents which are sent to the Sophora Replica Server, when the Sophora Replica Server synchronises its content with a Sophora Primary Server. Default: 10. Available since 4.27.0. |
sophora.replication.maxVersionsSyncCnt | Limits the number of document versions per document which are sent to the Sophora Replica Server, when the Sophora Replica Server synchronises its content with a Sophora Primary Server. Default: 10000 |
sophora.replication.mode | Type of the server. Possible values are none, cluster, master (Sophora Primary Server), slave (meaning the fall-back Sophora Replica Server) and Sophora Staging Server. With none, the Server has no connection to other servers but works as a standalone server. By using the replication mode cluster it is mandatory to specify the concrete mode via the system property clusterMode. Valid values for the system property are: master, slave and open (the Sophora Server which starts first becomes the Sophora Primary Server). |
sophora.replication.restartDate | Date to start the synchronisation at. Format is "yyyy.MM.dd HH:mm". Only applicable if sophora.replication.mode=stagingslave or =slave. |
sophora.replication.slaveHostname | Host name of the server. This name is used for the communication between Sophora Servers. If this property is left blank, the host name will be determined automatically. It is mandatory to specify the hostname in a cluster server. |
sophora.replication.syncQueueLimit | Maximum queue size (in bytes) to be held in the central memory. When this value is reached, the synchronisation waits until the Sophora Replica Server has removed enough messages from the queue so that the queue size falls below this threshold again. |
sophora.replication.userName, sophora.replication.password | Username and password for JMS queues. If no username and password are provided, the default values (userName=sophora and password=jms) are taken. |
Document Related Settings
| Parameter | Description |
|---|---|
sophora.autoPublish.legacyMode | This must be set to true if automated publishing using the released state is used. This should only be set for legacy installations. If set to false, automated publishing must be done by setting the "Publish at" property and publishing the document.In previous releases of Sophora, a document could automatically be published at a future date by settings the "Publish at" property and then releasing the document. The default is false. |
sophora.autoPublish.username | Name of the user that will appear as the one who triggered a document's automated publication. Needs to be a valid user with corresponding publish permissions upon the node types that might be published this way. Read the user guide's instructions on how users can schedule this automatic process. The default value is admin. However, it is advisable to alter this property to identify corresponding documents easily, e.g. to search for them or find log file entries. If you set this property to the special value [LAST_MODIFIER] the automated publication is done by the last modifier of the document. In this way the document is published by the same user who has released the document.There's an internal thread that is run periodically which looks for scheduled publications. |
sophora.cleanOfflineFilter.properties | Comma separated list of properties that should be removed from documents when they are set offline. This ensures that future publishing does not conflict with these historical values. |
sophora.deleteDocuments.archive | Determines whether documents are moved to the archive repository or are removed completely. Only relevant if sophora.archive.enabled=true. Default value is true. More detailed information about how Sophora handles and preserves deleted documents can be found in the documentation on deleted documents and trash. |
sophora.deleteDocuments.blockSize | Sets the maximum number of deleted documents that should be processed in one run. Default 300. |
sophora.deleteDocuments.cronTriggerExpression | Cron expression defining when to run the job for deleted documents. Default 0 15 * * * ? (Every hour, a quarter past the full hour) |
sophora.deleteDocuments.enabledOnStartup | Enable the removal job for deleted documents when starting the server? Possible values are true and false. Default is true. |
sophora.deleteDocuments.minimumAgeDays | Specifies the minimum age (in days) of deleted documents to be processed by the worker job. The Sophora Primary Server needs deleted documents for synchronizing temporary unavailable Sophora Replica Servers. Therefore, the minimum age should not be set too small. |
sophora.deleteProposals.afterDays | Number of days deleted proposals are retained in the repository. Deleted proposals are not visible to the user but are needed for synchronizing Sophora Replica Servers to the Sophora Primary Server. Default: 30 |
sophora.documentManager.childNodeIdPropertyNames | Comma-separated list of property names. Upon loading and saving a document, all childnodes are scanned if they have such a property defined in their CND without a value assigned yet. If so, they will get assigned a random long number. This will be done for the properties sophora:childNodeId and sophora-epg:childNodeId regardless of this configuration. Properties of mix-ins cannot be set in this way. |
sophora.documentManager.clone.additionalTags | Space-separated list of tags to be added to a cloned document after cloning. Can be empty. Default value: "kopie". |
sophora.documentManager.generateEvenIds | Create document IDs only with even numbers: true or false. Default: true |
sophora.documentManager.generateIdsWithMinusAsSuffix | Create document IDs with a minus as ID stem suffix: true or false. Default: false |
sophora.documentManager.thumbnail.big.maxHeight | Maximum height of big thumbnails, e.g. for tooltips of image documents. Default 300. |
sophora.documentManager.thumbnail.big.maxWidth | Maximum width of big thumbnails, e.g. for tooltips of image documents. Default 300. |
sophora.documentManager.thumbnail.maxHeight | Maximum height of thumbnails in the light box. Default 100. |
sophora.documentManager.thumbnail.maxWidth | Maximum width of thumbnails in the light box. Default 100. |
sophora.cache.thumbnail.cleanup.afterDays | Defines the maximum time since a thumbnail was created before beeing marked for deletion by the cleanup job. Default: 60Setting this to a negative number or 0 will deactivate the thumbnail cleanup.Available since 4.26.0. |
sophora.cache.thumbnail.cleanup.cron | Cron expression defining when the file based thumbnail store (cache) should be cleaned. Default: 0 0 3 * * ? Available since 4.26.0. |
sophora.documentTimingActions.batchLimit | Sets the batch limit for document timing actions (default: 10000). The batch limit is the maximum number of documents which are handled in a single run for each script. |
sophora.documentTimingActions.cronTriggerExpression | This cron expression defines when the server-side timing scripts should be executed (more detailed information about the timing action can be found in the documentation about Script managed Sophora extensions). The format and construction of a cron expression is given in the Quartz documentation or use the Cron Maker to generate the expression you need. Some examples: 0 0 3 * * ? (every night at 3 AM) or 0 0 0/1 * * ? (every full hour) When processing more documents per run as the value in the 'batchLimit' is, the timing script should run only once per day |
sophora.documentUuidProvider.servletPath | The server can resolve document UUIDs from URLs that a delivery generated for this document. This is mainly used by the DeskClient and MobileClient to support the "Open document from URL" function. Since however the URLs are generated by the delivery the server can't provide this function on its own but has to ask a delivery. The property sophora.documentUuidProvider.servletPath controls the path to the delivery's servlet that offers this functionality, the IdForUrlServlet. By default this property is set to system/servlet/idForUrl.servlet but you can adjust this to whatever path you assigned to the IdForUrlServlet in your webapp's web.xml.See also the section on servlets from the delivery configuration. If you're not using the delivery stack you can have your own HTTP endpoint to fill in for the IdForUrlServlet:
|
Repository and Archive
| Parameter | Description |
|---|---|
sophora.archive.activeOnStartup | Start the archival storage on the server's start-up. Default is true. |
sophora.archive.checkAllDocumentsForOldVersions | Check all documents for old versions in a background thread. Default is true. When set to false, only currently modified documents are checked. |
sophora.archive.deleteOldVersionsAfterDays | When the age of an archive version exceeds this amount of days this version will be removed from the archive. A version's age is based on its creation date. The default value is 0, meaning the versions are not removed at all, i.e. kept for good. |
sophora.archive.enabled | Activates the archival storage if set to true. A second repository is created in the directory repository_archive. Older versions of documents are moved to the new repository. Default true. |
sophora.archive.maxVersionsToRetain | Defines the maximum number of document versions that should be kept in the repository. Default 20. This is as well the minimal value. If configured with a smaller value, 20 is used instead. |
sophora.archive.preserveNumberOfVersionsInArchiveRepository | The archiving processes keep this number of versions for all documents, regardless how old the versions are. The default value is 0, meaning all versions can be removed by archive worker. |
sophora.archive.versionsBatchSize | Maximum number of versions to be archived within a single batch. Default is 500. If configured to 0 or below, default is used instead. |
sophora.repository.defaultNodeTypes | URL to the sophora.cnd file that should be imported at the server's start-up. An empty string specifies that no CND should be imported. |
sophora.repository.language | The repository's language. If a repository is initialised from scratch, the descriptors of basic properties and system documents will be set in the given language. Currently, Sophora supports German and English, whereas German is the default language. Possible values for this property are en (for English) and de (for German). |
sophora.archive.byNodeType.<key>.nodeType | Specifies a node type for the given <key>. With this property it is possible to configure the archive properties for single node types. Overwriting archive settings per node type requires a Sophora Server in version 4.0.3 or newer. |
sophora.archive.byNodeType.<key>.deleteOldVersionsAfterDays | Similar to sophora.archive.deleteOldVersionsAfterDays but only affecting one node type. Which node type is related to is described with the property sophora.archive.byNodeType.<key>.nodeType |
sophora.archive.byNodeType.<key>.preserveNumberOfVersionsInArchiveRepository | Similar to sophora.archive.preserveNumberOfVersionsInArchiveRepository but only affecting a node type. Which node type is related to is described with the property sophora.archive.byNodeType.<key>.nodeType |
sophora.archive.byNodeType.<key>.maxVersionsToRetain | Similar to sophora.archive.maxVersionsToRetain but only affecting a single node type. As opposed to sophora.archive.maxVersionsToRetain samller values than 20 are allowed. Which node type is related to is described with the property sophora.archive.byNodeType.<key>.nodeType |
Example of default configuration and custom configuration of a node type.
sophora.archive.enabled=true
sophora.archive.deleteOldVersionsAfterDays=3
sophora.archive.preserveNumberOfVersionsInArchiveRepository=200
sophora.archive.byNodeType.story.nodeType=sophora-content-nt:story
sophora.archive.byNodeType.story.deleteOldVersionsAfterDays=5
sophora.archive.byNodeType.story.preserveNumberOfVersionsInArchiveRepository=100
sophora.archive.byNodeType.story.maxVersionsToRetain=12
User Authentication
| Parameter | Description |
|---|---|
sophora.authenticate.checkForIncorrectLogins | Determines whether the server checks for invalid logins (if a user enters his password incorrectly several times) and locks the account after this number of failed login attempts (default: false). This property is accessible via JMX |
sophora.authenticate.enableUserLogin | Determines whether users are allowed to log in to the server (default: true). Admin users are always allowed to log in, even if this property is set to false. |
sophora.authenticate.incorrectLoginCount | Defines, how many times a user may enter a wrong password before the account is locked (default: 3). To reset the failed login attempts of a user, you can open the admin area of the user and reset the field Incorrect logins to 0. |
sophora.authenticate.user.ignoreUppercase | If set to true, the server ignores the case of user names during login. In addition, the creation of users with an uppercase user name is prohibited, while already existing users with uppercase characters cannot log in to the Sophora Server.Default is false.NB: the Sophora Importer will keep the case of any user names found in Sophora XML import files. For example, if an imported document is added to a proposal section, the user name given in the <sender> element is kept as-is. |
Solr and Lucene
| Parameter | Description |
|---|---|
sophora.lucene.maxClauseCount | Set the maximum number of boolean clauses permitted in lucene queries. (Default: 10000) |
sophora.solr.embedded.enabled | Start a Solr web application embedded in the server process (default: true). |
sophora.solr.hostname | HTTP host of the Solr instance. When an embedded Solr is started, the regular HTTP host name (sophora.remote.api.http.address) is used. (Default: localhost) |
sophora.solr.indexer.enabled | Automatically create indexes and send changed documents to the configured Solr instance (default: true). |
sophora.solr.iquerysearch.enabled | Specifies whether the Solr index should be used as the default search engine for all IQuery search operations. (Default: true) |
sophora.solr.password | Password for the basic authentication used by the indexer and by the embedded Solr instance. (Default: solr) |
sophora.solr.port | HTTP port of the Solr instance. When an embedded Solr is started, the regular HTTP port (sophora.remote.api.http.port) is used. (Default: 1196) |
sophora.solr.username | User name for the basic authentication used by the indexer and by the embedded Solr instance. (Default: solr) |
sophora.solr.indexer.nonDefaultJobThreads | The number of threads to use in a thread pool for all solr indexing jobs except for the default and live solr index. (Default: -1. A value of -1 will evaluate to the number of processor cores).Note: This affects the jobs used for determining which documents to re-index. These documents are then gathered in an indexing queue per core. The number of threads working of these queues however does not depend on this setting. |
Solr Cloud
| Parameter | Description |
|---|---|
sophora.solr.cloud.enabled | If set to true, the external SolrCloud instance is used instead of the internal one. (Default: false) |
sophora.solr.cloud.zk-hosts | List of ZooKeeper hosts that are part of the Solr Cloud cluster. |
sophora.solr.cloud.username | Solr username if the Solr Basic Authentication Plugin is enabled |
sophora.solr.cloud.password | Solr password if the Solr Basic Authentication Plugin is enabled |
sophora.solr.cloud.connection-timeout | Solr connection timeout in ms. (Default: 15000) |
sophora.solr.cloud.socket-timeout | Solr socket timeout in ms. (Default: 120000) |
The SolrCloud parameters can only be used in combination with an upcoming Sophora addon (Sophora Indexing Service). Activating the SolrCloud using these parameters without using the addon is not possible and will result in misbehaviour.
URL Generation
| Parameter | Description | |
|---|---|---|
sophora.url.use-url-library | Wether the URL library from the Sophora webapp-framework should be used to compose or parse URLs for Sophora documents. If set to false, the configured deliveries are requested. (Default: true) | |
sophora.url.create-url-without-site-prefix | Wether the Sophora document URLs should contain the site prefix. (Default: false) | |
sophora.url.default-domain | The URL prefix that should be used as default when composing a URL. If the site has a configured URL, this prefix will be used instead. (Default: http://localhost) | |
sophora.url.image-service-active | Wether the Sophora Image Service is active and its URL component should be used for parsing and composing URLs for image documents. (Default: false) | |
sophora.url.image-service-domain | The URL prefix for the Sophora Image Service. (Default: http://localhost)Available in versions before 4.18.0 | |
sophora.url.image-service-default-domain | The default URL prefix for the Sophora Image Service. The value of this property is used, when the property imageUrl in the site of the image document isn't set. (Default: http://localhost)Available in version 4.18.0 and later |
Miscellaneous
| Parameter | Description |
|---|---|
sophora.cache.selectValues.refreshInterval | The time interval in seconds to run the cache refresh job; e.g. 60. Currently, this functionality is only used for select value fields, whose values are determined via XPath queries on documents (see documentation for administrators) |
sophora.configuration.document.externalId | Defines the configuration system document by its external ID (default: sophora.configuration.configuration). |
sophora.home | Workspace of the Sophora Server. This folder contains the subdirectories config, data, logs, repository, repository_archive. |
sophora.ibf.enabled | Enables the feature of Invertible Bloom Filters for efficient document count comparisons using the Advanced Admin Dashboard. This will slightly increase the memory usage of the server. (Default: false) |
sophora.loadCachesOnServerStart | |
sophora.mail.sender.username | The username is used to authenticate to the SMTP server. Used for the 'password lost' feature. |
sophora.mail.sender.password | The password is used with the user name to authenticate to the SMTP server. Used for the 'password lost' feature. |
sophora.mail.sender.email | The e-mail address that is used by the Sophora Server to send mails. Used for the 'password lost' feature. |
sophora.mail.sender.name | The name that is used as the real name by the Sophora Server to send mails. Used for the 'password lost' feature. |
sophora.mail.smtp.host | The host name of the SMTP server that is used to send mails. Used for the 'password lost' feature. |
sophora.mail.smtp.port | The port number of the SMTP server that is used to send mails. 25 is the default port number. Used for the 'password lost' feature. |
sophora.browser.url.password.* | Password to use for authentication of websites that are opened in browser tabs or in a preview. Use this feature as an alternative to writing the password directly below the username in the corresponding tab or preview document. Instead it is necessary to set an arbitrary key suffix in the document, which replaces the *. The whole key and its value can be defined in the server properties or in the configuration document. Example: The value 'previewpassword' as 'Password Configuration Key for URL' in your preview document will result in Sophora searching for the entry sophora.browser.url.password.previewpassword=mysecretpassword. |
vmargs | Parameters for the java process. |
sophora.cpuload.throttleLoad | Controls the load threshold for the throttle mode. The value is measured in cpu cores. |
sophora.changeRegistry.derby.connectionTimeout | The maximum time in milliseconds to connect to the derby database used by the change registry. If the time is elapsed and no connection could be made the server will shut down. The smallest applicable value for this property is 250ms. If this property is not set the connection timeout will default to 30000ms (30 seconds). If the server cant make a connection to the database while starting it might help to increase the timeout. |
Configuration options outside of the sophora.properties
The following environment variables can be used to configure the server:
| Environment Variable Name | Description |
|---|---|
SOPHORA_INITIALADMINUSERS_0_USERNAME and SOPHORA_INITIALADMINUSERS_0_PASSWORD | These parameters can be used to define the username and password of the users that will initially be created when starting the Sophora Server with an empty repository. The 0 is an index and can be counted up to create more than one user at the first startup. It is necessary that the index starts at 0 and that the following indices are counted up consecutively. A user with the username "admin" will always be created, even if these variables are set. When not overwritten by these parameters, the "admin" user's password will be "admin" initially. All users created using these variables will get the "admin" role. We recommend to only add functional users (e.g. a user for the Sophora Importer) using environment variables. This configuration has no effect on existing installations. |
Logging
Logging is done using logback. The server will take logging configuration from any logback.xml file within the class path. We propose to put your logback.xml inside your config directory next to your sophora.properties file.
The logback.xml can be used to activate profile logging. This is explained in more detail in the corresponding article.
Java network properties
In addition to these sophora specific configuration options, outgoing http connections can be configured using the java network properties. The full list is specified by the httpclient's api docs and contains all the properties:
- ssl.TrustManagerFactory.algorithm
- javax.net.ssl.trustStoreType
- javax.net.ssl.trustStore
- javax.net.ssl.trustStoreProvider
- javax.net.ssl.trustStorePassword
- java.home
- ssl.KeyManagerFactory.algorithm
- javax.net.ssl.keyStoreType
- javax.net.ssl.keyStore
- javax.net.ssl.keyStoreProvider
- javax.net.ssl.keyStorePassword
- http.proxyHost
- http.proxyPort
- https.proxyHost
- https.proxyPort
- http.nonProxyHosts
- http.keepAlive
- http.maxConnections
Some of these properties overlap with explicit sophora configuration options, e.g. sophora.http.proxy.host. We propose to not mix them in order to avoid side effects.
Repository
The content ist stored in a JCR repository, which itself uses a database system. The default database system is Derby. This is a good choice for testing, development and for the Sophora delivery servers. For productive systems, we recommend more feature rich database systems like MySQL or Oracle. (Please see our specs at https://subshell.com/sophora/specs/ for more details.)
To configure a database for an empty repository, a custom repository/repository.xml (and repository_archive/repository.xml) has to be created before the server is started for the first time. To change the configuration for an existing repository, the files repository/workspaces/default/workspace.xml and repository_archive/workspaces/default/workspace.xml also must be changed. Both files are created from the information in the repository.xml when the server is started for the first time.
The repository.xml contains two sections of configuration: one for the default workspace and one for the version storage. The workspace section is a template for the workspace.xml. When the workspace.xml already exists, changes in this section have no effect.
Both sections in the repository.xml contain two important configurations: the persistence configuration and the search index configuration. The persistence configuration determines the database type and connection parameters.
This is an example for a MySQL connection:
<PersistenceManager class="org.apache.jackrabbit.core.persistence.pool.MySqlPersistenceManager">
<param name="driver" value="com.mysql.jdbc.Driver"/>
<param name="url" value="jdbc:mysql://localhost:3306/sophora?autoReconnect=true"/>
<param name="user" value="sophora"/>
<param name="password" value="sophora"/>
<param name="bundleCacheSize" value="256"/>
...
</PersistenceManager>
This is an example for the search index configuration:
<SearchIndex class="org.apache.jackrabbit.core.query.lucene.SearchIndex">
...
<param name="respectDocumentOrder" value="false" />
<param name="minMergeDocs" value="10000" />
<param name="mergeFactor" value="5" />
<param name="cacheSize" value="10000" />
<param name="initializeHierarchyCache" value="false" />
</SearchIndex>
LevelDB persistence manager
LevelDB support will be removed in Sophora 5!
When using LevelDB the java process requires additional memory from the operating system. The additional memory depends on the size of the repository and can not be controlled by java parameters (e.g. -Xmx4G). Thus, the LevelDB should only be used on hardware with enough memory (approximately 10 to 16 GB for a live Sophora Staging Server).
On fresh installs of a Sophora system we encourage using Derby over LevelDB on Staging Servers.
A persistence manager as alternative to Derby is LevelDB.
LevelDB is a key-value storage library written at Google in C++ and runs on most unix platforms. It is integrated into Java via JNI.
LevelDB is not suited for binary data, thus it should only be used in combination with a binary data store. It can be configured as follows:
<PersistenceManager class="com.subshell.sophora.jackrabbit.LeveldbPersistenceManager">
<!-- Regular JackRabbit parameter -->
<param name="bundleCacheSize" value="1024" />
<!-- LevelDB parameter -->
<param name="cacheSizeMB" value="512" />
<param name="blockSizeKB" value="4" />
<param name="blockRestartInterval" value="16" />
<param name="compressionType" value="SNAPPY" />
<param name="createIfMissing" value="true" />
<param name="errorIfExists" value="false" />
<param name="maxOpenFiles" value="1000" />
<param name="paranoidChecks" value="false" />
<param name="verifyChecksums" value="true" />
<param name="writeBufferSizeMB" value="4" />
</PersistenceManager>
For details on properties see LevelDB-JNI-documentation.
The type of the persistence manager (Oracle, Derby, LevelDB) can be set only for an empty repository. Therefore, to create a Sophora Staging Server with a LevelDB, an empty repository must be configured and synchronized completely with a Sophora Primary Server.
Recommended Configuration for Productive Environments
The Sophora Server's default configuration is completely sufficient for test systems. However, when running a productive Sophora Server, you should have a look at our recommended settings for productive environments.
Directory Structure
The directory cms-directory always contains the following folders:
apps - the directory apps contains the software components used in your Sophora environment. Amongst others, these are the Apache, Tomcat and the Sophora Server libraries. For each additional Sophora component, as the Sophora Importer or the Sophora Indexer, a separate directory is created on the same level within the apps directory. These folders contain the components' configuration files.
The apps directory itself also contains symbolic links to the actual (release dependent) files or directories. Thus, you only have to edit these links when updating the server's or components' software. For example, the link cms-directory/apps/sophora-importer could refer to the directory cms-directory/apps/com.subshell.sophora.importer-4.0.0. Such links exist for every installed Sophora component.
sophora - this folder contains the actual instance of the current Sophora Server. It is basically the workspace of the Sophora Server installed in the apps directory. In addition, there is a link sophoraServerControl.sh -> ../apps/sophora/sophoraServerControl.sh which refers to the start and stop script of the actual Sophora Server (this link uses the sophora link from the apps directory).
webapps - the web applications configured for this Sophora Server are located here. Each web application has its own subdirectory (named after the application's context).
The following is a scheme of the entire directory structure:
--cms-directory
----apps
------apache-maven-3.3.9
------apache-tomcat-8.0.38
------com.subshell.sophora.component1-4.0.0 (e.g. importer)
------com.subshell.sophora.server-4.0.0
--------sophoraServerControl.sh
------sophora -> link to com.subshell.sophora.server-4.0.0
------sophora-component1 (e.g. sophora-importer) -> link to component
----sophora
------config
------data
------logs
------repository
------repository_archive
------solr
------sophoraServerControl.sh -> Symbolic link to ../apps/sophora/sophoraServerControl.sh
----webapps
------[contextName1]
--------cache
--------conf
--------logs
--------webapp
------[contextName2]
--------cache
--------conf
--------logs
--------webapp
----Sophora-component-1
----Sophora-component-2
Enable the Establishment of HTTPS Connections
This section describes how to configure Sophora to use HTTPS directly. As of Sophora 4.1.0 it is possible to operate Sophora behind a reverse HTTP proxy (e.g. Nginx) which can do SSL termination. In Sophora this can be configured using the properties
sophora.remote.api.external.hostname, sophora.remote.api.external.port and sophora.remote.api.external.protocol.In order to open an HTTPS port, the property sophora.remote.api.https.enabled must be set to true. Furthermore, a keystore file must be created and stored into the config directory which is located below the sophora directory (sophora/config). The default filename for the keystore is sophora.keystore, however it is possible to adjust the filename by setting the property sophora.remote.api.https.keyStore.
By default, the HTTPS port is set to the RMI port minus 4 (1195), but the port is also configurable with the property sophora.remote.api.https.port. You can specify the passwords of the keystore with the properties sophora.remote.api.https.password and sophora.remote.api.https.keyPassword.
The keystore must at least contain a key pair and may contain a certificate. If the DeskClient and other Sophora components should verify the authenticity of the server, a valid certificate is required. By default, Sophora components do not verify the certificate. When configured to verify the certificate you must specify a truststore on the client side. Details about the client HTTPS connection configuration can be found in the Administration Handbook of the DeskClient.
As the Sophora Server uses a jetty HTTP server internal, you may be interested in the jetty documentation about the configuration of an HTTPS connections.
For testing purposes, you can generate a key pair with the commandkeytool -genkeypair -validity 731 -alias jetty -keyalg RSA -keystore sophora.keystore
Acadia:~ sophora$ keytool -genkey -validity 731 -alias jetty -keyalg RSA -keystore sophora.keystore
Enter keystore password:
Re-enter new password:
What is your first and last name?
[Unknown]: sophora.customer.com
What is the name of your organizational unit?
[Unknown]:
What is the name of your organization?
[Unknown]: subshell GmbH
What is the name of your City or Locality?
[Unknown]: Hamburg
What is the name of your State or Province?
[Unknown]: Hamburg
What is the two-letter country code for this unit?
[Unknown]: de
Is CN=sophora.customer.com, OU=Unknown, O=subshell GmbH, L=Hamburg, ST=Hamburg, C=de correct?
[no]: yes
Enter key password for <jetty>
(RETURN if same as keystore password):
It is important that the name in the key (in this example sophora.customer.com) matches with the configured hostname (sophora.remote.api.http.address) and with the host name in the connection URL (e.g.
https://sophora.customer.com:1195).Modern browsers do not accept DSA keys.
