Skip to content

Upgrading from 5.x to 6.x

EntryStore 6.x keeps the REST API and the repository format of 5.x, so existing data and clients such as EntryScape continue to work. What changed is the runtime underneath the API, several defaults and limits, and how configuration values are parsed. This page lists what an operator has to check when moving an instance from 5.x to 6.x. The detailed history is in the changelog.

What changed

5.x 6.x
REST layer Restlet Spring Boot 4.1 on embedded Jetty 12
Distribution Jetty bundle (.tar.gz) or WAR Executable jar and Docker image
Java 21 25
Default URL depends on the servlet container http://host:8080/store/ (server.port, server.servlet.context-path)
Solr embedded (local path) or external external only, Solr 10 with the configset shipped with EntryStore
Configuration entrystore.properties entrystore.properties, plus Spring Boot keys, command line overrides and stricter value parsing

Before the upgrade

  1. Back up the repository, the data folder and the configuration (see Backup).
  2. Set up an external Solr if the instance used an embedded Solr index, i.e. if entrystore.solr.url is a local path. 6.x refuses to start with a non-HTTP(S) Solr URL. See Search.
  3. Deploy the Solr configset of the new release (solr/conf in the source repository, /srv/entrystore/solr/conf in the Docker image) to the Solr core and reload the core before starting 6.x. EntryStore checks the schema at startup and refuses to run against a schema that lacks fields it writes.
  4. Review the configuration as described below. Most 5.x configurations start unchanged, but a few values change their meaning.
  5. Review the reverse proxy configuration, see Reverse proxy.

Configuration

Renamed keys

5.x keys that were renamed are translated at startup, and a WARN in the log names the 6.x key to use instead. An explicitly set 6.x key always wins over a translated one. Move to the new keys at your convenience:

5.x 6.x
entrystore.auth.http-basic=on entrystore.auth.http-basic.enabled=true
entrystore.auth.saml=on (or new) entrystore.auth.saml.enabled=true; the IdP settings keep their names (see Authentication)
entrystore.auth.cas=on entrystore.auth.cas.enabled=true
entrystore.auth.cas.server.url.login entrystore.auth.cas.server.url-login
entrystore.smtp.ssl (documented by mistake in example files up to 5.6.2, never read by 5.x) entrystore.smtp.security (the old key is now read as a fallback, with a WARN)

Removed keys

The following keys have no effect in 6.x:

  • entrystore.harvester.oai, entrystore.harvester.oai.multithreaded: the OAI-PMH harvester is not part of 6.x.
  • entrystore.repository.cache, entrystore.repository.cache.path
  • entrystore.repository.rewrite-basereference: external URLs are derived from the forwarded headers sent by the reverse proxy instead.
  • entrystore.solr.schema.url, entrystore.solr.config.url: they applied to embedded Solr only.
  • entrystore.trust.x-forwarded-for: logs a WARN; see Reverse proxy.
  • entrystore.metrics: metrics are always collected, see Performance metrics.

Values that change their meaning

  • Booleans accept true/on/yes/1 and false/off/no/0. In 5.x many settings were only enabled by on, so a value such as yes or 1 that was ignored before now enables the setting. For example, entrystore.nonadmin.group-context-creation=1 now lets every user create group contexts. An unrecognised value makes startup fail for most settings. See Settings.
  • Indexed lists (e.g. entrystore.auth.signup.whitelist.1) are read as in 5.x, but irregular numbering (a gap, .0, .01) is reported with a WARN. Number lists contiguously from .1. Traversal profiles must use the indexed form; see Traversal.
  • entrystore.auth.cookie.max-age must be at least one second; -1 fails startup.
  • SMTP transport security is enforced. A stale entrystore.smtp.ssl value or an unrecognised entrystore.smtp.security value now makes sending fail instead of silently falling back to plaintext. See SMTP.
  • reCAPTCHA requires both entrystore.auth.recaptcha.public-key and .private-key when enabled, otherwise startup fails.
  • Spring Boot keys (spring.*, server.*, management.*) only accept true and false.

New defaults and limits

Setting 6.x default 5.x
entrystore.data.max-file-size 1G (-1 disables) no limit
entrystore.proxy.max-response-size 100MB no limit
entrystore.echo.max-file-size 10MB 10 MB, not configurable
entrystore.auth.signup.rate.limit.max, entrystore.auth.password-reset.rate.limit.max, entrystore.message.rate.limit.max 10 per hour (per client IP; per user for /message) no limit
entrystore.csrf.enabled false not available
entrystore.auth.session.reload-interval 10 seconds every request

The settings are described on the respective Knowledge Base pages and in the Settings overview.

Solr index

  • An instance coming from 5.x gets a fresh index: with entrystore.data.folder configured, EntryStore detects the new schema and Solr version at startup and rebuilds the index. Without a data folder, start once with entrystore.solr.reindex-on-startup=on.
  • The rebuild can take a while on large repositories. Until it is done, search results are incomplete, POST /management/solr answers 409 to another reindex, and GET /management/status/extended lists the contexts still being indexed under solr.indexingContexts.
  • After the rebuild, solr.rejectedDocuments in GET /management/status/extended must be 0. Rejected documents mean that the Solr schema does not match the release.
  • Instances that already run a 6.0 build need extra steps when moving to 6.1; see Upgrading to version 6.1.

Search behaviour changes slightly: partial matching works per word, facet field and sort names are restricted to plain field names, and facetMatches takes literal text instead of a regular expression. See Search.

API changes for client developers

The REST API is compatible with 5.x, with these exceptions:

  • GET /auth/logout is replaced by POST /auth/logout.
  • GET /auth/basic is removed. With HTTP Basic enabled, 401 responses of Spring Security (e.g. for invalid Basic credentials) carry a WWW-Authenticate challenge instead; see Authentication.
  • /{context-id}/quota is removed.
  • PUT /management/logging is replaced by /management/loggers, the 5.x metrics format by /management/metrics, and GET /management/status?extended by GET /management/status/extended. See Management endpoints.
  • The /auth/user field external_id is now called external-id.
  • The callback parameter (JSONP) has no effect on /sparql.
  • Callers who can read neither the metadata nor the resource of an entry get a reduced entry information graph (see ACL).
  • Cache-Control headers differ from 5.x (e.g. anonymous responses carry no-cache), and the ETag of responses that embed other entries is computed from the body. See HTTP caching and formats.
  • Uploads larger than entrystore.data.max-file-size get 413, and multipart requests to routes that take no upload get 415. See Files.
  • POST /{context-id}/execute answers 502 or 504 when RowStore fails or times out. See Pipelines.
  • GET /_contexts/resource/{context-id} lists the entries of a context to admins only.

After the upgrade

  • Check the startup log for WARN messages about deprecated, translated or ignored settings, and move to the 6.x keys.
  • Check the effective configuration in GET /management/status/extended (admin only).
  • Test password login and every configured SSO method (SAML, CAS, OIDC), sign-up and password reset.
  • Test an upload of a large file if users work with large files.