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

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

Here’s the adjusted process:

Step 1. Clone the Cloud repo

Run 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 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

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:

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:

./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:

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

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:

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:

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

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:

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.

Updated on: 17/09/2025