Using the Sophora Server

The Sophora server is managed by the shell script sophora.sh, located at cms-directory/sophora/sophora.sh (you can learn more about the directory structure here). It can be used for the 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 sophora.properties 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
> ./sophora.sh -start

Starting the Sophora server as a Sophora Primary Server or as a fall-back Sophora Replica Server is usually quick. Starting it as a Sophora Staging Server might take a while because the time taken for initializing is dependent on the amount of files the Sophora Staging Server has to synchronize.

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 ] [Sync-www.subshell.com-
5f907edd-7c3e-4630-b372-69ddaeb42f24]
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

After the start-up, the script sophora.sh will create the file sophora.pid 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
> ./sophora.sh -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.

> cd cms-directory/sophora
> ./sophora.sh -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
> ./sophora.sh -start_clean

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

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

A Sophora Staging Server will start only with a connection to an already running Sophora Primary Server. Otherwise, the start process will pause until the Sophora Primary Server is available.

Stopping the Server

There are different ways to stop the Sophora server:

The command -stop (Recommended)

The Sophora server is stopped via JMX. Before the Sophora server stops, the archive worker is stopped.

> cd cms-directory/sophora
> ./sophora.sh -stop

The command stop

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

> cd cms-directory/sophora
> ./sophora.sh stop

The command kill

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

> cd cms-directory/sophora
> ./sophora.sh kill

You can check whether the server has been shut down correctly by viewing the PID. It can be obtained from the sophora.pid 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.

Starting

> cd cms-directory/sophora
> ./sophora.sh startArchival

Stopping

> cd cms-directory/sophora
> ./sophora.sh stopArchival

Checking

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

> cd cms-directory/sophora 
> ./sophora.sh 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.

Miscellaneous

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 
> ./sophora.sh 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

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