Upgrading to XP 7.0
Upgrading to XP 7.0
This section describes the steps required to upgrade Enonic XP from 6.15 to 7.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.
- Readonly mode
Turn on readonly mode in your 6.15 instance:
toolbox.sh set-read-only readOnly -a user:password
This will prevent new data from being written to XP during the upgrade, and also ensure a consistent dump.
- Dump data
Use 6.15 toolbox to dump the data:
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!