cms-directoryrefers 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=188.8.131.52 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
Messaging and Interfaces
|HTTP proxy host address for the RemoteDataManager (See the section on Java network properties for an alternative solution)|
|HTTP proxy port for the RemoteDataManager|
|HTTP proxy username for the RemoteDataManager|
|HTTP proxy password for the RemoteDataManager|
|List of excluded host names. Default is "127.0.0.1,localhost"|
|Activate the JMX interface: |
|Username and password for the JMX interface (optional). If no username and password are given, no authentication is required to use the JMX interface.|
On Sophora Staging Servers,
Default is localhost.
On Sophora Staging Servers, only the property
Default is 1197.
|IP address to bind the HTTP port to|
|HTTP port to access the content manager API via HTTP. If this property is blank, the port will be calculated as follows: |
|Defines whether the HTTPS port is enabled or not (Default: |
|HTTPS port to access the content manager API via HTTPS. If this property is blank, the port will be calculated as follows: |
|Password for the key in the keystore (Default: sophora)|
|The file name for the keystore. This file must be located in the directory |
|Password for the keystore (Default: sophora)|
|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.
|Port counterpart for |
|Protocol counterpart for |
The protocol can be different from the servers preferred protocol. You can use SSL termination in front of a Sophora Server running on http.
|RMI registry port. Default is 1199.|
|RMI port. Default is 1198.|
Server Cluster and Replication
|En- or disables the Sophora Replica Server's availability for readAnywhere connections. Default value is |
Change the state in JMX, go to ContentManager-MBean and you will see the current value for ReadAnywhereAvailable. There is also an operation
|Associates the delivery to at least one group (see |
|URL of the delivery web app that is bound to this server. Hereby, <index> is a key to associate certain delivery groups (see |
|Comma separated list of websites' UUIDs. Only applicable if |
|Number of events in the replication queue before the Sophora Replica Server is marked as unavailable. (Default: 500)|
|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|
|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 |
|Date to start the synchronisation at. Format is "yyyy.MM.dd HH:mm". Only applicable if |
|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.
|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.|
|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
|This must be set to |
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
|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
There's an internal thread that is run periodically which looks for scheduled publications.
|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.|
|Determines whether documents are moved to the archive repository or are removed completely. Only relevant if |
|Sets the maximum number of deleted documents that should be processed in one run. Default 300.|
|Cron expression defining when to run the job for deleted documents. Default |
|Enable the removal job for deleted documents when starting the server? Possible values are |
|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.|
|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: |
|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 |
|Space-separated list of tags to be added to a cloned document after cloning. Can be empty. Default value: "kopie".|
|Create document IDs only with even numbers: |
|Create document IDs with a minus as ID stem suffix: |
|Maximum height of big thumbnails, e.g. for tooltips of image documents. Default 300.|
|Maximum width of big thumbnails, e.g. for tooltips of image documents. Default 300.|
|Maximum height of thumbnails in the light box. Default 100.|
|Maximum width of thumbnails in the light box. Default 100.|
|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.|
|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: |
When processing more documents per run as the value in the 'batchLimit' is, the timing script should run only once per day
|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.
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
Repository and Archive
|Start the archival storage on the server's start-up. Default is |
|Check all documents for old versions in a background thread. Default is |
|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.|
|Activates the archival storage if set to |
|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.|
|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.|
|Maximum number of versions to be archived within a single batch. Default is 500. If configured to 0 or below, default is used instead.|
|URL to the |
|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).|
|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.
|Similar to |
|Similar to |
|Similar to |
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
|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: |
|Determines whether users are allowed to log in to the server (default: |
|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.|
|If set to |
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
Solr and Lucene
|Set the maximum number of boolean clauses permitted in lucene queries. (Default: 10000)|
|Start a Solr web application embedded in the server process (default: |
|HTTP host of the Solr instance. When an embedded Solr is started, the regular HTTP host name (|
|Automatically create indexes and send changed documents to the configured Solr instance (default: |
|Specifies whether the Solr index should be used as the default search engine for all IQuery search operations. (Default: |
|Password for the basic authentication used by the indexer and by the embedded Solr instance. (Default: solr)|
|HTTP port of the Solr instance. When an embedded Solr is started, the regular HTTP port |
|User name for the basic authentication used by the indexer and by the embedded Solr instance. (Default: solr)|
|The number of threads to use in a thread pool for all solr indexing jobs except for the default and live solr index. (Default: |
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.
|If set to |
|List of ZooKeeper hosts that are part of the Solr Cloud cluster.|
|Solr username if the Solr Basic Authentication Plugin is enabled|
|Solr password if the Solr Basic Authentication Plugin is enabled|
|Solr connection timeout in ms. (Default: |
|Solr socket timeout in ms. (Default: |
|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: |
|Wether the Sophora document URLs should contain the site prefix. (Default: |
|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: |
|Wether the Sophora Image Service is active and its URL component should be used for parsing and composing URLs for image documents. (Default: |
|The URL prefix for the Sophora Image Service. (Default: |
|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)|
|Defines the configuration system document by its external ID (default: |
|Workspace of the Sophora Server. This folder contains the subdirectories |
|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: |
|The username is used to authenticate to the SMTP server. Used for the 'password lost' feature.|
|The password is used with the user name to authenticate to the SMTP server. Used for the 'password lost' feature.|
|The e-mail address that is used by the Sophora Server to send mails. Used for the 'password lost' feature.|
|The name that is used as the real name by the Sophora Server to send mails. Used for the 'password lost' feature.|
|The host name of the SMTP server that is used to send mails. Used for the 'password lost' feature.|
|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.|
|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
|Parameters for the java process.|
|Controls the load threshold for the throttle mode. The value is measured in cpu cores.|
|Cache size for password hashes. Default is 10000|
Requires version 4.11.7
|Controls the cache size for the roles. Should be larger then the amount of roles the system has. Default is 2000|
Requires version 4.11.7
|Controls the cache size for structure nodes and structure info objects. Default is 15000|
Requires version 4.11.7
|Controls the cache size for node types and node type configurations. Should be bigger then the amount of node types the system has. Default is 10000|
Requires version 4.11.7
|Controls the cache size for proposal sections. Should be bigger then the amount of proposal sections the system has. Default is 1000|
Requires version 4.11.8
Configuration options outside of the sophora.properties
The following environment variables can be used to configure the server:
|Environment Variable Name||Description|
|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 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:
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.
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_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_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.
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
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.
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.
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
sophora.sh -> ../apps/sophora/sophora.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:
------com.subshell.sophora.component1-4.0.0 (e.g. importer)
------sophora -> link to
------sophora-component1 (e.g. sophora-importer) -> link to component
------sophora.sh -> Symbolic link to
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
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
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? [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):