Server 5

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

ParameterDescription
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 "127.0.0.1,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.
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.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 kubernets 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 Cliens 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 infront 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

ParameterDescription
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.
sophora.replication.delivery.<index>.groupsAssociates 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>.urlURL 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.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 5.1.0.
sophora.replication.modeType of the server. Possible values are none, cluster, master, 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 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.
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.

Repository

ParameterDescription
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.lucene.maxClauseCountSet the maximum number of boolean clauses permitted in lucene queries. (Default: 10000)

User Authentication

ParameterDescription
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 Cloud

ParameterDescription
sophora.solr.cloud.enabledIf set to true, the external solr cloud instance is used instead of the internal one. (Default: false)
sophora.solr.cloud.zk-hostsList of ZooKeeper hosts that are part of the Solr Cloud cluster.
sophora.solr.cloud.usernameSolr username if the Solr Basic Authentication Plugin is enabled
sophora.solr.cloud.passwordSolr password if the Solr Basic Authentication Plugin is enabled
sophora.solr.cloud.connection-timeoutSolr connection timeout in ms. (Default: 15000)
sophora.solr.cloud.socket-timeoutSolr socket timeout in ms. (Default: 120000)

Connecting to ZooKeeper with ACLs

If you set up ZooKeeper with ACLs on the SolrCloud ZK nodes you will need to pass the ACL credentials to the Indexing Service through one of the following options:

  • as VM arguments, for example: -DzkDigestUsername=user-readonly -DzkDigestPassword=onlyread -DzkCredentialsProvider=org.apache.solr.common.cloud.VMParamsSingleSetCredentialsDigestZkCredentialsProvider
  • in the environment variable SOLR_ZK_CREDS_AND_ACLS containing all the required VM arguments

Using the environment variable is our recommended approach for deployments in containers. Consult the SolrCloud and ZooKeeper documentation for more information about ACLs.

URL Generation

ParameterDescription
sophora.url.use-url-libraryWhether the URL library from the Sophora Web App 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-prefixWhether 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-activeWhether 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-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)

Miscellaneous

ParameterDescriptionFeature
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.
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.loadCachesOnServerStart
sophora.mail.sender.usernameThe username is used to authenticate to the SMTP server.password lost
sophora.mail.sender.passwordThe password is used with the user name to authenticate to the SMTP server.password lost
sophora.mail.sender.emailThe email address is used as sender's email address. An account on a mail server may accociate with several email addresses. Therefore, specifying this lets the mail server know which one to use.
sophora.mail.sender.nameThe name that is used as the sender's personal name in mails.password lost
sophora.mail.smtp.hostThe host name of the SMTP server that is used to send mails.password lost
sophora.mail.smtp.portThe port number of the SMTP server that is used to send mails. 25 is the default port number.password lost
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 sophora.properties

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

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:

  • MySQL 5 (no special edition is required, the free community edition is fine)
  • Oracle 10
  • PostgreSQL

To configure a database for an empty repository, a custom repository/repository.xml has to be created before the server is started for the first time. To change the configuration for an existing repository, the file repository/workspaces/default/workspace.xml must also 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>

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 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:

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

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?
	[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):

Last modified on 12/11/20

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

Icon