Skip to content
This repository has been archived by the owner on Nov 16, 2021. It is now read-only.

Uninstalling Lightning

Jump to bottom
Adam edited this page Jul 29, 2021 · 118 revisions

This procedure has been tested, but the unexpected can always occur! You should absolutely back up your site's database and configuration before proceeding!

This page explains how to migrate your site off of the Lightning (or Headless Lightning) profile. Once you finish this process, you will no longer be running the Lightning distribution, but you will still be using the individual Lightning components (API, Layout, Media, and Workflow), which you can either continue using, or migrate away from at your convenience.

Additional background information may be found at the FAQ about Lightning's end of life in November 2021.

Prerequisites

  • Your site must use Composer to manage its code base and dependencies. Most Lightning sites will natively support Composer (including sites created with Lightning Project or BLT Project); if your site is Composer-ready, you should be able to add modules to your site with: composer require drupal/MODULENAME. If your site is NOT Composer-ready, you will need to convert it, either manually or with a utility like Composerize Drupal.
  • Drush 9.7 or later.
  • The extension_discovery_scan_tests option in your site's settings.php (or one of the files included by it) should be set to FALSE. This is already the case for most sites, but may be an issue in development environments. If the uninstaller says that the lightning_extender profile uses Lightning as a base profile, but then raises an error along the lines of "The profile lightning_extender does not exist" when you try to decouple it, this is a likely culprit.

Uninstalling Lightning

The easiest way to uninstall Lightning is to use our automated uninstall tool, which is what these instructions cover. See "What is this doing?" below for more information about what actually happens under the hood.

  1. Update to the latest version of Lightning for your major version line, the way you normally would, following any config export and deployment procedures. Specifically:
  • If you're using Lightning 3, use the latest 3.4.x version.
  • If you're using Lightning 4, use the latest 4.1.x version.
  • If you're using Lightning 5, use the latest 5.2.x version.
  • If you're using Headless Lightning, use the latest 1.9.x version.
  1. If you're using BLT and drush status --fields=install-profile reports that you're directly using the lightning or headless_lightning profiles, edit blt/blt.yml and change the profile key to minimal. Do NOT do this if you're using a sub-profile of Lightning or Headless Lightning.
  2. Run drush pm:uninstall lightning to use the automated uninstall tool, which will ensure that Lightning can be uninstalled safely by making the necessary code and configuration changes. If you're using a sub-profile of Lightning, you can allow the uninstaller to decouple all sub-profiles automatically by answering the prompt, or see "Decoupling a sub-profile from Lightning" below to do it manually (all sub-profiles, in use or not, must be decoupled from Lightning before you continue). IMPORTANT: If you're using Headless Lightning or a sub-profile of it, run drush pm:uninstall headless_lightning BEFORE running drush pm:uninstall lightning.
  3. Export config, then commit all changes and deploy them to your hosting. At a minimum, you should expect to see changes in your project-level composer.json (see "Example composer.json configuration" below for more information on this) and core.extension config.
  4. Check that everything is still working properly after deployment. If so, you can physically remove Lightning from the code base:
composer remove acquia/lightning drupal/profile_switcher --no-update
composer update --with-all-dependencies
  1. If Lightning is still physically present after this, you probably have a dependency that is requiring it. Run composer why acquia/lightning to find the culprit.
  2. Final clean-up! Edit the project's composer.json and remove any patch whose name is prefixed with "REMOVE" (this is optional; the patches are harmless, but serve no further purpose). Then run composer update, commit changes, and deploy.

What is this doing?

The automated uninstall tool does the following steps, all of which are required to safely uninstall Lightning.

  • Confirm that there are no installed modules or themes physically located inside the Lightning profile directory; if there are, Lightning cannot be uninstalled. In most cases, this will not be an issue.
  • Check if there are any install profiles, in use or not, that use Lightning as their immediate parent (i.e., base profile). If so, modify them so that they no longer require Lightning. See "Decoupling a sub-profile from Lightning" below for information on how to do this manually.
  • Install the profile_switcher module.
  • if the site is using the Lightning or Headless Lightning profiles directly, use drush switch:profile to change the site to the Minimal profile. This modifies the core.extension config and the database.
  • Modify the project-level composer.json (the location of which is automatically detected) with the following changes, as seen in "Example composer.json configuration" below. Note that existing configuration should be respected as these changes are made:
    • Ensure that all of Lightning's direct dependencies are added.
    • Ensure that Lightning's required package repositories (packages.drupal.org/8 and asset-packagist.org) are added.
    • Add patches that are brought in by Lightning.
    • Ensure that the cweagans/composer-patches plugin is configured correctly.
    • Ensure that the composer/installers plugin is configured correctly and has all the required paths.
    • Ensure that the drupal/core-composer-scaffold plugin, if in use, is configured correctly.
  • Uninstall profile_switcher.

Example composer.json configuration

ADVANCED. This section is only relevant if you want to customize your project's composer.json yourself, rather than using our automated tool as described above. You will need to merge the appropriate configuration for your major version of Lightning into your project's composer.json. This is fairly advanced, and the nuts-and-bolts of how to do it is outside the scope of this documentation. You should only need to do this if your project has special technical needs. If there any collisions with your project's existing requirements and configuration, it's okay for the existing data to "win".

Lightning 5.2.x

{
    "require": {
        "ext-dom": "*",
        "composer/composer": "^1.10.22 || ^2.0.13",
        "cweagans/composer-patches": "^1.7",
        "drupal/acquia_connector": "^1.24-rc3 || ^2.0-rc1 || ^3",
        "drupal/core": "^9.2.2",
        "drupal/inline_entity_form": "^1.0-rc7",
        "drupal/lightning_api": "^4.6",
        "drupal/lightning_core": "^5.8",
        "drupal/lightning_layout": "^2.10",
        "drupal/lightning_media": "^4.6",
        "drupal/lightning_workflow": "^3.16",
        "drupal/page_manager": "^4.0-beta6",
        "drupal/panelizer": "^5.0-beta3",
        "drupal/pendo": "^1@alpha",
        "drupal/search_api": "^1.17"
    },
    "extra": {
        "composer-exit-on-patch-failure": true,
        "drupal-scaffold": {
            "locations": {
                "web-root": "docroot/"
            }
        },
        "enable-patching": true,
        "installer-paths": {
            "docroot/core": [
                "type:drupal-core"
            ],
            "docroot/libraries/{$name}": [
                "type:drupal-library",
                "type:bower-asset",
                "type:npm-asset"
            ],
            "docroot/modules/contrib/{$name}": [
                "type:drupal-module"
            ],
            "docroot/profiles/contrib/{$name}": [
                "type:drupal-profile"
            ],
            "docroot/themes/contrib/{$name}": [
                "type:drupal-theme"
            ]
        },
        "installer-types": [
            "bower-asset",
            "npm-asset"
        ],
        "patchLevel": {
            "drupal/core": "-p2"
        },
        "patches": {
            "drupal/core": {
                "2869592 - Disabled update module shouldn't produce a status report warning": "https://www.drupal.org/files/issues/2020-02-07/2869592-remove-update-warning-34.patch",
                "[subprofile support] 1356276 - Allow profiles to define a base/parent profile and load them in the correct order / 2914389 - Allow profiles to exclude dependencies of their parent": "https://www.drupal.org/files/issues/2021-05-20/3143958-14-subprofile-support-9.2.x.patch",
                "REMOVE: Allow installation profile to be changed from Lightning during config sync": "https://www.drupal.org/files/issues/2021-01-21/3143958-12-change-profile-config-sync-9.1.x.patch"
            }
        },
        "patches-ignore": {
            "drupal/lightning_core": {
                "drupal/core": {
                    "2869592 - Disabled update module shouldn't produce a status report warning": "https://www.drupal.org/files/issues/2869592-remove-update-warning-7.patch"
                }
            }
        }
    },
    "repositories": {
        "drupal": {
            "type": "composer",
            "url": "https://packages.drupal.org/8"
        },
        "assets": {
            "type": "composer",
            "url": "https://asset-packagist.org"
        }
    }
}

Lightning 4.1.x

{
    "require": {
        "ext-dom": "*",
        "cweagans/composer-patches": "^1.6",
        "drupal/acquia_connector": "*",
        "drupal/core": "~8.9.17",
        "drupal/libraries": "^3.0",
        "drupal/lightning_api": "^4.4",
        "drupal/lightning_core": "^5.2",
        "drupal/lightning_layout": "^2.10",
        "drupal/lightning_media": "^3.21 || ^4.6",
        "drupal/lightning_workflow": "^3.14"
    },
    "extra": {
        "composer-exit-on-patch-failure": true,
        "drupal-scaffold": {
            "locations": {
                "web-root": "docroot/"
            }
        },
        "enable-patching": true,
        "installer-paths": {
            "docroot/core": [
                "type:drupal-core"
            ],
            "docroot/libraries/{$name}": [
                "type:drupal-library",
                "type:bower-asset",
                "type:npm-asset"
            ],
            "docroot/modules/contrib/{$name}": [
                "type:drupal-module"
            ],
            "docroot/profiles/contrib/{$name}": [
                "type:drupal-profile"
            ],
            "docroot/themes/contrib/{$name}": [
                "type:drupal-theme"
            ]
        },
        "installer-types": [
            "bower-asset",
            "npm-asset"
        ],
        "patchLevel": {
            "drupal/core": "-p2"
        },
        "patches": {
            "drupal/core": {
                "2869592 - Disabled update module shouldn't produce a status report warning": "https://www.drupal.org/files/issues/2020-02-07/2869592-remove-update-warning-34.patch",
                "[subprofile support] 1356276 - Allow profiles to define a base/parent profile and load them in the correct order / 2914389 - Allow profiles to exclude dependencies of their parent": "https://www.drupal.org/files/issues/2021-01-14/3143958-11-subprofile-support-8.9.x.patch",
                "REMOVE: Allow installation profile to be changed from Lightning during config sync": "https://www.drupal.org/files/issues/2021-01-21/3143958-12-change-profile-config-sync-9.1.x.patch"
            }
        },
        "patches-ignore": {
            "drupal/lightning_core": {
                "drupal/core": {
                    "2869592 - Disabled update module shouldn't produce a status report warning": "https://www.drupal.org/files/issues/2869592-remove-update-warning-7.patch",
                    "1356276 - Allow profiles to define a base/parent profile and load them in the correct order": "https://www.drupal.org/files/issues/2019-11-05/1356276-531-8.8.x-4.patch",
                    "2914389 - Allow profiles to exclude dependencies of their parent": "https://www.drupal.org/files/issues/2018-07-09/2914389-8-do-not-test.patch"
                }
            }
        }
    },
    "repositories": {
        "drupal": {
            "type": "composer",
            "url": "https://packages.drupal.org/8"
        },
        "assets": {
            "type": "composer",
            "url": "https://asset-packagist.org"
        }
    }
}

Lightning 3.4.x

{
    "require": {
        "ext-dom": "*",
        "cweagans/composer-patches": "^1.6.4",
        "drupal/acquia_connector": "*",
        "drupal/core": "~8.9.17",
        "drupal/libraries": "^3.0",
        "drupal/lightning_api": "^4.1",
        "drupal/lightning_core": "^5.2",
        "drupal/lightning_layout": "^1.12",
        "drupal/lightning_media": "^3.21 || ^4.6",
        "drupal/lightning_workflow": "^3.6"
    },
    "extra": {
        "composer-exit-on-patch-failure": true,
        "drupal-scaffold": {
            "locations": {
                "web-root": "docroot/"
            }
        },
        "enable-patching": true,
        "installer-paths": {
            "docroot/core": [
                "type:drupal-core"
            ],
            "docroot/libraries/{$name}": [
                "type:drupal-library",
                "type:bower-asset",
                "type:npm-asset"
            ],
            "docroot/modules/contrib/{$name}": [
                "type:drupal-module"
            ],
            "docroot/profiles/contrib/{$name}": [
                "type:drupal-profile"
            ],
            "docroot/themes/contrib/{$name}": [
                "type:drupal-theme"
            ]
        },
        "installer-types": [
            "bower-asset",
            "npm-asset"
        ],
        "patchLevel": {
            "drupal/core": "-p2"
        },
        "patches": {
            "drupal/core": {
                "2869592 - Disabled update module shouldn't produce a status report warning": "https://www.drupal.org/files/issues/2020-02-07/2869592-remove-update-warning-34.patch",
                "[subprofile support] 1356276 - Allow profiles to define a base/parent profile and load them in the correct order / 2914389 - Allow profiles to exclude dependencies of their parent": "https://www.drupal.org/files/issues/2021-01-14/3143958-11-subprofile-support-8.9.x.patch",
                "REMOVE: Allow installation profile to be changed from Lightning during config sync": "https://www.drupal.org/files/issues/2021-01-21/3143958-12-change-profile-config-sync-9.1.x.patch"
            }
        },
        "patches-ignore": {
            "drupal/lightning_core": {
                "drupal/core": {
                    "2869592 - Disabled update module shouldn't produce a status report warning": "https://www.drupal.org/files/issues/2869592-remove-update-warning-7.patch",
                    "[subprofile support] 1356276 - Allow profiles to define a base/parent profile and load them in the correct order": "https://www.drupal.org/files/issues/2019-11-05/1356276-531-8.8.x-4.patch",
                    "[subprofile support] 2914389 - Allow profiles to exclude dependencies of their parent": "https://www.drupal.org/files/issues/2018-07-09/2914389-8-do-not-test.patch"
                }
            }
        }
    },
    "repositories": {
        "drupal": {
            "type": "composer",
            "url": "https://packages.drupal.org/8"
        },
        "assets": {
            "type": "composer",
            "url": "https://asset-packagist.org"
        }

    }
}

Headless Lightning 1.9.x

{
    "require": {
        "acquia/headless_lightning": "dev-eol",
        "ext-dom": "*",
        "cweagans/composer-patches": "^1.6.4",
        "drupal/acquia_connector": "^1.24-rc3 || ^2.0-rc1 || ^3",
        "drupal/core": "^9.2.2",
        "drupal/inline_entity_form": "^1.0-rc7",
        "drupal/lightning_api": "^4.6",
        "drupal/lightning_core": "^5.8",
        "drupal/lightning_layout": "^2.10",
        "drupal/lightning_media": "^4.6",
        "drupal/lightning_workflow": "^3.16",
        "drupal/page_manager": "^4.0-beta6",
        "drupal/panelizer": "^5.0-beta3",
        "drupal/pendo": "^1@alpha",
        "drupal/search_api": "^1.17"
    },
    "extra": {
        "composer-exit-on-patch-failure": true,
        "drupal-scaffold": {
            "file-mapping": {
                "[project-root]/.editorconfig": false,
                "[project-root]/.gitattributes": false,
                "[web-root]/.csslintrc": false,
                "[web-root]/INSTALL.txt": false,
                "[web-root]/example.gitignore": false,
                "[web-root]/modules/README.txt": false,
                "[web-root]/profiles/README.txt": false,
                "[web-root]/robots.txt": false,
                "[web-root]/sites/README.txt": false,
                "[web-root]/themes/README.txt": false,
                "[web-root]/web.config": false
            },
            "locations": {
                "web-root": "docroot/"
            }
        },
        "enable-patching": true,
        "installer-paths": {
            "docroot/core": [
                "type:drupal-core"
            ],
            "docroot/libraries/{$name}": [
                "type:drupal-library",
                "type:bower-asset",
                "type:npm-asset"
            ],
            "docroot/modules/contrib/{$name}": [
                "type:drupal-module"
            ],
            "docroot/profiles/contrib/{$name}": [
                "type:drupal-profile"
            ],
            "docroot/themes/contrib/{$name}": [
                "type:drupal-theme"
            ]
        },
        "installer-types": [
            "bower-asset",
            "npm-asset"
        ],
        "patchLevel": {
            "drupal/core": "-p2"
        },
        "patches": {
            "drupal/core": {
                "2869592 - Disabled update module shouldn't produce a status report warning": "https://www.drupal.org/files/issues/2020-02-07/2869592-remove-update-warning-34.patch",
                "[subprofile support] 1356276 - Allow profiles to define a base/parent profile and load them in the correct order / 2914389 - Allow profiles to exclude dependencies of their parent": "https://www.drupal.org/files/issues/2021-05-20/3143958-14-subprofile-support-9.2.x.patch",
                "REMOVE: Allow installation profile to be changed from Lightning during config sync": "https://www.drupal.org/files/issues/2021-01-21/3143958-12-change-profile-config-sync-9.1.x.patch"
            }
        },
        "patches-ignore": {
            "drupal/lightning_core": {
                "drupal/core": {
                    "2869592 - Disabled update module shouldn't produce a status report warning": "https://www.drupal.org/files/issues/2869592-remove-update-warning-7.patch"
                }
            }
        }
    },
    "repositories": {
        "drupal": {
            "type": "composer",
            "url": "https://packages.drupal.org/8"
        },
        "asset-packagist": {
            "type": "composer",
            "url": "https://asset-packagist.org"
        }
    }
}

Decoupling a sub-profile from Lightning

ADVANCED. This describes how to manually modify a sub-profile so that it no longer has a dependency on Lightning. This information is provided for reference; the drush pm:uninstall lightning command can make these changes automatically.

  1. Edit the info file and make the following changes:
  • Remove the base profile key.
  • Copy the contents of the install and themes lists from Lightning's info file, into the sub-profile's install and themes lists. Remove any items from those lists which appear in the sub-profile's exclude list.
  • If the sub-profile has a dependencies list, ensure that lightning is not in it.
  1. Copy all the files from Lightning's config/install and config/optional directories into the sub-profile's config/optional directory. If any of those files are already overridden by the sub-profile, the sub-profile's versions should "win".
  2. Remove the exclude list (this step is optional, but the list is no longer needed).

If you have a sub-profile whose parent is Headless Lightning, the process to decouple it is essentially the same. Simply substitute headless_lightning instead of lightning as you follow the instructions above, and copy the appropriate files and profile information from Headless Lightning, rather than Lightning. (Note that you'll need to be using Headless Lightning 1.9.x for this to be successful.)

Clone this wiki locally