/
Pack Hosting Panel

Magento 2 quickstart

Op Bitbucket een Magento 2 CI/CD pipeline opzetten met behulp van de Hipex Deploy image

Introductie

Dit artikel helpt je bij het opzetten van een continues integration en delivery/deployment pipeline voor Magento 2 met behulp van Bitbucket. Als voorbeeld richten we ons hierbij enkel op een staging omgeving.

Benodigdheden

Om te kunnen starten zijn er enkele benodigdheden die van tevoren geregeld moeten zijn:

  • Een Hipex hosting omgeving
  • Een Bitbucket account
  • Een Pack (Hipex hosting Paneel) account. Dit geeft je de rechten om SSH Key beheer te beheren.

Maak een Deployment SSH key aan

Ter voorbeeld genereren we een SSH key (publiek/prive) die we enkel gebruiken voor dit artikel:

Genereer een SSH key zonder wachtwoord:

ssh-keygen -f ~/.ssh/id_rsa_myproject_deploy

Configureer de public key voor je hosting omgeving

Ga eerst naar Pack > SSH-beheer > SSH Key toevoegen en voeg de zojuist gegenereerde public key toe.

Kopieer de volledige public key:

cat ~/.ssh/id_rsa_myproject_deploy.pub | pbcopy

Geef de key een passende naam: [projectnaam]-deploy, en kies het type key. Let op: zorg ervoor dat je geen voorvoegsel van het type key toevoegt zoals ssh-rsa, en strip ook het laatste deel van de key - meestal "user@machine" - weg.

ssh key toevoegen in pack

Ga naar Pack > SSH beheer en filter op de servernaam en de SSH key.

configureer de ssh key in pack

Voeg de SSH key toe aan de server door het vakje aan te vinken. Om te controleren of de key succesvol is toegevoegd, kun je ook SSH op je server invoeren en zoeken naar de naam van de sleutel in het geautoriseerde sleutelbestand:

cat ~/.ssh/authorized_keys | grep myproject-deploy

Configureer je Deployment SSH key in Bitbucket

Nu je je deployment key hebt gegenereerd en hebt toegevoegd aan de correcte server kunnen we je SSH key in Bitbucket configureren.

Ga naar je Bitbucket repository Settings > Pipelines > SSH keys. Selecteer "Use my own keys", waar we de keys toe kunnen voegen die we eerder al hebben gegenereerd.

configureer deploy key in bitbucket

Kopieer zowel de gegenereerde private als public key en plak deze precies zoals ze zijn (het wijzigen van de inhoud kan resulteren in "ongeldige sleutel formaat" problemen), en druk op Save key pair.

cat id_rsa_myproject_deploy | pbcopy
cat id_rsa_myproject_deploy.pub | pbcopy

plak de deploy prive public key in bitbucket

Verifieer composer packages uit andere repositories

Als het project composer package dependencies heeft naar andere (interne) repositories, voeg dan bij die betreffende projecten de deploy (public) key toe als access key om authenticatie issues te voorkomen.

Dump Magento configuratie naar configuratiebestanden

Voor een succesvolle pipeline is het van belang dat alle configuraties vanuit de Magento Admin wordt geëxporteerd naar bestanden, omdat we binnen een pipeline geen database afhankelijkheid kunnen en willen hebben.

Gebruik het volgende commando om de configuratie te dumpen naar bestanden:

bin/magento app:config:dump

Strip de configuratiebestanden, zodat app/etc/config.php alleen de essentiële configuratie bevat. Voeg app/etc/config.php toe aan je Git repoistory, maar app/etc/env.php niet omdat deze file enkel op de server aanwezig moet zijn.

Lees meer over het dumpen van Magento configuratie in de devdocs van Magento.

Maak het Hipex Deploy-configuratiebestand aan

Nu de deploy key is toegevoegd kunnen we door naar de volgende stap. Nu gaan we de deploy configuratie instellen met behulp van "configuratie als code". We hebben nu alleen nog een deploy.php bestand nodig in de root van het project.

Het Hipex Deploy configuratiebestand (zie Github) is een php-bestand dat een configuratieobject bevat die gebruikt wordt door de Hipex Deploy Docker image. Deze configureren we later in de Bitbucket CI-configuratie om vervolgens geconfigureerde CI/CD stappen uit te kunnen voeren.

Optioneel: voeg de Hipex Deploy Configuration composer package als development package toe aan het project om code completion voor de Hipex Deploy configuration te krijgen:

composer require hipex/deploy-configuration --dev

Je hebt de keuze om volledig nieuw te beginnen met een leeg deploy.php bestand, of je kiest voor een van de start templates om vanuit daar verder te gaan.

Voor een snelle start maken we nu gebruik van de Magento 2 application template. Dit is een starter template met een standaard configuratie voor Magento 2 projecten, die volledig naar eigen wensen aangepast kan worden.

De configuratie voor een staging omgeving mag zo kort zijn als het voorbeeld hieronder:

<?php
namespace HipexDeployConfiguration;

$configuration = new ApplicationTemplate\Magento2(
    // Your GIT repository url
    'git@bitbucket.org:myorg/myproject.git',
    // Frontend locales
    ['nl_NL'],
    // Backend locales
    ['nl_NL']
);

$configuration->setPhpVersion('php73');
$stagingStage = $configuration->addStage('staging', 'staging.myproject.com', 'myprojectsshuser');
$stagingStage->addServer('mystagingserver.hipex.io');

return $configuration;

Nu dienen we de bestanden en mappen aan te geven welke per deploy niet veranderen en bij elke deploy hetzelfde blijven.

Veel voorkomende voorbeelden van gedeelde bestanden zijn configuratiebestanden zoals .env, env.php en config.php. Meestal staan deze bestanden niet onder controle van de broncode en kunnen ze worden gegenereerd / samengesteld door de applicatie of het CI/CD-systeem.

Het M2-template dat we gebruiken bevat al de volgende configuratie voor gedeelde bestanden:

$configuration->setSharedFiles([
    'app/etc/env.php',
    'pub/errors/local.xml'
]);

Gebruik $configuration->addSharedFile(string $file) om hier bestanden aan toe te voegen.

Veel voorkomende voorbeelden van gedeelde mappen zijn: media, uploads, var/import en var/log. Het Magento 2 template bevat al de volgende configuratie voor gedeelde mappen:

$configuration->setSharedFolders([
    'var/log',
    'var/session',
    'var/report',
    'pub/media'
]);

Gebruik $configuration->addSharedFolder(string $folder) om hier mappen aan toe te voegen.

Nu kunnen we onze build, deploy en after deploy commando's toe gaan voegen.

Het Magento 2 template bevat al de volgende standaard build commando's:

$configuration->addBuildCommand(new Command\Build\Composer());
$configuration->addBuildCommand(new Command\Build\Magento2\SetupDiCompile());
$configuration->addBuildCommand(new Command\Build\Magento2\SetupStaticContentDeploy($localesFrontend, 'frontend'));
$configuration->addBuildCommand(new Command\Build\Magento2\SetupStaticContentDeploy($localesBackend, 'adminhtml'));

En ook de volgende deploy commando's:

$configuration->addDeployCommand(new Command\Deploy\Magento2\MaintenanceMode());
$configuration->addDeployCommand(new Command\Deploy\Magento2\SetupUpgrade());
$configuration->addDeployCommand(new Command\Deploy\Magento2\CacheFlush());

Bitbucket configuratiebestand opzetten

Nu kunnen we je CI-configuratiebestand aan maken. Je kunt wederom vanaf nul beginnen of de Hipex Deploy Bitbucket configuratietemplate gebruiken.

Het CI-configuratiebestand moet gebruik maken van de Hipex Deploy image om uw CI/CD-pipelines succesvol te runnen. Wij bieden meerdere versies van de Hipex Deploy image onder andere voor elke PHP + NodeJS versie combinatie. Zie Docker Hub voor alle beschikbare versies. Naarmate er nieuwe PHP / Node versies uitkomen zullen we meerdere nieuwe versies toe gaan voegen.

Selecteer een versie van de hipex/deployimage die het best aansluit bij je applicatiebehoeften. Hier hebben we een voorbeeld van een bitbucket-pipelines.yml bestand dat gebruik maakt van de combinatie PHP 7.3 + Node 13 die is geconfigureerd met een configuratie voor de staging omgeving, met daarin een build stap en een deployment stap om de deployment uit te voeren voor de geconfigureerde staging server. Hier wordt de configuratie uit deploy.php gebruikt om de stappen uit te voeren.

image: hipex/deploy:v2.5.0-php7.3-node13

pipelines:
    branches:
        # Deploy to staging
        staging:
            - step:
                  name: Build
                  image: hipex/deploy:v2.5.0-php7.3-node13
                  script:
                      - hipex-deploy build
                  artifacts:
                      - build/**
                  caches:
                      - composer
            - step:
                  name: Deploy
                  deployment: staging
                  script:
                      - hipex-deploy deploy staging

Optioneel: Test je Build en Deploy commando's lokaal

Nu de projectconfiguratie is afgerond, kunnen we de geconfigureerde Build and Deploy stappen optioneel lokaal gaan testen alvorens deze te committen en naar de remote Git repo gepusht kunnen worden. Gezien het niet nodig is te wachten op het resultaat van de Bitbucket-pipeline zal hier aanzienlijk tijd worden bespaard. Je hebt een Docker-client nodig om je build en deployment lokaal te kunnen testen.

Voer nu het hipex-deploy build commando lokaal uit. We gaan er hierbij van uit dat de private key van de eerder gemaakte deploy key zich bevindt op ~/.ssh/id_rsa_myproject_deploy, en dat deze toegang heeft tot de hoofd Git-repository, private packages en de SSH-gebruiker. Let hierbij op dat de meegeleverde SSH_PRIVATE_KEY omgevingsvariabele gecodeerd moet worden op basis64.

docker run -it --env SSH_PRIVATE_KEY="$(cat ~/.ssh/id_rsa_myproject_deploy | base64)" -v `pwd`:/build hipex/deploy:v2.5.0-php7.3-node13 hipex-deploy build -vvv

Omdat alle hipex-deploy-commando's zijn geïmplementeerd als Symfony Console-commando's, kunnen we het build-commando toevoegen met een flag om het verbosity level te bepalen, zoals vvv om alle berichten weer te geven. Dit is handig om eventuele fouten te kunnen debuggen.

Net als het build commando, kunnen we nu ook het deploy commando testen. In dit voorbeeld stellen we eerst de environment variables in voordat we ze in het commando gebruiken.

export SSH_PRIVATE_KEY=***
export DEPLOY_COMPOSER_AUTH=***

docker run -it -e SSH_PRIVATE_KEY -e DEPLOY_COMPOSER_AUTH -v `pwd`:/build hipex/deploy:v2.5.0-php7.3-node13 hipex-deploy deploy staging -vvv

Committen en pushen van project CI/CD configuraties

Nu alle projectconfiguratie is afgerond en we hebben geverifieerd dat zowel de build als deploy commando's succesvol lokaal draaien, is het tijd om zowel de Hipex Deploy configuratie (deploy.php) als de CI-configuratie (bitbucket-pipelines.yml) te committen en te pushen naar de remote Git repository.

Nadat dit is gedaan zal Bitbucket de pipeline automatisch starten.

Configureer app/etc/env.php op de server

Voor een succesvolle pipeline run is het van belang dat app/etc/env.php op de server aanwezig is correct is geconfigureerd. Als dit ontbreekt dan zal de build mislukken. Log in op de server en bewerk app/etc/env.php of app/etc/local.xml, afhankelijk van je projectbestand. Je vindt deze bestanden in de folder ~/domains/<domain>/application/shared/.

Run de pipeline hierna nogmaals. Je bent klaar als zowel de Build als Deploy stap een groen vinkje krijgen.

Bitbucket pipeline succeeded