Server 4

Using the Sophora Server

Learn how to use the Sophora Server.

Starting the Sophora Server

Since Sophora 4.21.0 there are two scripts available that can be used to start the Sophora Server, and In Sophora 5 only will be available.


The Sophora server can be started by the shell script, located at cms-directory/sophora/ (you can learn more about the directory structure here).

Start Server

To simply start the Server run following lines:

> cd cms-directory/sophora
> ./

Script Options

The start script takes following options:

  • -clean: Starts the server with empty server info, all info about known slaves are removed before start.
  • -clusterMode {master|slave|open}: Determines if the server is started as primary (master), replica (slave) or decides this depending on the cluster state (open). The clusterMode option should not be used, if the server is configured to run as a cluster node.
  • -background: Starts the server in background, the script will exit but the server process will keep running.
  • -background_and_wait: Starts the server in background, the script will wait to exit until the started server is ready.
  • -stop: Gracefully stops the sophora server by sending a SIGTERM signal to the server process
  • -kill: Kills the sophora server process by sending a sigkill signal to the server process
  • -pid: Prints the PID of the server process
  • -h: to display help.

Here is an example of starting a server as a background process with empty server info and clusterMode primary:

./ -clean -clusterMode master -background

Stopping the Server

The Server can be stopped by pressing Ctrl+C in the Terminal running the Shell Script. If it was started in the Background, the server process can be stopped with the -stop option or if it cant be stopped gracefully with the -kill option.


The script is located at cms-directory/sophora/ It can be used for following operations:

  • Starting the server
  • Stopping the server
  • Starting the archival storage
  • Stopping the archival storage
  • Requesting whether the archival storage is active
  • Executing scripts
  • Starting the staging
  • Stopping the staging

Except for starting the server and the execution of scripts, these operations can also be triggered using the server's JMX interface.

If the JMX interface requires authentication, but there is no given pair of username and password within the configuration file, you have to append the credentials separated by a whitespace character to the JMX command. In case of doubt, the credentials from the command will be preferred and those from the configuration file are overwritten.

Starting the Server

> cd cms-directory/sophora
> ./ -start

After the start-up, the script will create the file in the cms-directory/sophora/logs directory. This file contains the process ID (PID) of this server instance. When the server has been shut down, this file will be deleted. If the server did not terminate correctly, the file is kept and has to be removed manually before the next start of the Sophora server.

Keep in mind that the script has to return before the Sophora Server is able to handle incoming connection requests. If you want to ensure that the script does not return before the initialisation is complete, use the option -start_and_wait. (JMX must be enabled)

> cd cms-directory/sophora
> ./ -start_and_wait

If you use the option -start_and_wait, the server waits for different conditions depending on its server mode. A Sophora Primary Server waits until the server is started and JMX connections can be established. Sophora Replica Servers and Sophora Staging Servers prolong the waiting period until they are initially synchronized.

The option -start_and_wait may be parameterized in order to wait until all Solr cores or just specific Solr cores are initialized. These parameters are independent of the server mode. Use the parameter solr in order to wait until all Solr cores are initialized, or a list of Solr cores for which the script should wait. The Solr cores are specified with the prefix solr_. In the following example, the script waits for the Solr cores core2 and core3.

The default -start_and_wait maximum timeout for the JMX-Connection is set to 10 minutes.
To tweak this timeout, you can specify the maximum minutes, it should wait, as follows:

> cd cms-directory/sophora
> ./ -start_and_wait max-timeout=20

This would set the maximum timeout for the JMX-Connection to 20 minutes instead of its default of 10 minutes.

> cd cms-directory/sophora
> ./ -start_and_wait solr_core2 solr_core3

Another option is -start_clean. The behaviour is similar to the -start option. The only difference: on startup, all previously registered Sophora Replica Servers get removed from the list of known Sophora Replica Servers.

> cd cms-directory/sophora
> ./ -start_clean

The options clean and wait may also be specified as arguments of the start option.

> cd cms-directory/sophora
> ./ -start wait clean

Stopping the Server

There are different ways to stop the Sophora server:

The command stop

A kill signal is sent and the script waits until the Sophora server has been shut down.

> cd cms-directory/sophora
> ./ stop

The command kill

A kill -9 signal is sent to the Sophora server.

> cd cms-directory/sophora
> ./ kill

You can check whether the server has been shut down correctly by viewing the PID. It can be obtained from the file before stopping the server. Afterwards, you should write this ID down.

The log file contains the following entry when the server has been stopped successfully:

[2018-03-28 12:00:46,002, INFO ] [LifeCycle.stop-26-thread-1] INFO om.subshell.sophora.server.SophoraServer:539 - SophoraServer shutdown complete

The Archival Process

You can control the archival process via the server script. Extensive documentation about the archival process itself can be found here.


> cd cms-directory/sophora
> ./ startArchival


> cd cms-directory/sophora
> ./ stopArchival


Use the subsequent command to get the archive worker's state (JMX must be enabled):

> cd cms-directory/sophora
> ./ isArchiving

A value between 0 and 2 will be returned, with the following meaning:

  • 0 - The archival storage is currently not active.
  • 1 - The archival storage is active.
  • 2 - The archival storage is disabled and no more documents can be enqueued. Nonetheless, the remaining queue will be completed.


Starting the Server as Primary, Replica or Staging server

If the server starts as a replica or staging server, it has to synchronize all missed document changes from the primary, which might take some time if the server has been switched off for a while.

When the synchronization has finished, the following log entry will appear in the Sophora Primary Server's log:

[2018-03-28 11:10:50,744, INFO ] [
INFO erver.replication.master.ReplicationSync:
109 - syncFinished sent

Followed by the Sophora Replica Server:

[2018-03-28 11:10:51,147, INFO ] 
[SyncFinishedThread] INFO 
ra.server.replication.slave.jms.JmsSlave:699 - 
got syncFinished SLAVE

The Throttle Mode

The Sophora server has a throttle mode for handling high load. This is described in detail here.

Executing Scripts

You can invoke customized scripts in the following way:

> cd cms-directory/sophora 
> ./ runScript skript.bsh

For detailed information about customized scripts and valid script languages, refer to the section Script controlled Sophora extensions.

Endpoints for container probes

Three endpoints which provide information about the current status of the Sophora Server are available. These endpoints can be used to specify probes in case the Sophora Server runs in a container.

  • http://<host>:<port>/status/started - Whether the Sophora Server is started
  • http://<host>:<port>/status/ready - Whether the Sophora Server is currently ready
  • http://<host>:<port>/status/liveness - Whether the Sophora Server is alive and healthy

Last modified on 10/16/20

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