Docs Developer Site
Enonic XP
arrow-down
  1. Intro
    1. Widgets
    1. ID providers
    2. System ID provider
    3. Users and groups
    4. Roles
    1. Projects
    2. Layers
        1. AttachmentUploader
        2. Checkbox
        3. Combobox
        4. ContentSelector
        5. ContentTypeFilter
        6. CustomSelector
        7. Date
        8. DateTime
        9. Double
        10. GeoPoint
        11. HtmlArea
        12. ImageSelector
        13. Long
        14. MediaSelector
        15. Radiobutton
        16. Tag
        17. TextArea
        18. TextLine
        19. Time
      2. Field set
      3. Item set
      4. Option set
      5. Mixins
      6. Localization
    4. Content Types
    5. X-data
    6. Macros
    7. Custom styles
    8. Sites
      1. Regions
      2. Part component
      3. Layout component
      4. Text component
      5. Fragments
      6. Filtering
      7. Component indexing
      8. Visual editor
    10. Page templates
  5. Applications
    1. Sandboxes
    2. Code
    3. Building
    4. Configuration
    5. TypeScript
      1. Controllers
      2. Globals
      3. HTTP
      4. Events
      5. Error handler
      6. Filters
      7. ID provider
      8. Tasks
      9. Templating
      10. Localization
      11. Websocket
      12. Mappings
      13. Components
      14. Processors
      15. Contributions
      16. Main controller
      17. Java bridge
      1. Admin API
      2. Application API
      3. Auditlog API
      4. Authentication API
      5. Cluster API
      6. Common API
      7. Content API
      8. Context API
      9. Event API
      10. Export API
      11. Grid API
      12. I18N API
      13. IO API
      14. Mail API
      15. Node API
      16. Portal API
      17. Project API
      18. Repo API
      19. Scheduler API
      20. Schema API
      21. Tasks API
      22. Value API
      23. VHost API
      24. Websocket API
      1. Webapp Engine
        1. Image service
        2. Component service
      3. Universal API Engine
      4. Media API
      5. Admin Engine
      6. Asset service
      7. HTTP service
      8. IDprovider service
    2. Task engine
    3. Management Endpoint
    4. Statistics Endpoint
    1. Nodes and repos
    2. Properties
    3. Indexing
    4. Branches
    5. Queries (NoQL)
    6. Queries (DSL)
    7. Filters
    8. Aggregations
    9. Highlighting
    10. Editors
    1. Strategies
    2. Distributions
    3. Docker image
    4. Vhosts
    5. Configuration
    6. Backup & restore
    7. Systemd
    8. Clustering
  10. Audit Logs
    1. Upgrade Notes
    2. Upgrading Apps
Developer Docs Xp Next Release Upgrade

Upgrading

Contents

This procedure applies to feature (8.x.0) and fix upgrades (8.x.y, etc).

Non-cluster upgrade

Single node deployments cannot be performed without downtime. To upgrade a single instance deployment, follow the instructions below:

  1. Stop your instance

  2. Replace your XP7 runtime image with the new XP7 image

  3. Start the instance.

Rolling Cluster upgrade

All fix upgrades (i.e. from 8.4.1 to 8.4.8), and most feature upgrades (i.e. from 8.5.x to 8.6.x) support rolling upgrades - with zero downtime. None of Major upgrades (i.e. from 7.x to 8.x) support rolling upgrades, and require a full restart of the cluster.

To safely perform a rolling upgrade, perform the following steps.

Before you perform a rolling upgrade, verify that all feature version in your upgrade path (from version → to version) support rolling upgrade

  1. Upgrade only one node at a time. Wait for the node to start and join the cluster before you move on

  2. Stop, upgrade image and start your master nodes first (We always recommend using dedicated master nodes)

  3. Stop, upgrade image and start data nodes

  4. Stop, upgrade image and start remaining nodes

Full restart Cluster upgrade

Selected feature versions (i.e. when upgrading from 7.6.x to 7.7.x or 7.8.x) may require a full restart in order to guarantee no loss of data and/or state. Releases that require full restart are marked with a special warning section below.

This strategy may safely be applied to upgrading any XP cluster and/or version

Follow the steps below to complete a restart upgrade:

  1. Stop all cluster nodes

  2. Replace the xp runtime image with the new for all nodes

  3. Start all nodes in parallel

It is important to start the nodes at the same time to avoid timeouts, should any upgrade scripts be supplied with the new version.

Applications

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!

Upgrading to v8.0

Requirements

This guide focuses on completing an upgrade with zero downtime, and requires you to set up production environment on XP 8 in parallel with existing 7.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 8.16.x (if you are running an older version, upgrade to 8.16.x first)

QA environment

Ensure you have a QA environment where you can perform a test upgrade first (highly recommended)

Toolbox

Ensure you have latest 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 8.

Custom apps

Make sure all custom built applications have been upgraded to support XP 8, as described in Upgrading Applications

1. Install XP 8

We recommend setting up a new production environment for XP 8, running in parallel with your XP 7 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

File Application deployments

If you have one or more applications deployed as files, replace them with their respective XP 8 versions

Jansi Logback plugin no longer supported

Console appender in distributive used to use Jansi plugin for colorized output. This plugin is no longer supported as logback now natively supports colorized output. Remove the withJansi element from your logback.xml file to avoid errors when starting the server.

Old logback.xml

  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <withJansi>true</withJansi>
    <encoder>
      <pattern>%date{ISO8601} %highlight(%-5level) %cyan(%logger{36}) - %msg%n</pattern>
    </encoder>
  </appender>

Old logback.xml

  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%date{ISO8601} %highlight(%-5level) %cyan(%logger{36}) - %msg%n</pattern>
    </encoder>
  </appender>

Default CMS repository

With XP 8, the default CMS repository com.enonic.cms.default is no longer created automatically. In fact, there is no default CMS repository at all. Existing com.enonic.cms.default repository is converted to a normal one without any special permissions or behavior. During XP 8 startup the repository will be converted to a normal repository. To avoid permissions conflicts it is recommended to migrate the default repository prior migration.

Metrics Endpoint

Statistics endpoint http://<host>:2609/metrics is no longer reporting Dropwizard Metrics JSON. Instead, it reports metrics in OpenMetrics format.

Management API

POST /repo/export

The following request parameters have been removed:

  • exportWithIds - previously controlled whether node IDs were included in the export

  • includeVersions - previously controlled whether all node versions were exported

  • dryRun - dry-run mode is no longer supported

A new optional batchSize parameter has been added to control the number of nodes processed per batch (default: 1000).

Exports are now stored as ZIP archives named {exportName}.zip in the exports directory, replacing the previous folder-based export structure.

POST /repo/import

The dryRun request parameter has been removed.

The exportName must refer to a ZIP archive present in the exports directory (.zip file).

Folder-based exports from XP 7 should be converted to ZIP format before they can be imported.
POST /system/dump

The archive request parameter field has been removed.

Dumps are now always stored as ZIP archives named {name}.zip in the dumps directory, replacing the previous folder-based structure.

POST /system/load

The archive request parameter field has been removed.

Folder-based dumps from XP 7 can still be loaded and upgraded by setting upgrade: true.

Admin Dashboard

Default Admin Home path is now /admin instead of /admin/home.

General Admin Tools

All admin tools are now present on the Launcher Menu as it was stated in documentation. In case when admin tool should not be present on the launcher panel convert it to an API.

Security changes

xp.suPassword

md5 and sha1 hashing algorithms are no longer supported xp.suPassword system property as they are no longer considered secure. Plain text password isn’t supported anymore either. Please use stronger hashing algorithms sha256 or sha512. More details about configuring su password can be found in system properties documentation.

System su user password is no longer read from the database either. If you had a su password stored in the database, it will be ignored after the upgrade.

User passwords

User passwords are still supported in XP8, although the hashing algorithm is changed for new passwords.

So far only pbkdf2-sha512 is supported for new passwords, but new algorithms may be added in future releases. Hash function can be configured in the security service configuration.

The old passwords are not automatically converted to the new format. When a user with an old password logs in, the password is verified using the old algorithm. It is strongly recommended to change all passwords after the upgrade to ensure all passwords are stored using the new algorithm.

Other configuration

  • Migrate other configuration files from 7.15, including custom configurations (app config etc.).

draftBranchAllowedFor

  • Portal draftBranchAllowedFor configuration is removed. Instead - to access content from the draft branch - user must have any content project role assigned (like cms.project.<projectKey>.viewer).

deployment configuration

  • It is no longer possible to via com.enonic.xp.server.deploy.cfg file. This method was not documented, unreliable in cluster installations and insecure.

Start servers

Start your new servers and verify everything is working properly

2. Dump data

We are now ready to dump data from our existing 7.15 instance.

enonic dump create --archive

3. Upgrade and Load

Move dump

Transfer dump files from previous step to the new instance. For clustered environments, any server will do.

Load dump

Now, load the dump into your XP 8 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.

4. Update apps

All installed applications must be updated to latest versions compatible with XP 8.

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 8 compatible versions of your custom applications either through the "Install App" UI or by using CLI.

5. Validate

Validate that your new installation is working as expected. We recommend checking logs, and performing live tests on services.

6. Go live

With all lights green, redirect all traffic from your old XP 7 servers to the upgraded XP 8 environment.

Welcome to the XP 8 club!

Contents

Contents

AI-powered search

Juke AI