Restore an environment

If you encounter issues in the integration environment and do not have a valid backup, try restoring your environment using one of the following methods:

  • Reset or revert the code in the Git branch
  • Uninstall the Commerce application
  • Force a redeployment
  • Manually reset the database
TIP
For help with stuck deployments, use the Adobe Commerce deployment troubleshooter in the Commerce Help Center.

Reset the Git branch

Resetting your Git branch reverts the code to a stable state in the past.

To reset your branch:

  1. On your local workstation, change to your project directory.

  2. Review the Git commit history. Use --oneline to show abbreviated commits on one line:

    code language-bash
    git log --oneline
    

    Sample response:

    code language-terminal
    6bf9f45 (HEAD -> master, magento/master, magento/develop, magento/HEAD, develop) Create composer.lock
    34d7434 2.4.6 upgrade
    b69803c Update composer.lock
    c1bca24 Add sample data
    ec604c3 Update magento/ece-tools
    ...
    
  3. Choose a commit hash that represents the last known stable state of your code.

    To reset your branch to its original initialized state, find the first commit that created your branch. You can use --reverse to display history in reverse chronological order.

  4. Use the hard reset option to reset your branch. Be careful using this command because it discards all changes since the chosen commit.

    code language-bash
    git reset --hard <commit>
    
  5. Push your changes to trigger a redeployment, which reinstalls Adobe Commerce.

    code language-bash
    git push --force <origin> <branch>
    

Uninstall Commerce

Uninstalling the Commerce application returns your environment to an original state by restoring the database, removing the deployment configuration, and clearing the var/ subdirectories. This guidance also resets your git branch to an earlier stable state. If you do not have a recent backup, but you can access the remote environment using SSH, follow these steps to restore your environment:

  • Disable configuration management
  • Uninstall Adobe Commerce
  • Reset the git branch

Uninstalling the Adobe Commerce software drops and restores the database, removes the deployment configuration, and clears the var/ subdirectories. It is important to disable Configuration management so that it does not automatically apply the previous configuration settings during the next deployment. Make sure that your app/etc/ directory does not contain the config.php file.

To uninstall the Adobe Commerce software:

  1. On your local workstation, change to your project directory.

  2. Use SSH to log in to the remote environment.

    code language-bash
    magento-cloud ssh
    
  3. Remove the configuration file.

    • For Adobe Commerce 2.2 and later:

      code language-bash
      rm app/etc/config.php
      
    • For Adobe Commerce 2.1:

      code language-bash
      rm app/etc/config.local.php
      
  4. Uninstall the Adobe Commerce application.

    code language-bash
    php bin/magento setup:uninstall -n
    
  5. Confirm that Adobe Commerce was successfully uninstalled.

    The following message displays to confirm a successful uninstallation:

    code language-terminal
    [SUCCESS]: Magento uninstallation complete.
    
  6. Clear the var/ subdirectories.

    code language-bash
    rm -rf var/*
    
  7. Log out.

TIP
Optionally, it is a good practice to clean build caches.
code language-bash
magento-cloud project:clear-build-cache

Force a redeployment

If you have attempted to uninstall Adobe Commerce and your deployment continues to fail, you can try to manually force a redeployment.

git commit --allow-empty -m "<message>" && git push <origin> <branch>

Reset the database

If you have attempted to uninstall Adobe Commerce and the command failed or could not complete, you can manually reset the database.

To reset the database:

  1. On your local workstation, change to your project directory.

  2. Use SSH to log in to the remote environment.

    code language-bash
    magento-cloud ssh
    
  3. Connect to the database.

    code language-bash
    mysql -h database.internal
    
  4. Drop the main database.

    code language-shell
    drop database main;
    
  5. Create an empty main database.

    code language-shell
    create database main;
    
  6. Delete the following configuration files.

    • config.php
    • config.php.bak
    • env.php
    • env.php.bak
  7. Log out and trigger a redeployment.

    code language-bash
    magento-cloud environment:redeploy
    
WARNING
The deployment process begins when you perform a merge, push, or synchronization of your environment, or when you trigger a manual redeployment, during which the Commerce application is in maintenance mode. For a Production environment, Adobe recommends completing this work during off-peak hours to avoid service disruptions.
recommendation-more-help
05f2f56e-ac5d-4931-8cdb-764e60e16f26