Postgres as the persistence layer
With the release of version 6, Sophora has transitioned its persistence layer from Apache Jackrabbit to PostgreSQL. This shift delivers enhanced performance, greater scalability, and more robust concurrency. See the Document Store documentation for details.
Upon the initial startup of Server version 6, data is automatically migrated from JCR to PostgreSQL. Depending on the size of the repository, this process may take several hours. If the migration is interrupted, it will resume seamlessly upon the next start.
Migration progress can be tracked in the server logs. During the migration process, the server does not open an HTTP port. Thus, it remains inaccessible to clients, metrics are unavailable, and health endpoints do not respond. Make sure your setup does not try to automatically restart the server too quickly due to unresponsiveness.
As with every major release update, replicas must be updated before the primary. While a version 5 primary is compatible with version 6 replicas and staging servers, a version 6 primary is not compatible with version 5 replicas or staging servers.
Once the migration is successfully completed, the JCR repository can be deleted. Both the repository folder in the server's home directory and the associated JCR databases are obsolete. The server must be stopped before deleting the JCR repository.
As a result of this transition, XPath queries are no longer supported. All XPath queries must be migrated to IQuery, which relies on Apache Solr for execution. This affects not only API calls but also text-based configurations in:
- Select Values
- Scripts
- Configurations
These configurations must be refactored to SoQL before starting the update.
The Sophora Server now requires PostgreSQL 17 or later.
Removing obsolete JCR data
Starting with Sophora Server 6.1.0, you can safely remove all data related to JCR after the initial migration. This includes the following directories in your filesystem:
- sophora/repository/repository
- sophora/repository/version
- sophora/repository/workspaces
- sophora/data/tags
You may also delete the database that stores JCR data.
In case you are using our Helm Chart, make sure to update the Helm Chart to at least version 3.0.1. Now apply the following steps in order to delete the old data:
- Set
sophora.server.persistence.repositoryTypetonone - Configure an extra volume mount to access the old data:
extraVolumeMounts:
- name: sophora-server-storage
mountPath: /sophora/old_data
- Remove all obsolete directories via shell access
rm -rf /sophora/old_data/config
rm -rf /sophora/old_data/solr
rm -rf /sophora/old_data/repository.binarystore
rm -rf /sophora/old_data/repository.version
rm -rf /sophora/old_data/repository.binaries
rm -rf /sophora/old_data/repository.workspaces.live.index
rm -rf /sophora/old_data/repository.workspaces.live.db
rm -rf /sophora/old_data/repository.workspaces.default.index
rm -rf /sophora/old_data/repository.workspaces.default.db
rm -rf /sophora/old_data/repository.repository
rm -rf /sophora/data/tags
You can remove the old_data volume mount afterwards.
The Sophora Server now hosts a new gRPC-based Sophora API on an additional port (default 2026).
Due to the discontinuation of Spring Remoting, the Sophora Client (version 6 and later) now utilizes gRPC for server communication. This gRPC services listens on port 2026 by default. Sophora Server 6 exposes both the gRPC and the legacy HTTP API. Consequently, the Sophora Client in 5 remains compatible with Sophora Server 6.
Deprecation Warning: Starting with Sophora Server version 7, the HTTP API will be removed, and only gRPC will be supported.
The module Linkchecker has been sourced out in version 5 and has been removed from Sophora Server 6.
Consequently, the Linkchecker must be deployed as a standalone application.
Content-API Externalization
Up to Version 5, the Content-API was an integral part of the Sophora Server. Starting with Version 6, the Content-API is available exclusively as an external service. Consequently, it must be deployed separately if required.
Minimum Sophora Version prior to Upgrade
For compatibility reasons all of your Sophora Servers must be running with at least version 5.11.0 prior to the upgrade to 6.
Document Store configuration
Several new configuration options have been added for the Document Store in Sophora 6.
| Status | Document Store configuration | Description | Default |
|---|---|---|---|
| NEW | sophora.documentstore.sophoraids.declutter.cron | Schedules cleanup of the Sophora ID table. Removes IDs of fully deleted documents if their ID base is continued by other documents. | 0 0 0 * * * (00:00) |
| NEW | sophora.documentstore.cache.documents.maxSize | Document cache located directly behind the database. Prevents database lookups when fetching documents. Stores live and working versions. | 5000 |
| NEW | sophora.documentstore.cache.summaries.maxSize | Document summary cache located directly behind the database. Prevents database lookups when fetching summaries. Stores live and working versions. | 5000 |
| NEW | sophora.documentstore.cache.ids.maxSize | Document ID cache located directly behind the database. Used for resolving references and executing simple queries. Stores live and working versions. | 100000 |
| NEW | sophora.documentstore.cache.primaryTypes.maxSize | Resolves the primary type of a document based on its document ID. | 100000 |
| NEW | sophora.proposals.cache.maxSections | Maximum number of proposal sections stored in the cache. | 2000 |
| NEW | sophora.proposals.cache.maxProposals | Maximum number of proposals stored in the cache. | 20000 |
| NEW | sophora.repository.jcrNodeTypes | Path to a .cnd file containing old JCR definitions that aren't stored in PostgreSQL. The default includes all required JCR nodetypes. It is unlikely that you need to change this property. | classpath:/cnd/jcr.cnd |
| REMOVED | sophora.backupSystemDocuments.cronExpression | Automatic backup of user settings is no longer supported. | — |
| REMOVED | sophora.autoPublish.legacyMode | The released status is no longer considered during publishing. | — |
| REMOVED | sophora.repository.transaction.uuidlocks.enabled | This lock is no longer needed due to the updated transaction model in the Document Store. | — |
PostgreSQL configuration
The PostgreSQL configuration has been available since Sophora 5 but is included here for completeness.
| Property | Description | Default |
|---|---|---|
sophora.persistence.postgres.hostname | Hostname of the PostgreSQL server | — |
sophora.persistence.postgres.port | Port of the PostgreSQL server | — |
sophora.persistence.postgres.username | PostgreSQL username | — |
sophora.persistence.postgres.password | PostgreSQL password | — |
sophora.persistence.postgres.database | Database used for both Version Store and Document Store | — |
sophora.persistence.postgres.maxPoolSize | Maximum number of connections in the connection pool. Determines how many SQL requests can be processed in parallel. Connections are reused. | 10 |
sophora.persistence.postgres.minIdleConnections | Minimum number of connections that should always be available | — |
sophora.persistence.postgres.connectionTimeoutMs | Maximum time the Sophora Server waits for a connection | 30000 (30s) |
sophora.persistence.postgres.idleTimeoutMs | Maximum time a connection should remain idle before being closed | 10000 (10s) |
sophora.persistence.postgres.validationTimeoutMs | After this timeout, the Sophora Server checks the connection’s health status | 5000 (5s) |
sophora.persistence.postgres.sslMode | Sets the SSL mode. To enforce a connection over TLS use require. For more information about SSL modes refer to the official postgres documentation. | prefer (Postgres default) |
List of breaking changes
| Version | Timing | Changes |
|---|---|---|
| 6.0.0 | Before the update, preferably months before | The Sophora Server does no longer come with an internal Linkchecker. If you use this feature and have not yet switched to the external Linkchecker application, you should install it before updating. |
| 6.0.0 | Before the update, preferably months before | Support for the legacy structure node document type "sophora-nt:structureNodeDocument" is discontinued in version 6. Please ensure that you do not use this document type anywhere. Since version 3 it is replaced by "sophora-nt:structureNode2". |
| 6.0.0 | Before the update, preferably months before | The Sophora Server no longer supports to search its PostgreSQL based document repository with IQuerys. Instead all queries will search in SolrCloud. The SearchParameters forceRepositorySearch flag will be ignored by the Sophora Server. |
| 6.0.0 | Before the update, preferably months before | The Sophora Server has a default implementation for composing and parsing URLs, which uses the URL components of the Sophora Webapp-Framework instead of requesting the deliveries.This implementation can handle both Sophora document URLs and URLs for the Sophora Image Service. It also avoids HTTP calls to the deliveries and thus it's much faster. Using the URL handling from the deliveries by setting the property sophora.url.use-url-library=false in the configuration file is no longer possible. The configuration sophora.documentUuidProvider.servletPath has also been removed.For more information about the properties, see the description in the documentation of the Sophora Server configuration. |
| 6.0.0 | Before the update, preferably months before | Since the method getAdditionalXPath (deprecated in 5) was removed from the ITimingActionScript interface, all implementations must also omit this method. Use getAdditionalIQuery as replacement. |
| 6.0.0 | Before the update, preferably months before | The Sophora Server no longer natively supports HTTPS and all associated configuration options have been removed. We highly recommend using an SSL-terminating reverse-proxy like nginx to connect to the Sophora Server. Read the configuration guide for more information how to configure Sophora correctly. |
| 6.0.0 | Before the update, preferably months before | The Sophora Server now hosts the new gRPC-based Sophora API on an additional port (default 2026). The previous API remains but will be removed with the future Sophora Server 7 release. The new API comes with its own list of breaking changes, which can be found on the "Sophora 6: API changes" page. Read the page carefully and see, if any of your own tools uses one of the deprecated methods. |
| 6.0.0 | Before the update, preferably months before | The shell script sophoraServerControl.sh, previously used to start the Sophora Server for on-premises setups, was removed in version 6 (was deprecated in 5). Customers can still run the Sophora Server on-premise, but no official script will be provided or supported. The recommended deployment method is now container-based/cloud-based using Helm charts. |
| 6.0.0 | Before the update, preferably months before | We removed the support for the deprecated sophora-nt:tags node type. The method com.subshell.sophora.api.server.IContentManagerContent#getTags will not be removed in Sophora 6 but it will always return an empty set. Related to this change the following sophora.properties configurations were removed:
|
| 6.0.0 | Before the update | A BooleanQuery without any subqueries will now lead to an exception in the server, instead of interpreting it as a "find everything" query. Tools may create such queries when generating a BooleanQuery by using an empty list. |
