> ## 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 Magento Commerce Cloud - using UNIX systems

This guide covers installing the Pearl Theme on Magento Commerce Cloud environments where Static Content Deployment (SCD) happens in the **Deploy hook**.  
If your environment has SCD in the **Build hook**, follow this guide instead: [How to install the Pearl Theme on Magento Cloud - Ideal State Environment](https://support.weltpixel.com/hc/en-us/articles/360017233900-How-to-Install-the-Pearl-Theme-on-a-Magento-Cloud-Ideal-State-environment).

---

### Step 1. Clone the Cloud repository 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 was added

git clone <branch_name> user@git.us.magento.cloud:repo.git <folder_name>
```

You can find the exact clone command in your Cloud Account.  

![magento-cloud-git-clone.png](https://storage.crisp.chat/users/helpdesk/website/-/6/6/f/1/66f18efee4688c00/cf3f5b6d-c306-475e-92ba-d924f8_1wtfrko.png)

---

### Step 2. Copy the Pearl Theme files
Upload the `app` and `pub` folders from the **Theme Files (Magento Commerce)** directory into the root of your Magento installation.  

> 💡 If you’ve only upgraded the theme code, you still need to re-apply the latest Commerce Cloud Patch (Step 3 and Step 4).

---

### Step 3. Apply the Commerce Cloud patch (Non-Ideal State)
Copy the content of the **Patches/Magento Commerce Cloud patch/Non-Ideal State Environment** folder into your Magento root.  
Merge with `pub` but **do not overwrite it**.

After patching:
- `pearl_cloud_setups.sh` should be in the Magento root.
- `pub/media/weltpixel_css/` should contain required files.

![weltpixel-css-files.png](https://storage.crisp.chat/users/helpdesk/website/-/c/9/3/1/c93194c4daf5f80/f99c6e1b-07f8-42ca-bb45-4be7d8_cznl55.png)

---

### Step 4. Run the patch script
Ensure the script is executable:

```bash
chmod +x pearl_cloud_setups.sh
./pearl_cloud_setups.sh
```

A `DONE` message confirms success.

---

### Step 5. Verify symlinks
Check that `css` directories in the following locations are **symlinks, not folders**:

```
app/code/WeltPixel/CategoryPage/view/frontend/web/css
app/code/WeltPixel/CustomFooter/view/frontend/web/css
app/code/WeltPixel/CustomHeader/view/frontend/web/css
app/code/WeltPixel/FrontendOptions/view/frontend/web/css
```

**Before patch:** `css` is a folder.  
![ece-before-patch.png](https://storage.crisp.chat/users/helpdesk/website/-/c/5/e/f/c5efc1284e6b5000/cd4424b8-9e5d-4713-86bb-79dda8_14gkh5q.png)

**After patch:** `css` is a symlink.  
![ece-after-patch.png](https://storage.crisp.chat/users/helpdesk/website/-/d/b/7/6/db76e6f7d6fe1000/1f44be19-8c40-490f-9779-ea3998_160ckj4.png)

---

### Step 6. Update `.gitignore`
Unhide `.gitignore` and ensure:
1. The first line is not `*`.  
2. Add these at the **end**:

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

![gitignore-update.png](https://storage.crisp.chat/users/helpdesk/website/-/a/9/4/3/a9439a468181c800/295f7b39-3b9b-42eb-834c-fb2f8c_15jp4lv.png)

---

### Step 7. Move SCD to the Deploy hook
SCD must run in the **Deploy hook**, not Build, because DB access is required.  
Update `.magento.env.yaml`:

```yaml
stage:
  build:
    SKIP_SCD: true
  deploy:
    SKIP_SCD: false
```

![env-yaml-config.png](https://storage.crisp.chat/users/helpdesk/website/-/9/f/a/6/9fa6532f7c46c800/7f6fe28d-f4ab-4369-be9f-a75c52_1w651f.png)

---

### Step 8. Commit to Git
```bash
git status
git add --all
git commit -m "Install Pearl Theme"
git branch  # verify branch
git push origin <branch_name>
```

---

### Step 9. Activate the Pearl Theme

**From Magento Admin:**
- Go to `System > Configuration > Applied Theme > Custom Pearl Theme for Magento 2`
- Regenerate Pearl Theme LESS/CSS
- Flush cache

**Via 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
```

---

### Step 10. Pre-configure Pearl Theme via SSH
Pick a layout from the [Pearl Demo Store](http://pearl.weltpixel.com).  

Example (Home Page V10, Header V1, 3-column Category, Product Page 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 CSS/LESS generation
Update `.magento.app.yaml`:

```yaml
hooks:
  build: |
    php ./vendor/bin/ece-tools build:generate
    php ./vendor/bin/ece-tools build:transfer

  deploy: |
    php ./vendor/bin/ece-tools deploy

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

---

✅ **Done! The Pearl Theme is installed on Magento Commerce Cloud.**

---

### FAQ – SSH Access
1. Upload your **public key** in Cloud Account > SSH Keys.  
2. Set private key permissions:  

```bash
chmod 600 id_weltpixel_rsa
```

3. Connect via SSH:  

```bash
ssh -i id_weltpixel_rsa username@cloudserver
```

![cloud-ssh-access.png](https://storage.crisp.chat/users/helpdesk/website/-/f/0/c/f/f0cfeae4270a2000/d88e6461-25a8-4e41-b63a-bcd8e2_ltne9v.png)

More details: [Configure multiple SSH identities](https://confluence.atlassian.com/bitbucket/configure-multiple-ssh-identities-for-gitbash-mac-osx-linux-271943168.html)