Sophora Server Configuration

You configure the Sophora Server with a sophora.properties file. Its location can be specified with the Java VM option -Dsophora.properties. Here is a minimal example to extend on:

sophora.home=/path/to/sophora/home

sophora.persistence.postgres.hostname=localhost
sophora.persistence.postgres.port=5432
sophora.persistence.postgres.username=postgres
sophora.persistence.postgres.password=postgres
sophora.persistence.postgres.database=sophora

sophora.replication.mode=master

sophora.binarystore=fs

Configuration Parameters of the Sophora Server

The following tables list all valid parameters for the sophora.properties file.

Messaging and Interfaces

PostgreSQL

The PostgreSQL connections are held in a connection pool. The following optional properties can be used to configure the connection pool. If not specified, the properties will take the default values from HikariCP, a Java library for JDBC connection pool.

Every Sophora Server requires its own Postgres-Database. Currently this must be at least version 17. In a production environment we recommend one PostgreSQL server per Sophora Server.

Server Cluster and Replication

Document Related Settings

Document Store

Version Store

Repository

User Authentication

Solr Cloud

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

Miscellaneous

Reading Environment Variables

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

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. Its location can be specified with the Java VM option -Dlogback.configurationFile.

To use active profile logging refer to the configuration page.

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.

JCR Repository

The current release of Sophora 6 does not query or write to the JCR repository but still requires its configuration and availability. This dependency will be removed in a later minor version. Until then you can keep your current JCR configuration or use the following one for PostgreSQL.

You need to setup three JCR configuration files to connect JCR to postgres. These configuration files contain variables starting with SOPHORA_ and JCR_ like ${SOPHORA_PERSISTENCE_POSTGRES_HOSTNAME}. You need to replace them accordingly. Do not replace the lower cased variables.

repository/repository.xml

<?xml version="1.0"?>
  <!DOCTYPE Repository
            PUBLIC "-//The Apache Software Foundation//DTD Jackrabbit 2.0//EN"
            "http://jackrabbit.apache.org/dtd/repository-2.0.dtd">
  <Repository>
    <!--
      virtual file system where the repository stores global state (e.g.
      registered namespaces, custom node types, etc.)
    -->
    <FileSystem class="org.apache.jackrabbit.core.fs.local.LocalFileSystem">
      <param name="path" value="${rep.home}/repository" />
    </FileSystem>

    <!--
      security configuration
    -->
    <Security appName="Jackrabbit">
      <AccessManager class="org.apache.jackrabbit.core.security.simple.SimpleAccessManager">
        <!-- <param name="config" value="${rep.home}/access.xml"/> -->
      </AccessManager>

      <LoginModule class="org.apache.jackrabbit.core.security.simple.SimpleLoginModule">
        <!--
            anonymous user name ('anonymous' is the default value)
        -->
        <param name="anonymousId" value="anonymous"/>
        <!--
            administrator user id (default value if param is missing is 'admin')
        -->
        <param name="adminId" value="admin"/>
      </LoginModule>
    </Security>

    <!--
      location of workspaces root directory and name of default workspace
    -->
    <Workspaces rootPath="${rep.home}/workspaces"
      defaultWorkspace="default" />
    <!--
      workspace configuration template: used to create the initial workspace
      if there's no workspace yet
    -->
    <Workspace name="${wsp.name}">
      <FileSystem class="org.apache.jackrabbit.core.fs.local.LocalFileSystem">
        <param name="path" value="${wsp.home}"/>
      </FileSystem>
      <!--
        persistence manager of the workspace: class: FQN of class
        implementing the PersistenceManager interface
      -->
          <PersistenceManager class="org.apache.jackrabbit.core.persistence.pool.PostgreSQLPersistenceManager">
                  <param name="driver" value="org.postgresql.Driver"/>
                  <param name="consistencyCheck" value="false"/>
                  <param name="minBlobSize" value="16384"/>
                  <param name="url" value="jdbc:postgresql://${SOPHORA_PERSISTENCE_POSTGRES_HOSTNAME}:${SOPHORA_PERSISTENCE_POSTGRES_PORT}/${JCR_REPOSITORY_DEFAULT_POSTGRES_DB}"/>
                  <param name="user" value="${SOPHORA_PERSISTENCE_POSTGRES_USERNAME}"/>
                  <param name="password" value="${SOPHORA_PERSISTENCE_POSTGRES_PASSWORD}"/>
                  <param name="schema" value="postgresql"/>
                  <param name="bundleCacheSize" value="1024"/>
                  <param name="schemaObjectPrefix" value="${wsp.name}_"/>
          </PersistenceManager>
      <!--
        Search index and the file system it uses. class: FQN of class
        implementing the QueryHandler interface
      -->
      <SearchIndex class="org.apache.jackrabbit.core.query.lucene.SearchIndex">
        <param name="path" value="${wsp.home}/index"/>
        <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>
    </Workspace>

    <!--
      Configures the versioning
    -->
    <Versioning rootPath="${rep.home}/version">
      <FileSystem class="org.apache.jackrabbit.core.fs.local.LocalFileSystem">
        <param name="path" value="${rep.home}/version" />
      </FileSystem>
      <!--
        persistence manager of the workspace: class: FQN of class
        implementing the PersistenceManager interface
      -->
          <PersistenceManager class="org.apache.jackrabbit.core.persistence.pool.PostgreSQLPersistenceManager">
                  <param name="driver" value="org.postgresql.Driver"/>
                  <param name="consistencyCheck" value="false"/>
                  <param name="minBlobSize" value="16384"/>
                  <param name="url" value="jdbc:postgresql://${SOPHORA_PERSISTENCE_POSTGRES_HOSTNAME}:${SOPHORA_PERSISTENCE_POSTGRES_PORT}/${JCR_REPOSITORY_VERSIONS_POSTGRES_DB}"/>
                  <param name="user" value="${SOPHORA_PERSISTENCE_POSTGRES_USERNAME}"/>
                  <param name="password" value="${SOPHORA_PERSISTENCE_POSTGRES_PASSWORD}"/>
                  <param name="schema" value="postgresql"/>
                  <param name="bundleCacheSize" value="1024"/>
                  <param name="schemaObjectPrefix" value="ver_"/>
          </PersistenceManager>
    </Versioning>
      <!--
        Search index and the file system it uses. class: FQN of class
        implementing the QueryHandler interface
      -->
    <SearchIndex
      class="org.apache.jackrabbit.core.query.lucene.SearchIndex">
      <param name="path" value="${rep.home}/repository/index" />
      <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>

  </Repository>

repository/workspaces/default/workspace.default.xml

<?xml version="1.0" encoding="UTF-8"?>
  <Workspace name="default">
    <!--
      virtual file system of the workspace: class: FQN of class
      implementing the FileSystem interface
    -->
    <FileSystem class="org.apache.jackrabbit.core.fs.local.LocalFileSystem">
      <param name="path" value="${wsp.home}"/>
    </FileSystem>
    <!--
        persistence manager of the workspace: class: FQN of class
        implementing the PersistenceManager interface
    -->
    <PersistenceManager class="org.apache.jackrabbit.core.persistence.pool.PostgreSQLPersistenceManager">
      <param name="driver" value="org.postgresql.Driver"/>
      <param name="consistencyCheck" value="false"/>
      <param name="minBlobSize" value="16384"/>
      <param name="url" value="jdbc:postgresql://${SOPHORA_PERSISTENCE_POSTGRES_HOSTNAME}:${SOPHORA_PERSISTENCE_POSTGRES_PORT}/${JCR_REPOSITORY_DEFAULT_POSTGRES_DB}"/>
      <param name="user" value="${SOPHORA_PERSISTENCE_POSTGRES_USERNAME}"/>
      <param name="password" value="${SOPHORA_PERSISTENCE_POSTGRES_PASSWORD}"/>
      <param name="schema" value="postgresql"/>
      <param name="bundleCacheSize" value="1024"/>
      <param name="schemaObjectPrefix" value="${wsp.name}_"/>
    </PersistenceManager>
    <!--
      Search index and the file system it uses. class: FQN of class
      implementing the QueryHandler interface
    -->
    <SearchIndex class="org.apache.jackrabbit.core.query.lucene.SearchIndex">
      <param name="path" value="${wsp.home}/index"/>
      <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>
  </Workspace>

repository/workspaces/live/workspace.live.xml

  <?xml version="1.0" encoding="UTF-8"?>
  <Workspace name="live">
    <!--
    virtual file system of the workspace: class: FQN of class
    implementing the FileSystem interface
    -->
    <FileSystem class="org.apache.jackrabbit.core.fs.local.LocalFileSystem">
      <param name="path" value="${wsp.home}"/>
    </FileSystem>
    <!--
      persistence manager of the workspace: class: FQN of class
      implementing the PersistenceManager interface
    -->
    <PersistenceManager class="org.apache.jackrabbit.core.persistence.pool.PostgreSQLPersistenceManager">
        <param name="driver" value="org.postgresql.Driver"/>
        <param name="consistencyCheck" value="false"/>
        <param name="minBlobSize" value="16384"/>
        <param name="url" value="jdbc:postgresql://${SOPHORA_PERSISTENCE_POSTGRES_HOSTNAME}:${SOPHORA_PERSISTENCE_POSTGRES_PORT}/${JCR_REPOSITORY_LIVE_POSTGRES_DB}"/>
        <param name="user" value="${SOPHORA_PERSISTENCE_POSTGRES_USERNAME}"/>
        <param name="password" value="${SOPHORA_PERSISTENCE_POSTGRES_PASSWORD}"/>
        <param name="schema" value="postgresql"/>
        <param name="bundleCacheSize" value="1024"/>
        <param name="schemaObjectPrefix" value="${wsp.name}_"/>
    </PersistenceManager>
    <!--
    Search index and the file system it uses. class: FQN of class
    implementing the QueryHandler interface
    -->
    <SearchIndex class="org.apache.jackrabbit.core.query.lucene.SearchIndex">
      <param name="path" value="${wsp.home}/index"/>
      <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>
  </Workspace>

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.

Configuring HTTPS

To connect to the Server via HTTPS, Sophora needs to be run behind a reverse proxy like nginx, which can handle the SSL termination. This can also be achieved using an ingress controller (e.g. ingress-nginx) in Kubernetes deployments. Please read the following section for general instructions on running the Sophora Server behind a reverse proxy.

Running the Sophora Server behind a reverse proxy

The Sophora Server can be run behind a reverse proxy like nginx. As the Server's API is based on gRPC, it is necessary to configure the proxy to handle these connections properly. We recommend to use nginx but all proxies with gRPC support should be suitable. The following example shows a minimal nginx configuration which ensures that gRPC traffic is sent correctly to the gRPC port while the other traffic is still being sent to the default http port.

http {
    server {
        listen 80;
        listen [::]:80;

        http2 on;

        location /sophora.srpc {
            grpc_pass grpc://sophora-server:2026;
        }

		location / {
            proxy_pass http://sophora-server:1196;
        }
    }
}

The above configuration ensures that all gRPC API calls are proxied as gRPC calls, while the rest of the Sophora Server's endpoints are proxied as regular HTTP requests. If required, the configuration can be extended to support HTTPS. Additionally, nginx supports many fine-grained configuration options for reverse-proxying.