Docs Developer Site
Enonic XP
arrow-down
    1. Overview
    2. Core concepts
    3. Using docs
    4. Intro Videos
    5. Tutorials
    1. Intro
    2. GraphQL API
    3. Media API
    4. Extending the API
    5. Component API
    1. Content Studio
      1. Branches
    3. Layers
      1. Lifecycle
      2. Media
      3. Attachments
      4. X-data
        1. Page templates
        2. Fragments
      6. Variants
      7. Permissions
      8. Versions
    5. Sites
      1. Visual editor
    7. Publishing
    1. Introduction
      1. Controllers
      2. Globals
      3. Events
      4. HTTP Request
      5. HTTP Response
      6. Error handler
      7. Filters
      8. Templating
      9. Localization
      10. Websocket
      11. Tasks
      12. Main controller
      13. Java bridge
      1. Admin Lib
      2. Application Lib
      3. Auditlog Lib
      4. Authentication Lib
      5. Cluster Lib
      6. Common Lib
      7. Content Lib
      8. Context Lib
      9. Event Lib
      10. Export Lib
      11. Grid Lib
      12. I18N Lib
      13. IO Lib
      14. Mail Lib
      15. Node Lib
      16. Portal Lib
      17. Project Lib
      18. Repo Lib
      19. Scheduler Lib
      20. Schema Lib
      21. Tasks Lib
      22. Value Lib
      23. VHost Lib
      24. Websocket Lib
    4. Other Libraries
      1. CLI
      2. Sandboxes
      3. Code
      4. Building
      5. Configuration
      6. TypeScript
    6. Building APIs
      1. Mappings
      2. Components
      3. Processors
      4. Contributions
    8. Building Webapps
      1. ID providers
      2. Admin Apps
      3. Admin Widgets
    1. Architecture
      1. TODO
      1. Navigating
      2. Users
      3. Applications
      4. Data management
      5. System info
      6. Audit Logs
      7. Task management
      1. Portal
      2. IDprovider
      3. Management
      4. Statistics
      1. Nodes and repos
      2. Properties
      3. Indexing
      4. Branches
      5. Editors
      1. DSL Queries
      2. NoQL Queries
      3. Filters
      4. Aggregations
      5. Highlighting
      1. ID providers
      2. System ID provider
      3. Users and groups
      4. Roles
      1. Strategies
      2. Distributions
      3. Docker
      4. Kubernetes
      5. Systemd
      6. Vhosts
      7. Configuration
      8. Backup & restore
      9. Clustering
      10. Observability
      1. Notes
      2. Upgrade
      3. Upgrading Apps
        1. Asset service
        2. HTTP service
        3. Image service
    1. Best practice
        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
        1. Field set
        2. Item set
        3. Option set
      3. Mixins
      4. Localization
      5. Styles
    3. Content Types
    4. X-data
    5. Macros
      1. Pages
      2. Regions
      3. Part component
      4. Layout component
      5. Text component
      6. Component Filtering
      7. Component Indexing
    1. Marketplace
    2. Market guidelines
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.15.x (if you are running an older version, upgrade to 8.15.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.

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.

Other configuration

Others

  • 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.

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

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