> ## 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).

# How to Install the Pearl Theme on a Magento Cloud - Ideal State environment

The process for installing the theme on Magento Cloud environments where the SCD happens in the **Deploy hook** can be found here:  
[How to install the Pearl Theme on Magento Commerce Cloud - using UNIX systems](https://help.weltpixel.com/en/article/how-to-install-the-pearl-theme-on-magento-commerce-cloud-using-unix-systems-mgh3z5/)

Magento’s **Ideal State**, however, requires the SCD to happen in the **Build hook**, which is an issue for Pearl Theme because there’s no DB access there and the LESS/CSS generation fails, causing frontend issues. (More info: [Magento Smart Wizards](https://devdocs.magento.com/cloud/deploy/smart-wizards.html)).

Here’s the adjusted process:

---

## Step 1. Clone the Cloud repo

Run on **UNIX/macOS** (not supported on Windows):

```bash
git init
git config user.name "Support WeltPixel"
git config user.email "support@weltpixel.com"

eval 'ssh-agent -s'
eval $(ssh-agent -s)
ssh-add '/Users/your_user/.ssh/id_weltpixel_rsa'   # private key for Cloud Account
ssh-add -l  # verify key added, expect output like "2048 SHA256:..."

# Clone repo (exact command is shown in your Cloud account)
git clone <branch_name> user@git.us.magento.cloud:repo.git folder_name
```

---

## Step 2. Upload Theme Files

Copy **only** the `app` and `pub` folders from **Theme Files (Magento Commerce)** into the Magento root.  
⚠️ Do not copy dependency packs here.

If using multiple store views, follow this first:  
[How to use Pearl Theme on multiple store views](https://help.weltpixel.com/en/article/how-to-use-pearl-theme-on-multiple-store-views-important-update-install-instructions-ffdhrs/)

---

## Step 3. Apply the Cloud Patch

Copy contents of  
`Patches/Magento Commerce Cloud patch/Ideal State Environment`  
into the Magento root (merge with `pub`, don’t overwrite).

You should now have:

- `pearl_cloud_setups.sh` and `pearl_cloud_local_setups.sh` in root  
- `pub/media/css_weltpixel/` with patch CSS files

---

## Step 4. Run local patch

Set execution permission:

```bash
chmod +x pearl_cloud_local_setups.sh
```

If you use additional themes/locales, edit `pearl_cloud_local_setups.sh` and define them (no commas, shell arrays don’t use commas).  
Default: `weltpixel_custom`.

Run:

```bash
./pearl_cloud_local_setups.sh
```

You should see `DONE`. Check `pub/media/css_weltpixel/` for generated files.

---

## Step 5. Edit pearl_cloud_setups.sh (optional)

Edit and add themes/locales after line 34. Default: `weltpixel_custom`.

If static/media paths differ in your environment, update them here.

---

## Step 6. Run patch in Build hook

Edit `.magento.app.yaml` → Build hook:

```yaml
build: |
  php ./vendor/bin/ece-tools build:generate
  php ./vendor/bin/ece-tools build:transfer
  chmod +x pearl_cloud_setups.sh
  ./pearl_cloud_setups.sh
```

This ensures symlinks are created before LESS/CSS generation.

---

## Step 7. Update `.gitignore`

Make sure first line of `.gitignore` is **not** `*`.  
At the end, add:

```
!/pub/media/wysiwyg/pearl_theme
!/pub/media/css_weltpixel
!/pub/media/weltpixel
```

---

## Step 8. Commit changes

```bash
git status
git add --all
git commit -m "Install Pearl Theme"
git branch   # confirm correct branch
git push origin <branch_name>
```

---

## Step 9. Activate Pearl Theme

**Magento Admin:**  
System → Configuration → (select store view) → Applied Theme → Pearl Theme  
System → Cache Management → Regenerate Pearl Theme LESS/CSS  
System → Cache Management → Flush Magento Cache

**SSH:**  
```bash
php bin/magento weltpixel:theme:activate --store="GLOBAL" --themePath="Pearl/weltpixel_custom"
php bin/magento cache:clean
php bin/magento weltpixel:less:generate
php bin/magento weltpixel:css:generate --store=default
```

Create new admin user if needed:

```bash
php bin/magento admin:user:create --admin-user='username' --admin-password='password' \
  --admin-email='email@company.com' --admin-firstname='Firstname' --admin-lastname='Lastname'
```

Find admin path in `/app/etc/env.php`.

---

## Step 10. Preconfigure Pearl Theme

Generate default values for options.

Example: Home V10 + Header V1 + Category 3 columns + Product V1 + Footer V3

```bash
php bin/magento weltpixel:import:demo --store=GLOBAL --demoVersion=v10
php bin/magento weltpixel:theme:configurator --store=GLOBAL --homePage=v10 --header=v1 \
  --categoryPage=3columns --productPage=v1 --footer=v3
php bin/magento weltpixel:less:generate
php bin/magento weltpixel:css:generate --store=default
php bin/magento cache:clean
```

---

## Step 11. Automate LESS/CSS generation on deploy

In `.magento.app.yaml` add under `post_deploy`:

```yaml
post_deploy: |
  php ./vendor/bin/ece-tools post-deploy
  php ./bin/magento weltpixel:less:generate
  php ./bin/magento weltpixel:css:generate --store=default
```

---

✅ Done! Pearl Theme is now installed and configured for Magento Cloud Ideal State.