Server 4

Configuring the Sophora Server

Learn about configuring the Sophora Server and about its directory structure.

The central configuration file of each Sophora Server is called and is located within the config folder of the sophora directory. Subsequently, an exemplary configuration is displayed:

# Installation directory of the Sophora Server
# RMI ports
# For fall-back and Sophora Staging Servers you have to specify the Sophora Primary Server server here
# 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)
# 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 file.

Messaging and Interfaces

sophora.http.proxy.hostHTTP proxy host address for the RemoteDataManager (See the section on Java network properties for an alternative solution)
sophora.http.proxy.portHTTP proxy port for the RemoteDataManager
sophora.http.proxy.usernameHTTP proxy username for the RemoteDataManager
sophora.http.proxy.passwordHTTP proxy password for the RemoteDataManager
sophora.http.proxy.noProxyList of excluded host names. Default is ",localhost"
sophora.jmx.enabledActivate the JMX interface: true or false
sophora.jmx.username, sophora.jmx.passwordUsername and password for the JMX interface (optional). If no username and password are given, no authentication is required to use the JMX interface.,
Use to specify the host name or IP address of the embedded JMS Broker. refers to the host name or IP address of its Sophora Primary Server.
On Sophora Staging Servers, must be configured. But as Sophora Staging Servers do not have an embedded JMS Broker, the configuration of is not necessary.
Default is localhost.
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.addressIP address to bind the HTTP port to
sophora.remote.api.http.portHTTP 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.enabledDefines whether the HTTPS port is enabled or not (Default: false). For client connection using HTTPS see here.
sophora.remote.api.https.portHTTPS 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.keyPasswordPassword for the key in the keystore (Default: sophora)
sophora.remote.api.https.keyStoreThe file name for the keystore. This file must be located in the directory sophora.home/config. (Default: "sophora.keystore")
sophora.remote.api.https.passwordPassword for the keystore (Default: sophora)
sophora.remote.api.external.hostnameAn 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.portPort counterpart for sophora.remote.api.external.hostname.
sophora.remote.api.external.protocolProtocol 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.registryPortRMI registry port. Default is 1199.
sophora.rmi.servicePortRMI port. Default is 1198.

Server Cluster and Replication

sophora.cluster.readAnywhere.availableEn- or disables the Sophora Replica Server's availability for readAnywhere connections. Default value is true
Change 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.<index>.groupsAssociates the delivery to at least one group (see<index>.url). Multiple groups are associated using a comma separated list of group names (an example is given below).<index>.urlURL of the delivery web app that is bound to this server. Hereby, <index> is a key to associate certain delivery groups (see<index>.groups). For each URL there has to be an assigned group with the same <index>.
sophora.replication.ignoreWebsitesComma 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.maxQueueSizeForAvailableStateNumber of events in the replication queue before the Sophora Replica Server is marked as unavailable. Default: 500
sophora.replication.maxSystemDocumentVersionsSyncCntLimits 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.maxVersionsSyncCntLimits 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.modeType 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.restartDateDate to start the synchronisation at. Format is "yyyy.MM.dd HH:mm". Only applicable if sophora.replication.mode=stagingslave or =slave.
sophora.replication.slaveHostnameHost 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.syncQueueLimitMaximum 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.
Username and password for JMS queues. If no username and password are provided, the default values (userName=sophora and password=jms) are taken.

Repository and Archive

sophora.archive.activeOnStartupStart the archival storage on the server's start-up. Default is true.
sophora.archive.checkAllDocumentsForOldVersionsCheck all documents for old versions in a background thread. Default is true. When set to false, only currently modified documents are checked.
sophora.archive.deleteOldVersionsAfterDaysWhen 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.enabledActivates 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.maxVersionsToRetainDefines 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.preserveNumberOfVersionsInArchiveRepositoryThe 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.versionsBatchSizeMaximum 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.defaultNodeTypesURL 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.languageThe 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>.nodeTypeSpecifies 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>.deleteOldVersionsAfterDaysSimilar 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>.preserveNumberOfVersionsInArchiveRepositorySimilar 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>.maxVersionsToRetainSimilar 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.


User Authentication

sophora.authenticate.checkForIncorrectLoginsDetermines 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.enableUserLoginDetermines 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.incorrectLoginCountDefines, 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.ignoreUppercaseIf 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

sophora.lucene.maxClauseCountSet the maximum number of boolean clauses permitted in lucene queries. (Default: 10000)
sophora.solr.embedded.enabledStart a Solr web application embedded in the server process (default: true).
sophora.solr.hostnameHTTP 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.enabledAutomatically create indexes and send changed documents to the configured Solr instance (default: true).
sophora.solr.iquerysearch.enabledSpecifies whether the Solr index should be used as the default search engine for all IQuery search operations. (Default: true)
sophora.solr.passwordPassword for the basic authentication used by the indexer and by the embedded Solr instance. (Default: solr)
sophora.solr.portHTTP 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.usernameUser name for the basic authentication used by the indexer and by the embedded Solr instance. (Default: solr)
sophora.solr.indexer.nonDefaultJobThreadsThe 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

ParameterDescription set to true, the external SolrCloud instance is used instead of the internal one. (Default: false) of ZooKeeper hosts that are part of the Solr Cloud cluster. username if the Solr Basic Authentication Plugin is enabled password if the Solr Basic Authentication Plugin is enabled connection timeout in ms. (Default: 15000) socket timeout in ms. (Default: 120000)

URL Generation

sophora.url.use-url-libraryWether 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-prefixWether the Sophora document URLs should contain the site prefix. (Default: false)
sophora.url.default-domainThe 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-activeWether 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-domainThe URL prefix for the Sophora Image Service. (Default: http://localhost)
Available in versions before 4.18.0
sophora.url.image-service-default-domainThe 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


sophora.cache.selectValues.refreshIntervalThe 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.externalIdDefines the configuration system document by its external ID (default: sophora.configuration.configuration).
sophora.homeWorkspace of the Sophora Server. This folder contains the subdirectories config, data, logs, repository, repository_archive.
sophora.ibf.enabledEnables 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.mail.sender.usernameThe username is used to authenticate to the SMTP server. Used for the 'password lost' feature.
sophora.mail.sender.passwordThe password is used with the user name to authenticate to the SMTP server. Used for the 'password lost' feature.
sophora.mail.sender.emailThe e-mail address that is used by the Sophora Server to send mails. Used for the 'password lost' feature.
sophora.mail.sender.nameThe name that is used as the real name by the Sophora Server to send mails. Used for the 'password lost' feature.
sophora.mail.smtp.hostThe host name of the SMTP server that is used to send mails. Used for the 'password lost' feature.
sophora.mail.smtp.portThe 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.
vmargsParameters for the java process.
sophora.cpuload.throttleLoadControls the load threshold for the throttle mode. The value is measured in cpu cores.
sophora.changeRegistry.derby.connectionTimeoutThe 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

The following environment variables can be used to configure the server:

Environment Variable NameDescription
SOPHORA_INITIALADMINUSERS_0_USERNAME and SOPHORA_INITIALADMINUSERS_0_PASSWORDThese 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 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 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
  • java.home
  • ssl.KeyManagerFactory.algorithm
  • 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. We propose to not mix them in order to avoid side effects.


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 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"/>

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" />

LevelDB persistence manager

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" />

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.

Binary Data Store

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 -> ../apps/sophora/ 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:

------com.subshell.sophora.component1-4.0.0 (e.g. importer)
------sophora -> link to com.subshell.sophora.server-4.0.0
------sophora-component1 (e.g. sophora-importer) -> link to component
------solr -> Symbolic link to ../apps/sophora/

Enable the Establishment of HTTPS Connections

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 command
keytool -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?
What is the name of your organizational unit?
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, 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):

Last modified on 9/9/22

The content of this page is licensed under the CC BY 4.0 License. Code samples are licensed under the MIT License.