This procedure applies to feature (7.x.0) and fix upgrades (7.x.y, etc).
To upgrade a single instance deployment:
stop your instance
replace your current 7.x runtime image with the new v7.(x+1) image
restart the instance.
The procedure is essentially the same as for a single instance, but repeated for all cluster nodes. We recommend the following procedure:
Update only one node at a time. Wait for a node to start and join the cluster before you move on to the next node.
Upgrade your master nodes first (We always recommend using dedicated master nodes)
Upgrade all other nodes. If you run a combination of back-end and front-end nodes, we recommend upgrading the back-end nodes before you move on to the front-end nodes.
If this is done correctly, bugfix upgrades (v7.x.y) can be executed without downtime. For feature upgrades (7.x.0), the forming of the cluster is a little bit more complicated, and there may be some requests to the site that are rejected during the upgrade but the process should still be really smooth.
When upgrading to new feature versions of Enonic XP, new versions of standard apps may also be available.
After upgrading XP, check for new versions of your installed applications from Enonic market. We generally always recommend updating your apps to the latest version!
Session cookie specifies
SameSite=Laxby default. It is similar to modern browsers default value except for "Lax + POST mitigation". You can revert to previous behavior by setting
session.cookieSameSite =in Configuration Files / Jetty
Image Service now limits maximum image size and number of filters applied. You can configure thresholds in Configuration Files / Image
Image Service has more eager validation of scale, filters, background and quality parameter values. Make sure the requests to Image Service use only correct/supported values.
Built-in Embed Macro now requires body part to be HTML escaped. In general, it should not cause issues because ContentStudio HTML editor always escapes macro body.
Content attachment file names can no longer contain suspicious characters. You can revert to previous behavior by setting
attachments.allowUnsafeNames = truein Configuration Files / Content
Assets Service URL fingerprint part now uses application’s "build time" instead of application’s startup time. Make sure "build time" always changes for new versions of an application.
Default Cache-Control headers for Assets Service and Portal Media Attachments have been changed. You can change default settings in Configuration Files / Portal
ResourceService no longer considers directories in jar as existing resources. If application code relies on checking directory existence in jar, consider checking existence of a file inside that directory instead.
Content integrity is verified on move as it was done on create for
sitebuilt-in content types.
page-templatecontent now accepts child content, but only
media:*. Attachments are no longer redirected to the nearest template’s site.
Named tasks do not necessarily execute on the node they were submitted on anymore. Instead, a random node capable to run a task is selected and task gets executed there. Make sure your named tasks do not require a specific node to be run on. Follow the Tasks / Distributable for more information.
v7.5 is backward compatible with earlier versions
v7.4 is backward compatible with earlier versions, but if you run XP on a cluster, several configurations need to change for the nodes to get in touch with each other after the upgrade. Please do the following:
Create the configuration files
com.enonic.xp.web.sessionstore.cfgand consider the values in them as described in Configuration Files / Hazelcast and Configuration Files / SessionStore.
Open port 5701 between the nodes in the network. This port is used by Hazelcast for internal communication in the cluster. An alternate port may be chosen by setting
network.port. If using Docker, the port needs to be opened both in the network and in the
Evaluate the minimum required number of nodes in a cluster.
system.hazelcast.initial.min.cluster.sizeis by default set to 2. During start-up, events, tasks and sessions will not be communicated between nodes in the cluster until the minimum number of nodes have signed in. For large clusters, this is an important setting. We recommend setting it to nodes/2 + 1, so for instance, in a cluster of six nodes, the value should be 4.
Distributed Sessions are off by default. Enable them by setting
replicatedin the sessionStore config, if desired.
v7.3 is backward compatible with earlier versions, but includes fixes that may affect your existing deployments.
- Changed GIF handling
The image service has been partly broken when processing GIF files. As of 7.3, GIFs are always returned as original files (unprocessed, similar to how SVGs are handled). This means GIFs will no longer be cropped, and always work as expected if they contain animations/videos. Animated GIFs are the most common usage of GIF files today.
- Ignite removed
Ignite (grid memory component) has been part of the XP core for testing purposes, disabled by default. It has now been removed from the XP core. Unless you have enabled Ignite for testing purposes, this will not affect your deployment. Also, all Ignite configuration files and options can now safely be removed.
- Content projects
XP 7.3 introduces the ability to create isolated content repositories. If you have many sites in your current deployment, consider moving your sites into separate projects.
- New docker image
A new, improved and properly documented version of our XP7 Docker image is now available. The documentation also describes how to upgrade from the old image.
v7.2 is fully backward compatible with v7.1 and v7.0.
|This version includes new "Audit logger" feature that requires a new repository. The repository will be created automatically during the upgrade process.|
v7.1 is fully backward compatible with v7.0.
This guide focuses on completing an upgrade with zero downtime, and requires you to set up production environment on XP7 in parallel with existing 6.15 environment. Carefully follow the below steps to upgrade your instance:
|For scenarios where downtime cannot be avoided, additional steps, such as setting up a temporary "we are upgrading page", will be required:|
Before starting the upgrade process, ensure the following requirements are in place
- XP Version
You need to be running at least Enonic XP 6.15.x (if you are running an older version, upgrade to 6.15.x first)
- QA environment
Ensure you have a QA environment where you can perform a test upgrade first (highly recommended)
Ensure you have 6.15 Toolbox available
- Enonic CLI
Make sure you have Enonic CLI installed
- Disk space
Verify you have enough disk space to facilitate a complete dump of all existing data
- 3rd party apps
Verify that all (if any) 3rd party applications in use are upgraded to support XP 7.
- Custom apps
Make sure all custom built applications have been upgraded to support XP 7, as described in Upgrading Applications
We recommend setting up a new production environment for XP 7, running in parallel with your XP 6 environment. This will virtually eliminate downtime, and also be a safety net, should the upgrade fail somehow.
Follow the XP installation instructions to set up an instance matching your requirements
If you have one or more applications deployed as files, replace them with their respective XP 7 versions
Vhost configuration has changed:
/apphas been renamed to
/portalhas been renamed to
Repository name is added before the branch in site URL, ie
userStorehas been renamed to
idProvider config format is new
Update your vhost config file as follows:
mapping.intranet.host = example.com mapping.intranet.source = / mapping.intranet.target = /portal/master/mysite mapping.intranet.userStore = myProvider mapping.myapp.host = myapp.example.com mapping.myapp.source = / mapping.myapp.target = /app/com.example.myapp mapping.myapp.userStore = system
mapping.intranet.host = example.com mapping.intranet.source = / mapping.intranet.target = /site/default/master/mysite mapping.intranet.idProvider.myProvider = default mapping.myapp.host = myapp.example.com mapping.myapp.source = / mapping.myapp.target = /webapp/com.example.myapp mapping.admin.idProvider.system = default
In XP 7
/api have been moved to separate dedicated ports: 2609 and 4848 respectively.
Consider how this affects your monitoring and how to expose management API internally.
http.port is replaced with
discovery.unicast.sockets in ES configuration: "ip[port]" is now "ip:port"
#Old: discovery.unicast.sockets = 10.0.0.1 #New: discovery.unicast.sockets = 10.0.0.1:9300
Migrate other configuration files from 6.15, including custom configurations (app config etc.).
Start your new servers and verify everything is working properly
We are now ready to dump data from our existing 6.15 instance. Do with the 6.15 toolbox:
toolbox.sh dump -t mydump -a user:password --skip-versions
We highly recommend dumping data without versions. This will dramatically speed up the upgrade while also preparing your dataset for the new vacuuming features in XP 7.
- Move dump
Transfer dump files from previous step to the new instance. For clustered environments, any server will do.
Toolbox has been removed from XP 7 and replaced by Enonic CLI.
- Upgrade dump
Before we can load the dump, we need to upgrade the data to support XP 7:
enonic dump upgrade
- Load dump
Now, load the dump into your XP 7 environment i.e.
enonic dump load
|Don’t worry about the command losing connection, this is only related to the system repo (and user) being removed during the operation. Watch the log for progress.|
All installed applications must be updated to latest versions compatible with XP 7.
- Market apps
For market apps, go to the Applications tool, click "Install" in the menu and click "Upgrade" button for all applications where upgrade is available.
- Custom apps
Install XP 7 compatible versions of your custom applications either through the "Install App" UI or by using CLI.
Validate that your new installation is working as expected. We recommend checking logs, and performing live tests on services.
With all lights green, simply redirect all traffic from your old XP 6 servers to the upgraded XP 7 environment.
Welcome to the XP 7 club!