/
Pack Hosting Panel

Shopware 6 Quickstart

In Bitbucket een Shopware 6 CI/CD pipeline opzetten met behulp van de Hipex Deploy image

Introductie

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

Benodigdheden

Zorg ervoor dat de volgende voorwaarden correct zijn ingesteld voordat je start:

  • Een Hipex hosting omgeving
  • Een bitbucket account
  • Een Pack (Hipex hosting Paneel) developer 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 deploys:

Genereer een key zonder wachtwoord:

ssh-keygen -f id_rsa_myproject_deploy

Configureer de openbare SSH-key van de deploys voor je server

Ga eerst naar Pack > SSH Beheer > SSH-key toevoegen en voeg de zojuist gegenereerde key toe. Geef je key een passende naam: [projectnaam]-deploy. Zorg ervoor dat je geen voorvoegsel van het type key toevoegt, zoals ssh-rsa.

add ssh key in pack

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

configure ssh key in pack

Voeg de key toe aan de server door het vakje aan te vinken. Om te controleren of de key succesvol is toegevoegd, kun je ook de SSH op je server invoeren en zoeken naar de naam van de key 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 jouw server, is het tijd om je SSH key in Bitbucket te configureren.

Ga naar je Bitbucket repository en dan naar: Settings > Pipelines > SSH keys. Selecteer “Use my own keys”, waardoor we de gegenereerde key toe kunnen voegen.

configure deploy key in bitbucket

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

cat id_rsa_myproject_deploy | pbcopy
cat id_rsa_myproject_deploy.pub | pbcopy

paste deploy private public key in bitbucket

Maak het Hipex Deploy-configuratiebestand aan

Nu de deploy key is toegevoegd en geconfigureerd kunnen we door naar de volgende stap: het instellen van de deploy configuratie met behulp van “configuratie as 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 configuratie object bevat die wordt gebruikt 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 te beginnen met een leeg deploy.php file, bestand of om een van de start templates te kiezen om vanuit daar verder te gaan.

Voor deze quickstart gebruiken wij de Shopware 6 starter template configuration. Dit template bevat een standaard configuratie voor Shopware 6 projecten, die volledig naar eigen wens aangepast en uitgebreid kan worden.

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

<?php
namespace HipexDeployConfiguration;

$configuration = new Configuration\Shopware6('git@bitbucket.org:myorg/myproject.git');

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

return $configuration;

Nu dienen we de bestanden en mappen aan te geven die niet veranderen per deploy en dus 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 SW6-starter template dat wij gebruiken bevat al de volgende configuratie voor gedeelde bestanden:

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

Veel voorkomende voorbeelden van gedeelde mappen zijn: media, uploads, var/import en var/log. De SW6-starter template bevat al de volgende configuratie voor gedeelde mappen:

$configuration->setSharedFolders([
    'config/jwt',
    'var/log',
    'public/sitemap',
    'public/media',
    'public/thumbnail'
]);

Nu kunnen we onze build, deploy en after deploy commando’s toevoegen.

Het SW6 starter template bevat de volgende standaard build commando’s:

$this->addBuildCommand(new Composer([
    '--verbose',
    '--no-progress',
    '--no-interaction',
    '--optimize-autoloader',
    '--ignore-platform-reqs',
]));

$this->addBuildCommand(new ShopwareRecovery());
$this->addBuildCommand(new BuildAdministration());
$this->addBuildCommand(new BuildStorefront());

En de volgende deploy commando’s:

$this->addDeployCommand(new AssetInstall());
$this->addDeployCommand(new ThemeCompile());
$this->addDeployCommand(new CacheClear());

Commando’s die toegang nodig hebben op de database moeten worden uitgevoerd als deploy commando’s en worden uitgevoerd op de server, terwijl build commando’s worden uitgevoerd in het CI-systeem, binnen de hipex/deploy Docker CI container.

Maak Shopware 6 configuratie bestanden aan

Voor shopware 6 zal uw eerste build mislukken vanwege een ontbrekende configuratie. Log in op de server en bewerk, afhankelijk van uw projectbestand, .env. Je vindt deze bestanden in ~/domains/<domain>/application/shared/.

Genereer app secret

Shopware heeft een app secret nodig die je eenmaal genereert na de eerste deployment. Je kunt dit gemakkelijk doen door ssh’ing in je server en bin/console system:generate-jwt-secret uit te voeren vanuit de application/current map. Dit JWT-secret wordt opgeslagen in config/jwt, die automatisch gesymlinked is naar shared/config/jwt door hipex deploy, omdat je config/jwt al eerder als een gedeelde map hebt gemarkeerd en dus wordt gedeeld tussen alle deploys.

Bitbucket configuratiebestand opzetten

Nu is het tijd om een CI-configuratiebestand aan te maken. Je kunt wederom vanaf nul beginnen of het Hipex Deploy Bitbucket configuration starter template gebruiken.

Het CI-configuratiebestand moet gebruik maken van de Hipex Deploy image om uw CI/CD-pijplijnen succesvol te laten werken. 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 toevoegen.

Selecteer een versie van de hipex/deploy image die het beste aansluit bij jouw applicatie behoeften. Hier is 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, die een build en deployment stap bevat om de deployment uit te voeren voor de geconfigureerde staging server. Het gebruikt de configuratie uit deploy.php om de stappen uit te voeren.

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

pipelines:
    branches:
        # Deploy to staging
        staging:
            - step:
                  name: Build
                  script:
                      - hipex-deploy build
                  artifacts:
                      - build/**
                  caches:
                      - composer
            - step:
                  name: Deploy
                  deployment: staging
                  script:
                      - hipex-deploy deploy staging

Optioneel: Test jouw Build en Deploy commando’s lokaal

Nu het project configuratie is afgerond, kunnen we de geconfigureerde Build en Deploy optioneel lokaal gaan testen voordat deze gecommit en gepusht worden naar de remote Git repository. Gezien het niet nodig is om 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 het hipex-deploy build commando lokaal uit. We gaan ervan uit dat de private key van het eerdere gemaakte deploy key zich bevindt in ~/.ssh/id_rsa_myproject_deploy, en dat het 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:2.1.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 vlag om het verbosity level te bepalen, zoals -vvv om alle berichten weer te geven. Dit is handig om eventuele fouten te debuggen.

Net als het build commando, kunnen we ook het deploy commando testen. In dit voorbeeld stellen we eerst de environment variabelen 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 hipex-deploy deploy staging -vvv

Committen en pushen van project CI/CD configuraties

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

Nadat dat is gedaan zal Bitbucket de pipeline automatisch starten. De enige geaccepteerde uitkomst is dat een compleet geslaagde pipeline.