Déployez votre PWA Studio sur Magento Cloud !

DND Magento PWA Studio x Magento Cloud — *par Florian, Magento Technical Officer à l’Agence Dn’D*

Les premières étapes sont disponibles dans la documentation officielle de PWA Studio, vous pouvez suivre l’ensemble de la démarche jusqu’à la phase “finding the correct UPWARD path value”. En revanche, si vous continuez de suivre cette dernière, vous devrez build votre application sur votre machine locale et pousser vos sources sur votre repository, ce qui va à l’encontre du couplage unitaire spécifié dans la documentation officielle de PWA Studio. En revanche, il ne sera pas possible de découpler le déploiement, car nous sommes limités par le fait que nous n’avons qu’un environnement fourni par Magento Cloud.

Créer les variables Magento Cloud

Il existe deux manières de créer des variables avec Magento Cloud :

Depuis l’interface en cliquant sur le lien des paramètres
Depuis votre ligne de commande avec le Magento Cloud cli

Il y a deux types de variables, celles au niveau projet (qui nous seront utiles dans notre cas) et les variables d’environnement. Elles se distinguent par le fait que les variables projet peuvent être utilisées pendant le hook build (et c’est donc pour cela qu’elles nous intéressent).

Créez deux variables projet en pensant à bien sélectionner le fait que vous souhaitez qu’elles soient visibles pendant la phase de build :

- PWA_BRANCH => permet de définir la branche à pull sur votre repository contenant les sources de PWA Studio
- MAGENTO_BACKEND_URL => l’url de votre Magento

Donnez une valeur par défaut à ces variables puis créez les sur chaque environnement avec la valeur appropriée (e.g. staging pour votre PWA_BRANCH sur votre environnement de staging). Vous pouvez bien entendu créer autant de variables que vous voulez. Si vous affichez les variables pour un environnement, vous devez obtenir ceci :

Variables on the project MyMcProject (mcdnd2021), environment staging:
+-----------------------------------------+-------------+-----------------------------------------------+---------+
| Name                                    | Level       | Value                                         | Enabled |
+-----------------------------------------+-------------+-----------------------------------------------+---------+
### VALUES FROM PROJECT LEVEL ###
| PWA_BRANCH                              | project     | integration                                   |         |
| MAGENTO_BACKEND_URL                     | project     | https://mcstaging.my-beautiful-website.com/   |         |
### VALUES FROM ENVIRONMENT LEVEL ###
| MAGENTO_BACKEND_URL                     | environment | https://mcstaging.my-beautiful-website.com/   | true    |
| PWA_BRANCH                              | environment | staging                                       | true    |
+-----------------------------------------+-------------+-----------------------------------------------+---------+

Build PWA Studio

Magento Cloud met à disposition trois hooks :

- Build, qui est en l’occurrence celui que nous utiliserons car il nous permettra de cloner les sources de notre PWA Studio. Pendant cette phase, aucun des services tel que MySQL n’est accessible.
- Deploy, qui est lancé dès lors que tous les containers sont up mais pas encore sollicités. Durant cette phase, Magento est down lors de l’exécution de la commande de setup upgrade.
- Post-deploy, qui permet de lancer diverses opérations sur votre application tel que le cache warming.

Mise à jour du .magento.app.yml

Les hooks peuvent être modifiés dans le fichier .magento.app.yml qui se trouve à la racine des sources de votre Magento. Dans ce fichier, vous trouverez un nœud se nommant hooks.

Nous avons fait le choix de mettre toutes nos instructions dans un fichier bash car cela est plus lisible. Voici donc le contenu de notre noeud hooks :

hooks:
# We run build hooks before your application has been packaged.
# Set permission & execute bash file
build: |
set -e
chmod u+x .hooks/bin/build.sh && ./.hooks/bin/build.sh
# We run deploy hook after your application has been deployed and started.
deploy: |
php ./vendor/bin/ece-tools run scenario/deploy.xml
# 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 run scenario/post-deploy.xml

L’objectif de ce script bash est de :

Installer NVM
Installer yarn and webpack
Exécuter le code de base de Magento
Cloner PWA Studio
Build PWA Studio
Nettoyer le dossier de PWA Studio afin de conserver uniquement le dossier dist

Installation de NVM

Pour ce faire, il faut créer un fichier .environment à la racine du code source de Magento avec le contenu suivant :

# This is necessary for nvm to work.
unset NPM_CONFIG_PREFIX
# Disable npm update notifier; being a read only system it will probably annoy you.
export NO_UPDATE_NOTIFIER=1
# This loads nvm for general usage.
export NVM_DIR="$MAGENTO_CLOUD_APP_DIR/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

Ensuite, créez le fichier qui est utilisé dans notre .magento.app.yml via .hooks/bin/build.sh (vous pouvez bien évidemment lui donner le nom que vous souhaitez en pensant bien à reporter le bon nom dans la configuration yaml). Ajoutez-y les lignes suivantes :

#!/bin/dash

### INSTALL NVM TO UPGRADE NODE JS ###
unset NPM_CONFIG_PREFIX
export NVM_DIR="$MAGENTO_CLOUD_APP_DIR/.nvm"
# install.sh will automatically install NodeJS based on the presence of $NODE_VERSION
curl -f -o- https://raw.githubusercontent.com/nvm-sh/nvm/$NVM_VERSION/install.sh | bash
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
### END INSTALL NVM TO UPGRADE NODE JS ###

Retournez dans le fichier .magento.app.yml afin d’y renseigner deux variables NODE et NVM_VERSION dans le noeud variable :

# Environment variables
variables:
env:
NVM_VERSION: v0.36.0
NODE_VERSION: v14.13.1
NODE_ENV: "production"
# Others variables

Installation de Yarn

Ce gestionnaire de paquet vous permettra de build votre application. Pour les installer, ajoutez les lignes suivantes dans votre fichier .hooks/bin/build.sh :

### INSTALL YARN & WEBPACK ###
npm install --global yarn
### END INSTALL YARN & WEBPACK ###

Exécution du code natif Magento

Nous devons conserver la logique Magento qui lance des process comme l’installation des paquets via composer. De ce fait, ajoutez les lignes suivantes dans le .hooks/bin/build.sh :

### MAGENTO OOTB LOGIC ###
php ./vendor/bin/ece-tools run scenario/build/generate.xml
php ./vendor/bin/ece-tools run scenario/build/transfer.xml
### END MAGENTO OOTB LOGIC ###

Cloner, build et nettoyer les sources de PWA Studio

### INSTALL PWA STUDIO ###
if [ -z "${PWA_BRANCH}" ];
then
PWA_BRANCH='production'
echo "PWA_BRANCH Not exist !"
fi
git clone --single-branch --branch $PWA_BRANCH https://your-repo-url.com/path-to-your-repo $MAGENTO_CLOUD_APP_DIR/pwa
cd pwa && yarn cache clean && yarn install --production=false --frozen-lockfile && echo yes|yarn build

CHECK IF DIST WAS CREATED ###
if [ -d $MAGENTO_CLOUD_APP_DIR/pwa/dist ]
then
# Clean sources and preserve only dist directory
find $MAGENTO_CLOUD_APP_DIR/pwa -mindepth 1 ! -regex "^$MAGENTO_CLOUD_APP_DIR/pwa/dist\(/.*\)?" -delete
# Move statics files to make them accessible in magento pub directory
cp -R $MAGENTO_CLOUD_APP_DIR/pwa/dist/*.png $MAGENTO_CLOUD_APP_DIR/pub
else
echo "A problem occurred while building PWA Studio"
exit 1
fi
### ENDCLONE & INSTALL PWA STUDIO ###

Explications :

Nous clonons les sources de la branche que nous avons renseigné pour notre PWA. Nous avons créé les branches équivalentes à celles de Magento en fonction de notre architecture (pro ou starter),
Nous entrons dans le dossier des sources que nous avons clonées et faisons un build de l’application,
Nous supprimons toutes les sources de PWA Studio afin de conserver uniquement le dossier dist,
Nous ajoutons une sécurité supplémentaire en contrôlant la présence du dossier dist afin de stopper le déploiement si ce dernier ne s’est pas correctement créé.

Contenu entier & déploiement

Voici tout le contenu de l’ensemble des fichiers requis. En considérant que nous sommes à la racine des sources de votre Magento : .magento.app.yml

# Environment variables
variables:
env:
NVM_VERSION: v0.36.0
NODE_VERSION: v14.13.1
# Using gitlab ? Feel free to put your token here :) (optional)
# You can also handle this with variables
GITLAB_TOKEN: A_BEAUTIFUL_TOKEN
GITLAB_USERNAME: AN_AMAZING_USER
# end (optional)
# You can handle this value with variables
CHECKOUT_BRAINTREE_TOKEN: sandbox_token
ENABLE_EXPRESS_SERVER_COMPRESSION: false
IMAGE_OPTIMIZING_ORIGIN: backend
MAGENTO_BACKEND_EDITION: EE
NODE_ENV: "production"
# You can handle this value with variables
CONFIG__DEFAULT__WEB__UPWARD__PATH: "/path/to/magento/root/pwa/dist/upward.yml"
.hooks/bin/build.sh

#!/bin/dash

### INSTALL NVM TO UPGRADE NODE JS ###
unset NPM_CONFIG_PREFIX
export NVM_DIR="$MAGENTO_CLOUD_APP_DIR/.nvm"
# install.sh will automatically install NodeJS based on the presence of $NODE_VERSION
curl -f -o- https://raw.githubusercontent.com/nvm-sh/nvm/$NVM_VERSION/install.sh | bash
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
npm install --global yarn
### END INSTALL NVM TO UPGRADE NODE JS ###

### run the build tasks using Composer 2.x. (Magento >=2.4.2) ###
composer --no-ansi --no-interaction install --no-progress --prefer-dist --optimize-autoloader
### end using composer 2.x. ###

### MAGENTO OOTB LOGIC ###
php ./vendor/bin/ece-tools run scenario/build/generate.xml
php ./vendor/bin/ece-tools run scenario/build/transfer.xml
### END MAGENTO OOTB LOGIC ###

### INSTALL PWA STUDIO ###
if [ -z "${PWA_BRANCH}" ];
then
PWA_BRANCH='integration'
echo "PWA_BRANCH Not exist !"
fi
git clone --single-branch --branch $PWA_BRANCH https://your-repo-url.com/path-to-your-repo $MAGENTO_CLOUD_APP_DIR/pwa
cd pwa && yarn cache clean && yarn install --production=false --frozen-lockfile && echo yes|yarn build

### CHECK IF DIST WAS CREATED ###
if [ -d $MAGENTO_CLOUD_APP_DIR/pwa/dist ]
then
# Clean sources and preserve only dist directory
find $MAGENTO_CLOUD_APP_DIR/pwa -mindepth 1 ! -regex "^$MAGENTO_CLOUD_APP_DIR/pwa/dist\(/.*\)?" -delete
# Move statics files to make them accessible in magento pub directory
cp -R $MAGENTO_CLOUD_APP_DIR/pwa/dist/*.png $MAGENTO_CLOUD_APP_DIR/pub
else
echo "A problem occurred while building PWA Studio"
exit 1
fi
### ENDCLONE & INSTALL PWA STUDIO ###

.environment

# This is necessary for nvm to work.
unset NPM_CONFIG_PREFIX
# Disable npm update notifier; being a read only system it will probably annoy you.
export NO_UPDATE_NOTIFIER=1
# This loads nvm for general usage.
export NVM_DIR="$MAGENTO_CLOUD_APP_DIR/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

DEPLOY ! 🚀

DND - Magento Cloud x PWA Studio - release

Conclusion

La CI de Magento Cloud nous permet de faire beaucoup de choses grâce aux hooks mis à disposition, ce qui la rend très puissante. Nous aimerions cependant avoir un peu moins de restrictions afin d’être libre d’installer certains paquets (via apt-get ou autre, non disponible quelle que soit la phase). Nous pouvons constater plusieurs points sur le fait d’héberger notre PWA sur Magento Cloud :

- Upward connector réduit les performances car c’est PHP qui est utilisé pour rendre et récupérer les données, mais cela permet de facilement implémenter du SSR via prerender.io
- Il est possible de cacher toutes les query graphql (et non pas les mutations) avec Fastly
- La documentation mise à disposition par Magento Cloud est parfois incomplète mais celle fournie par Platform.sh permet de pallier cette problématique.

Vous êtes intéressé par PWA Studio et/ou par Magento ?

En tant qu’agence certifiée Magento, Dn’D vous accompagne dans le conseil, la conception et la maintenance de votre plateforme E-Commerce. N’hésitez pas à nous contacter via le formulaire ci-dessous !