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.

Step 1. Clone the Cloud repository on UNIX / macOS (not supported on Windows)

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.

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.

Step 4. Run the patch script

Ensure the script is executable:

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.

After patch: css is a symlink.

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

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:

stage:
  build:
    SKIP_SCD: true
  deploy:
    SKIP_SCD: false

Step 8. Commit to Git

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:

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.

Example (Home Page V10, Header V1, 3-column Category, Product Page V1, Footer V3):

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:

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:

chmod 600 id_weltpixel_rsa

3. Connect via SSH:

ssh -i id_weltpixel_rsa username@cloudserver

More details: Configure multiple SSH identities

Updated on: 17/09/2025