Installation and Deployment

Important Changes

There are hundreds of changes across dotCMS versions that affect all types of functionality. Most of these are captured in detail in our changelog and GitHub documentation for each version. Below are a list of major changes across versions that we have seen cause questions and issues as customers have upgraded from older versions.

These changes may or may not be important to your system depending on the details of your implementation; please review them, and contact support if you have any questions. You may also wish to review our Deprecations page.

Details by Version#

26.11.06-03#

26.11.06-03, ships with stricter security defaults for API access and basic authentication. In dotCMS, many anonymous API responses expose valid system usernames and email addresses. This design has historically allowed administrative functions within dotCMS to function seamlessly. However, because dotCMS WebDAV and API endpoints have accepted Basic username:password authentication, attackers can harvest these exposed usernames and email addresses to attempt password-guessing attacks against administrator accounts. The new security defaults eliminate this entire attack path by restricting basic authentication and requiring explicit API tokens for API responses.

What is changing:#

Basic authentication and WebDAV only accepts an API token as the password. Real username/password pairs are rejected. This includes WebDAV: keep your username and use an API token in place of your password.
Anonymous access to the content APIs is off by default. Requests without an API token are rejected (401). This covers the Content API, GraphQL, the Elasticsearch search API, tags, languages, content types and fields, widgets, and content relationships.
Anonymous access to custom scripting endpoints (/api/vtl/* and /api/js/*) is off by default. Generated sitemaps, custom VTL endpoints, and similar public endpoints return 401 to anonymous visitors.

What to do#

Recommended: move to API tokens
API clients: send the header Authorization: Bearer. You can create tokens in dotCMS using the User manager screen. These can be passed to dotCMS to authenticate with the API request.
WebDAV: keep your username and use an API token as the password.
If you only need your public scripting endpoints (sitemaps, custom VTL/JS APIs): In the dotCMS admin, go to Maintenance > System Table and set:

SCRIPTING_APIS_ALLOW_ANONYMOUS = true

This opens /api/vtl/* and /api/js/* to anonymous visitors and keeps the built-in content APIs closed. Scripts run as the anonymous user and respect that user's permissions. The setting applies to every HTTP method, so publish only get.vtl / get.js for endpoints that should be read-only. How to revert to the previous default If you need more time to update your integrations, you can choose to maintain the current less secure behavior by setting these in Maintenance > System Table:

DOT_ALLOW_BASIC_AUTH = ALL
DOT_CONTENT_APIS_ALLOW_ANONYMOUS = READ   (OR WRITE)
DOT_SCRIPTING_APIS_ALLOW_ANONYMOUS = true

Changes take effect immediately, with no restart. You can add them before the upgrade so nothing breaks when your evergreen environment update happens. Use this only as a stopgap. It reopens and exposes the vulnerabilities that these changes close.

26.07.13-01#

VTL template authors should ensure aggregations are navigated directly as aggregations.<name>.buckets and drop the legacy .get("asMap") hop. [#36435]

...
#set($rawResults = $estool.search($render.eval($esQuery)))
#set($results = $json.generate($rawResults.response))
## OLD: #foreach($folder in $results.aggregations.get("asMap").folders.buckets)
## NEW:
#foreach($folder in $results.aggregations.folders.buckets)
    <url>
        <loc>https://${host}${folder.key}</loc>
        <changefreq>always</changefreq>
        <priority>0.9</priority>
    </url>
#end

26.04.25-01#

Index mapping and bulk indexing are routed through a vendor-neutral layer that works across Elasticsearch and OpenSearch migration phases. [#34933]
- ContentletIndexAPI.fullReindexStart() now returns IndexStartResult instead of String. Callers previously using the raw timestamp string must call .timestampSuffix() on the result.
- BulkRequest, BulkProcessor, and ActionListener<BulkResponse> have been removed from the ContentletIndexAPI interface. Any code directly casting or importing these types against the interface will not compile.
- The IndexAccess enum's values have changed. IndexAccess.READ_ONLY should be changed to IndexAccess.READ; IndexAccess.READ_WRITE is now IndexAccess.WRITE

Example of replacing Elasticsearch-specific types with vendor-neutral domain abstractions:

// BEFORE
void putToIndex(BulkRequest bulkRequest);
IndexBulkProcessor createBulkProcessor(BulkProcessor.Listener listener);
String fullReindexStart();

// AFTER (current in main)
void putToIndex(IndexBulkRequest bulkRequest);
IndexBulkProcessor createBulkProcessor(IndexBulkListener bulkListener);
IndexStartResult fullReindexStart();

26.04.20-01#

Important changes to the Universal Visual Editor include faster inline editing paths and quality-of-life updates — such as quick-edit cancel actions and improved variant-handling behavior — to reduce editing friction. Users running headless sites must update their SDK libraries to continue using the UVE. [#34555]

26.03.06-02#

OSGi plugins directly referencing APILocator.getESIndexAPI() or any org.elasticsearch.* types will fail to load at runtime. Replace with APILocator.getIndexAPI() and the new provider-neutral types in com.dotcms.content.index.domain, then rebuild.
- See our migration guide for further details and a full type mapping.
- See our blog post about how to add plugin compatibility testing to your CI/CD pipelines.

26.02.27-01#

Made time unit handling consistent throughout database timeout configuration; DB_CONNECTION_TIMEOUT and DB_IDLE_TIMEOUT now use milliseconds consistently throughout the codebase, removing the erroneous multiplication by 1000 that caused effective timeouts of ~1.5 hours instead of the intended values. Please ensure these times are configured in milliseconds.

25.12.01-01#

SDK update: The React-library AI search result property has changed:
- DotCMSAISearchResponse.dotCMSResults -> DotCMSAISearchResponse.results

Migration guide:

// Before
const response = await client.ai.search('query', 'index');
response.dotCMSResults.forEach(item => console.log(item));

// After
const response = await client.ai.search('query', 'index');
response.results.forEach(item => console.log(item));

25.07.08-1#

SDK update: Imports must be updated:
- import @dotcms/client/next -> import @dotcms/client
- import @dotcms/angular/next -> import @dotcms/angular
- import @dotcms/react/next -> import @dotcms/react This establishes a stable foundation for the SDK with proper dependency management, updated documentation, and enhanced dual publishing strategy.

25.06.05-1#

GraphQL behavior: Block Editor fields are returned as parsed objects instead of JSON strings.
GraphQL behavior: GraphQL now automatically converts _raw fields to objects under their corresponding base keys.

25.06.03-1#

GraphQL behavior: Aligned GraphQL page query behavior with REST Page API for Vanity URLs, including in cases where the "from" page object does not exist.
Metadata behavior: Fixed modDate — now updates properly after Unpublish or Archive actions.

25.02.12#

Enabled authentication for servlet requests, allowing users to download files via an authenticated API request. Users can have their resources protected behind authentication, but still access them via an authenticated API request.

24.12.27#

Corrected Push Publishing behavior: System now correctly respects the push-publishing filter governing relationships — i.e., relationships: false will properly prevent relationship data from being transmitted to, or altered on, the receiver.

24.11.11#

Endpoint change: Disabled the legacy /DotAjaxDirector/com.dotcms.publisher.ajax.RemotePublishAjaxAction/cmd/uploadBundle endpoint in favor of /api/bundle/sync.
- The old endpoint can be re-enabled via the DOT_ENABLE_OLD_BUNDLE_UPLOAD_ENDPOINT configuration variable.

24.08.27#

Log behavior change: A new global log4j configuration in Tomcat may cause conflicts with existing custom logging behaviors; in the worst case can cause a server to fail to start. Using the default logging configuration is recommended when upgrading.
API response change: Page API's returned image property now includes the entire image object, rather than just an identifier string.

24.07.19#

Cookie change: The access_token cookie has been renamed rme, as its only purpose is to establish a "remember me" login flow. rme cannot be used as a Bearer token in the header, and concerns itself exclusively with full login procedures that update the user's "last login" date.

23.10#

Default behavior change: dotCMS 23.10.24 (whether Current or LTS) initiates the default behavior of deleting versions of Content older than a year and greater than 100 versions ago. This will never include live or working versions of content. See Content Versions for information on how to adjust this behavior through environment variables.

23.06#

MSSQL is deprecated, and will no longer be receiving active support; from now on, all DB development will be in PostgreSQL.
- All remaining transitional MSSQL support will have ended as of the following EOL dates:
  - 23.06 (Jun 14, 2024)
  - 23.01.x LTS (Sep 22, 2024)

Older Versions#

23.01#

Removed unused MySQL and Oracle drivers; users relying on either of these will need to provide their own drivers in their plugins.

22.12#

Requires a reindex immediately after upgrade due to changed handling of identifiers.

22.09#

As of this build, LDAP support is deprecated, and may be removed from the product at a future date. It is recommended that customers still using LDAP to integrate with dotCMS begin migration to a different Single Sign-On (SSO) solution, such as SAML (through Azure or another Identity Provider).

22.08#

By default, dotCMS no longer follows redirects when accessing remote URLs programmatically. This change is configurable, and can be reversed by setting the REMOTE_CALL_ALLOW_REDIRECTS property to true.

22.06#

Initial admin password automatically generated; retrieve from log or use DOT_INITIAL_ADMIN_PASSWORD environment variable.
Updated several default configuration values, such as disallowing HTTP by default.
Build scripts have adjusted to use Gradle 7.3.3.

22.05#

OSGi Fragments now update the osgi-extras properties and are not used in the plugins screen.

22.03#

Timezone added to all dates — dates using daylight savings might need manual (sql/by hand) adjustment.
Content now stored as a json field rather than as columns — custom database content queries (which should not be done anyway) are no longer an option.
All front-end struts paths disabled.
Calendar screen removed, calendarEvent deprecated.
Hazelcast removed.
/api/v2/users incorporated into /api/v1/users. Redirect calls appropriately.

21.07#

Deterministic Ids added to objects.

21.06#

Requires Java 11.
Last version to support Oracle and MySQL.
- This tool can simplify the migration from MySQL to PostgreSQL. It is believed to work in most cases, though it has not been tested with significantly old versions of the software. We still recommend, as we do generally, that you make backups before performing any major operation on a database.
Static plugins no longer supported. Almost all configuration should now be done as environmental variables.
Non-postgres installs require 3rd party cache transport provider.
Docker required for any supportable installation.
All dotCMS cookies marked as Secure, SameSite and HTTPOnly, which can cause issues in some SSO environments.
Enabled several security headers in Tomcat. Note that X-Frame-Options can be overridden by Content-Security-Policy: frame-ancestors using dotCMS Rules

21.02#

Removes legacy user_proxy table.

5.3#

Elasticsearch is now externalized.
The clusterId of an environment determines the Elasticsearch indexes to use and should not be shared across clusters.

5.2.4#

Child Relationships are no longer queryable in Elasticsearch. There are convenience methods in both REST and velocity to mirror the old behavior.

5.2#

Front-end and Back-end roles are required for users.
Elasticsearch mapping changes - default elasticsearch mapping changed from whitespace to custom/standard analyzer. This can be overridden at the field level and queries can be changed to query against the {fieldVar}_dotraw version of a text field. Dates are now mapped as date fields and numeric values are mapped as numberic fields in elasticsearch.

5.0#

Workflow Steps/Actions now required for every content action.
System Workflow added.
H2 no longer supported as content datastore.
Major Elasticsearch version upgrade. _all is no longer queryable.

4.2#

Vanity Urls converted to content.
Identifiers/paths get lowercased - dotCMS pathing should now be case insensitive.

4.0#

Drops legacy fileasset and htmlpage database tables.

3.1#

Requires Java 8
Pages converted to content
Pages no longer need .html or .dot extensions. If you need extension for index pages, you need to explicitly set CMS_INDEX_PAGE=index.html