How to install the Pearl Theme on Magento Commerce Cloud - using UNIX systems

This guide is for installing the Pearl Theme on Cloud environments that have the SCD in the Deploy hook of the deployment process. For installation on instances that have the SCD in the Build hook, refer to this article: How to install the Pearl Theme on Magento Cloud - Ideal State Environment

Step 1. Clone the cloud repo locally on your UNIX / MAC OS machine or on a server. This installation is not supported via Windows Machines. 

git init (initialize git on your local machine)

git config user.name "Support WeltPixel" (add git user)

git config user.email "support@weltpixel.com" (add git email)

eval 'ssh-agent -s' 

eval $(ssh-agent -s)

ssh-add '/Users/your_user/.ssh/id_weltpixel_rsa'  (add private key associated with the Cloud Account)

ssh-add -l (verify that key was added you should receive '2048 SHA256:......' and the key location)

git clone branch_name user@git.us.magento.cloud:repo.git folder_name ( clone your cloud repository, you can find the exact command in your Cloud Account as shown in the picture below)

Step 2. Copy/upload the theme files from the 'Theme Files (Magento Commerce)' folder (only the app and pub folders) in the root of your Magento installation. (If you've only upgraded the theme code to the latest version, it is still necessary to re-apply the latest version of Commerce Cloud Patch as described in Step 3 and Step 4.)

Important: If you are using the Pearl Theme on multiple store views, make sure you follow the instructions in this article before the install/upgrade, as Pearl Theme functionality on the Store-View level has been improved starting with release 1.5.5, October 20, 2017: How to use Pearl Theme on multiple store views. Important update / install instructions. If you have a single store view, you can ignore this note.

Step 3. Copy the content of the ‘Patches/Magento Commerce Cloud patch/Non-Ideal State Environment’ folder into the root of your Magento installation. Make sure to merge with the 'pub' folder and not overwrite it. 

After the patch files are copied:

- pearl_cloud_setups.sh should be in the root of your Magento installation

and 

- under pub/media/weltpixel_css you should have the files listed below. 

Step 4. Apply the Commerce Cloud patch 

In some cases, you may need to assure the script has the proper permissions in order to be able to execute it. To do so, run the following command:

chmod +x pearl_cloud_setups.sh

On UNIX / MAC OS systems run the pearl_cloud_setups.sh script using this command in the CLI in the root of your project, where you copied the files:

./pearl_cloud_setups.sh ( sh pearl_cloud_setups.sh)

A "DONE" message should show up at the end.

Step 5. Verify the patch was applied correctly at the locations below

In order to make sure that patch was successfully applied, you can verify that symlinks were created at these locations; 'css' should be a symlink/alias and not a directory:

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
app/code/WeltPixel/CustomHeader/view/frontend/web/css

BEFORE applying the Commerce Cloud patch you can see that the 'css' folder is a directory:

AFTER applying the Commerce Cloud patch you can see that 'css' is no longer a directory but an Alias/Symlink.

How the Commerce Cloud Patch Works

Note: If you are still getting the 'path is not writable' errors when saving admin options, it means the patch was not successfully applied. Make sure you are running the script pearl_cloud_setups.sh on UNIX OS in the root of your project before committing the files to your Cloud Github repository.

In read-only environments a write limitation is encountered when generating theme LESS files based on theme admin options. As Magento Commerce Cloud environments are read-only, we cannot generate dynamic LESS files inside the theme modules. Because of this, in this patch we changed the default location of LESS files from 'app/code/WeltPixel' (read-only) to 'pub/media/css_weltpixel' (read / write).

When the pearl_cloud_setups.sh shell script is executed, it removes the CSS directories under the non-writable location 'app/code/WeltPixel/...' and creates symlinks to 'pub/media/css_weltpixel/MODULE_NAME/css directories' (as these are writable on the cloud as well.)

The Commerce Cloud patch also contains the initial module LESS files for 5 modules where we generate LESS on the fly. (CategoryPage, CustomHeader, FrontendOptions, ProductPage, QuickCart).

Once the patch is applied, you should not encounter any LESS file generation restrictions when saving Pearl Theme options in your Cloud environment.

Step 6. Add exceptions to your .gitignore file in the root of your Magento installation.

The .gitignore file may be hidden. If you do not see it, activate the option to see hidden files.

6a. Make sure no '*'is present on the first line of your .gitignore file, remove the '*' from the first line of .gitignore file if necessary.

6b. Add the lines below AT THE END of to your .gitignore file in order to allow access for media theme files to be committed to your Cloud repository. By adding them at the end you make sure that existing .gitignore settings will not overwrite these exceptions.

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

By following the instructions above, you make sure that all theme files are added to your Cloud environment.

Step 7. Assure your Static Content Deployment process happens in the Deploy hook 

This is required in order to assure the CSS can be generated in the pub/static folder. Magento recommends the Static Content Deployment happens in the Build hook for faster deployments, however, the Build hook does not provide access to the DB, so the required information for generating the CSS via the weltpixel:css:generate command is not accessible, and the command fails.

This will ensure the CSS generation process can be completed successfully as the pub/static folder remains writable on the Magento Cloud instance. When you move to the production instance, you might want to inverse the values of the variables to speed up the process. This will, however, impede the CSS generation process and will not allow you to make changes to theme design options on the fly.

Step 8. Commit the changes to your cloud GitHub repository

Go to the root of your Magento installation and run the following commands:

git status (show all new files added to your environment)

git add --all (commit all new files added)

git commit -m "Install Pearl Theme" (commit the files with the installation message)

git branch (verify you are on the correct branch)

git push origin <branch_name> (push the code to your Cloud associated branch)

Step 9. Activate the Pearl Theme

From the Magento Admin :

Go to System > Configuration > (select store view) > Edit > Applied Theme > Custom Pearl Theme for Magento 2

Go to System > Cache Management > Regenerate Pearl Theme LESS/CSS Files

Go to System > Cache Management > Flush Magento Cache

Via SSH: (you can find details on how to connect to Commerce Cloud via SSH at the end of this article)

In the root of the Magento installation execute the commands below:

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

If you don't know the admin user or admin path you can use SSH access to create a new user or find the frontend admin path: 

- Create new user:

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 via /app/etc  nano env.php 

Step 10. Pearl Theme Pre-Configuration via SSH.

It's important to execute this step in order to generate default values for the Pearl Theme options as a starting point for your project.

Visit the Pearl Theme Demo Store and choose the layout you like for each page type. Available options can be found below:

• [--homePage[="..."]] = v1, v2, v3, v4, v5, v6, v7, v8, v9, v10, v11, v12, v14, v15
• [--header[="..."]] = v1, v2, v3, v4
• [--categoryPage[="..."]] = 2columns, 3columns, 4columns, 5columns
• [--productPage[="..."]] = v1, v2, v3, v4
• [--footer[="..."]] = v1, v2, v3, v4
• [--store="..."] = default, GLOBAL
• [--demoVersion] = v1, v2, v3, v4, v5, v6, v7, v8, v9, v10, v11, v12, v14, v15

When changing between sample Home Pages make sure to run the corresponding import options as each Home Page comes with predefined theme settings.

• php bin/magento weltpixel:import:demo [--store="..."] [--demoVersion]
• php bin/magento weltpixel:theme:configurator [--store="..."] [--homePage[="..."]] [--header[="..."]] [--categoryPage[="..."]] [--productPage[="..."]] [--footer[="..."]]
• php bin/magento weltpixel:less:generate
• php bin/magento weltpixel:css:generate --store=default
• php bin/magento ca:cl

Example for how to set Home Page V10 with the corresponding V10 theme options, Header Version 1, Category Page on 3 columns, Product Page Version 1, Footer Version 3:

• 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 ca:cl

Step 11. Automate the Pearl Theme LESS/CSS generation with each deploy

After the deployment, go to the Cache Management section of your Magento Admin and Regenerate Pearl Theme LESS/CSS files in order to correctly apply all theme options.

You can automate the Pearl Theme LESS/CSS generation by adding the corresponding commands in the .magento.app.yaml file from the root of your cloud installation, these commands will automatically be executed with each deploy. You can find an example of the deploy hook structure of the .magento.app.yaml file below. 

hooks:
# We run build hooks before your application has been packaged.
build: |
php ./vendor/bin/ece-tools build:generate
php ./vendor/bin/ece-tools build:transfer
# We run deploy hook after your application has been deployed and started.
deploy: |
php ./vendor/bin/ece-tools deploy
# We run post deploy hook to clean and warm the cache. Available with ECE-Tools 2002.0.10.
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 now installed on your Magento Commerce Cloud Environment

 ***

FAQ:

#1 How To Connect to the Commerce Cloud environment via SSH:

- You will need a Private Key / Public key pair. Upload the Public Key under Cloud Account Settings > SSH Keys.

- Make sure to set secure permissions for the private key in order to be able to connect

chmod 600 id_weltpixel_rsa

- Connect as shown in the example below. Connection details can be found in the Cloud account:

ssh -i id_weltpixel_rsa username@cloudserver

Related articles: 

https://confluence.atlassian.com/bitbucket/configure-multiple-ssh-identities-for-gitbash-mac-osx-linux-271943168.html