> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.weltpixel.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Migrating from manual SSH installation to Composer Installation

Starting with version 1.16.0 of all of our products, we've introduced Composer Installation. This has become the sole available installation method for all WeltPixel Products, including the Google Analytics 4 integration, the Pearl Theme and all other extensions. This means products and new updates will no longer be provided via zip files.

If you already have your WeltPixel product installed via SSH (in the `app/code/WeltPixel` directory), you'll need to migrate to Composer Installation. There are numerous advantages to this, including:

* Significantly increased security
* Faster, easier updates
* Cleaner codebase and maintainability

The migration process is very simple, and we'll address it in the sections below.

## Composer Setup

To gain access to Composer Installation, follow the steps below:

1. Log in to your customer account on the [WeltPixel website](https://www.weltpixel.com/customer/account/login/)
2. Use the navigation menu on the left to head into **My Products**.
3. Find your product and click **Enable Composer**. The page will refresh.
4. At the top of the page, you'll see your Composer Configuration Commands.
5. Run these commands in the root of your Magento 2 project.

## Individual WeltPixel extensions (includes the Google Analytics & Social Marketing Suite Pro and Stack Framework)

**Note:** Please ensure you perform these changes on a development/staging environment first. Additionally, ensure your Magento instance is in developer mode when doing so. When migrating to production, ensure you have a backup.

To migrate to Composer Installation for individual products and packages (excluding the Pearl Theme), you'll need to remove the existing extension files from the `app/code` directory. To do this, you can simply remove the entire WeltPixel folder in `app/code`:

Head into **app/code**
```bash
rm -rf WeltPixel
```

After the WeltPixel folder is removed, you'll be able to properly install your product(s) via Composer with the installation commands found in your WeltPixel account's **My Products** section. These are revealed when you click the **Enable Composer** button. For example, if you want to install the Google Analytics 4 PRO extension via composer, after enabling Composer access via the button, you can run the following command to install the extension, after you head back into the Magento root:

```bash
composer require weltpixel/module-ga4-pro
```

**Note:** If your product has additional satellite products that can be installed (for example, the Hyvä theme compatibility modules for the Google Analytics 4 PRO extension), you'll find the Composer installation commands for those as well.

Repeat this process for all extensions you've purchased and want to install via composer.

## Pearl Theme for Magento 2

**Note:** Please ensure you perform these changes on a development/staging environment first. Additionally, ensure your Magento instance is in developer mode when doing so. When migrating to production, ensure you have a backup.

To migrate to Composer Installation for the Pearl Theme, there are a few extra steps required. You'll need to remove the extension files from `app/code`, as well as the theme files from `app/design`. To do this, follow the process below:

**Important:** If you have modifications/customizations in the `weltpixel_custom` Child Theme (or other created Child Themes), don't remove it/them from `app/design`.

Head into **app/code**
```bash
rm -rf WeltPixel
```

Head into **app/design/frontend/Pearl**
```bash
rm -rf weltpixel
```

Once you've removed the files, you can find the Pearl Theme installation commands in your WeltPixel account's **My Products** section. Hit the **Enable Composer** button (if you haven't already), which will reveal the Composer Installation commands. The main command depends on your Pearl Theme edition:

**Essential Pack**
```bash
composer require weltpixel/m2-theme-frontend-weltpixel-essential
```

**Professional Pack**
```bash
composer require weltpixel/m2-theme-frontend-weltpixel
```

**Important:** Below the main installation command is the command to install the `weltpixel_custom` Child Theme. You only need to run this command if you've removed the default Child Theme from `app/design/frontend/Pearl`.

## Pearl Theme for Magento 2 on Commerce Cloud

To properly install on Magento Commerce Cloud, the process is largely the same:

1. Clone your repo locally.
2. Remove the files from `app/code` and `app/design/frontend/Pearl`.
3. Download the updated Magento Cloud Installation Patches from Github: [Link](https://github.com/Weltpixel/magento2-weltpixel-pearl-miscellaneous/tree/master/Magento%20Commerce%20Cloud%20Patch/Composer%20installation%20%28vendor%29)
4. Complete with the normal upgrade/installation steps for Magento Cloud:

* [Ideal State](https://support.weltpixel.com/hc/en-us/articles/360017233900-How-to-Install-the-Pearl-Theme-on-a-Magento-Cloud-Ideal-State-environment)
* [Non-ideal State](https://support.weltpixel.com/hc/en-us/articles/115000614253-How-to-install-the-Pearl-Theme-on-Magento-Commerce-Cloud-using-UNIX-systems)

## Troubleshooting

### Possible issues after migrating

**License is requested for Mobile Detect in the Magento Admin after installing the Pearl Theme via Composer**

This happens because of the Magento Admin user session. It should be easily resolvable by logging out of the Magento Admin user and logging back in.

**Frontend exception: Required parameter ‘theme_dir’ was not passed after installing the Pearl Theme via Composer**

This happens when the `weltpixel_custom` Child Theme was removed from `app/design/frontend/Pearl` but was not re-installed via composer. To solve this, install the Child Theme via Composer with:

```bash
composer require weltpixel/m2-theme-frontend-weltpixel-custom
```