Instructions for Upgrading to Crafter CMS 3.1.0 from a previous 3.0.x version

This section details how to upgrade your Crafter CMS installation.

Before Upgrading

Starting with version 3.1.0, Crafter CMS has an upgrade manager that automatically upgrades the system, some configuration files and blueprints. Here’s a list of items auto handled by the upgrade manager when you start Crafter CMS:

  1. Site Config updates

    There are a number of updates that has been made to the tools available in siteConfig.

    Here’s the upgraded siteConfig tools:

    Crafter Studio Site Config

    The following items are auto added/removed from your site after starting your new Crafter CMS install:

    • Remote Repository tool is auto added
    • Groups tool is auto removed
    • Log level setting is auto removed
    • GraphiQL is auto added
  2. Version File Added

    Starting with version 3.1.0 Crafter CMS will use a special file studio_version.xml to track the version of each site and automatically apply upgrades for future releases. The studio_version.xml file is auto installed and looks like this:

    /config/studio/studio_version.xml
    <?xml version="1.0" encoding="UTF-8"?>
    <studio>
        <version>3.1.0</version>
    </studio>
    

    Note

    If your site is heavily customized and you would like to prevent Crafter CMS from trying to upgrade it in the future you can set the version value to any random string, for example <version>DISABLED</version>.

  3. Managed Configuration Files

    Starting in version 3.1.0 Crafter CMS will also track an individual version for some configurations files in order to keep them up to date. These configuration files are auto updated by the upgrade manager

    Note

    These upgrades can also be disabled by setting the version to a random string, just like the site version.

    Important

    If one of the files do not contain a version tag then all existing upgrades will be applied.

    This is the list of files currently managed by Crafter CMS:

    • /config/studio/role-mappings-config.xml Current version: 2. In 3.0.x groups were handled by site and starting in 3.1.0 they became global, during the database upgrade existing groups will be renamed to {site}_{role} and this file needs to match.
    • /config/studio/administration/config-list.xml Current version: 3. There are new configuration files for URL Rewrite and WebDAV Profiles.
    • /config/studio/administration/site-config-tools.xml Current version: 2. There are new datasources for WebDAV file management.

    If you are certain that one of those files is already up to date in your site, you can add the version tag with the latest value to prevent the upgrades from being applied to it.

  4. Groups Update

    Groups are now at the system level instead of per site. As mentioned above, the Groups tool has been removed from siteConfig and is now in the Main Menu. By default, Crafter CMS has the following groups available after a fresh install: system_admin, site_admin, site_author, site_developer, site_publisher, and site_reviewer. Users added to the system_admin group has the role system_admin that has permissions to create users, create site, add users to groups, etc. Users added to any of the default groups has permissions for all sites created in Studio.

  5. Site Membership Update

    Site membership of a user is now determined by a mapping of group membership to roles within a site using the mapping file role-mappings.xml (see Role Mappings on how to configure the role mappings). Note the new default groups when you create a site as noted above, these are automatically mapped to roles when using the built-in blueprints.

    When upgrading a site, the default groups in the site are auto updated as follows:

    3.0 Default Groups ==>
    3.1 Default Groups
    Admin
    {site_name}_admin
    Author
    {site_name}_author
    Developer
    {site_name}_developer
    Publisher
    {site_name}_publisher
    Reviewer
    {site_name}_reviewer

    For example, if user john is a member of group Developer (one of the default groups) in the site mysite, after upgrading, user john will be a member of group mysite_developer.

Some More Things to Note

There are a few more things to note when upgrading to Crafter CMS 3.1 from 3.0.

  1. Studio authentication now uses a chain, with the internal database as the Studio default authentication. For more information, see Configuring Studio Security

  2. The LDAP authentication configuration has been updated. The attribute siteId has been removed and is no longer needed since site membership of a user is now determined by group membership. Please see Configure LDAP Authentication for the updated configuration.

  3. The headers based authentication configuration has been updated. The groups header value should just be a comma separated list of groups that a user belongs to. In the previous version, 3.0.x, the groups header value contained a comma separated list of sites and groups. Please update the groups header value of users to contain only a comma separated list of groups the user belongs to. Please see Configure Headers Based Authentication for the updated configuration.

  4. The default search engine for Crafter CMS is now Elasticsearch as opposed to Solr, learn more at Why Elasticsearch.

    • If you’re happy with Solr, you can keep using it as it is fully supported. However, please bear in mind:

      • New features, like GraphQL support, require Elasticsearch.
      • Studio requires Elasticsearch for authoring search, so that will get installed and used regardless.
    • If you’d like to switch to Elasticsearch, please read Migrating a site from Solr to Elasticsearch.

Let’s begin upgrading your Crafter CMS install.

Upgrade Crafter CMS

  1. Review the release notes for the version you are upgrading to, which contains specific information on the changes that have been made and how it may affect you when upgrading to that specific version.
  2. Backup your Crafter CMS 3.0.x install
  3. Download the Crafter CMS 3.1.0 bundle version and extract the files
  4. In your Crafter CMS 3.0.x install, copy/paste or move the data folder CRAFTER_3.0.x_INSTALLATION/data to your new CRAFTER_3.1.0_INSTALLATION install folder
  5. Migrate sites to Elasticsearch (recommended) by following this guide: Migrating a site from Solr to Elasticsearch. You can continue using Crafter Search and Solr as the search engine, by following Using Crafter Search and Solr
  6. Start your upgraded Crafter CMS, then follow the steps below for Create Authoring Targets, Update the Index Format of the Preview Targets and Update the Paths in the Targets for all upgraded sites.
    • If a site has not been migrated to Elasticsearch, follow additionally the steps under Updates for Solr.
    • If a site uses a default dependency resolver configuration file from a previous Crafter CMS installation version, consider deleting your dependency resolver configuration file and it will then use the default dependency resolver configuration with rules matching what’s in this sample CRAFTER_3.1.0_INSTALLATION/data/repos/global/configuration/dependency/resolver-config.xml
    • If a site has a customized dependency resolver configuration file, please compare your dependency resolver configuration with the default dependency resolver file CRAFTER_3.1.0_INSTALLATION/data/repos/global/configuration/dependency/resolver-config.xml and make changes as required.
  7. Verify that the authoring and delivery environments are functioning as intended.

Create Authoring Targets

Starting with Crafter CMS 3.1.0, Studio will use Elasticsearch to index all sites to provide the new features in the authoring search. For all existing sites a new target must be created using the Deployer API:

  1. Create the new target:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    curl --request POST \
      --url http://localhost:9191/api/1/target/create \
      --header 'content-type: application/json' \
      --data '{
      "env": "authoring",
      "site_name": "SITE_NAME",
      "template_name": "authoring",
      "repo_url": "INSTALL_DIR/data/repos/sites/SITE_NAME/sandbox"
    }'
    
  2. Index all content

    1
    2
    3
    4
    5
    6
    curl --request POST \
      --url http://localhost:9191/api/1/target/deploy/authoring/SITE_NAME \
      --header 'content-type: application/json' \
      --data '{
      "reprocess_all_files": true
    }'
    

Update the Index Format of the Preview Targets

The preview Deployer targets in the Authoring environment need to be updated to include the new preview index format:

  1. Go to AUTHORING_INSTALL_DIR/data/deployer/targets.

  2. For each target YAML file ending in -preview, below the localRepoPath property, add the following property with the same indentation:

    search:
      indexIdFormat: '%s-preview'
    

Update the Paths in the Targets

The Deployer targets needs the repository path to be updated to point to the new local repository path:

For Authoring environments, to update the local repository path:

  1. Go to AUTHORING_INSTALL_DIR/data/deployer/targets.

  2. For each target YAML file ending in -preview, modify the localRepoPath property value with the new path of the site sandbox repository:

    1
    localRepoPath: AUTHORING_INSTALL_DIR/data/repos/sites/SITE_NAME/sandbox
    

For Delivery environments, to update the repository path:

  1. Go to DELIVERY_INSTALL_DIR/data/deployer/targets.

  2. For each target YAML file ending in -default, modify the deployment:pipeline:remoteRepo:url: property value with the new path of the site published repository:

    1
    2
    3
    4
    5
    deployment:
      pipeline:
        - processorName: gitPullProcessor
          remoteRepo:
            url: AUTHORING_INSTALL_DIR/data/repos/sites/SITE_NAME/published
    

Updates for Solr

The following are updates only required if you’re going to keep using Solr as your search engine.

Enable Crafter Search in the Targets

You need to update the Authoring and Delivery Deployer targets to enable Crafter Search use:

  1. Go to CRAFTERCMS_INSTALL_DIR/data/deployer/targets.

  2. For each target YAML file ending in -preview in case of Authoring, or in -default.yaml in case of Delivery, below the localRepoPath property, add the following property with the same indentation:

    crafterSearchEnabled: true
    

Upgrade Solr Cores

After upgrading your Crafter CMS install, you will need to recreate the Solr cores and reindex all content.

For Authoring environments, use the following commands to upgrade the Preview cores:

  1. Delete the existing core.

    1
    2
    curl --request POST \
      --url http://localhost:8080/crafter-search/api/2/admin/index/delete/SITE_NAME
    
  2. Create the new core.

    1
    2
    3
    4
    5
    6
    curl --request POST \
      --url http://localhost:8080/crafter-search/api/2/admin/index/create \
      --header 'content-type: application/json' \
      --data '{
      "id": "SITE_NAME-preview"
    }'
    
  3. Reindex all content.

    1
    2
    3
    4
    5
    6
    curl --request POST \
      --url http://localhost:9191/api/1/target/deploy/preview/SITE_NAME \
      --header 'content-type: application/json' \
      --data '{
      "reprocess_all_files": true
    }'
    

For Delivery environments that can have downtime during the upgrade you can use the following commands:

  1. Delete the existing core.

    1
    2
    curl --request POST \
      --url http://localhost:9080/crafter-search/api/2/admin/index/delete/SITE_NAME
    
  2. Create the new core.

    1
    2
    3
    4
    5
    6
    curl --request POST \
      --url http://localhost:9080/crafter-search/api/2/admin/index/create \
      --header 'content-type: application/json' \
      --data '{
      "id": "SITE_NAME"
    }'
    
  3. Reindex all content.

    1
    2
    3
    4
    5
    6
    curl --request POST \
      --url http://localhost:9192/api/1/target/deploy/default/SITE_NAME \
      --header 'content-type: application/json' \
      --data '{
      "reprocess_all_files": true
    }'
    

For Delivery environments that cannot have downtime you can follow the guide for Reindexing Content Without Disrupting Service in Production