Diese Seite ist auch auf Deutsch verfügbar. Zur deutschen Seite wechseln

Continuous Deployment: Automizing Shopware 6 deployments

Overview

Automized deployments shouldn't be a pain and have several advantages like lower failure rates, reproducible builds, and they increase the overall productivity because actual testing can get more attention.

This article explains the fundamental steps it takes, to deploy Shopware 6 to a certain infrastructure, focussing on continuous deployment using GitLab CI and Deployer. Deployer is a deployment tool written in PHP.

This "certain infrastructure" will be called "target server" in the following.

Video

Prerequisites

Please make sure, that you already have a working Shopware 6 instance running, and your repository is based on the Shopware production template, because this article relies on some scripts to exist in your repository.

Preparations before the first deployment

Deployer has a default directory structure, in which it organizes releases, shared files across releases (e.g. certificates, configuration or media files) and the symlink to the current release.

The structure looks like this:

 

If you haven't used such a structure yet, it's recommended to move the current document root contents to a different location, because you will have to copy some existing files into the shared folder, after your first deployment with Deployer.

For more information, please have a look into Migrating existing instance to Deployer structure.

Webserver configuration

Please make sure, to set the document root of the domain to /var/www/shopware/current/public, assuming /var/www/shopware is the path you're uploading Shopware to, but this can of course differ. The more important part of this path is current, which is the symlink to the currently active release.

Because current is a symlink, please also make sure, that your webserver is configured to resolve/follow symlinks correctly.

GitLab Runner requirements

GitLab pipelines are processed by so called runners. Once a pipeline job is created, GitLab notifies a registered runner, and the job will then be processed by that runner.

The GitLab Runner must have the following packages installed:

This example uses the docker image shopware/development:latest. This image meets all requirements.

Deployment steps

1. Cloning the repository

The very first needed step in the pipeline is cloning the repository into the runner's workspace.

GitLab does that automatically for every started job.

2. Installing dependencies

All the dependencies of your project must be installed. Shopware 6 uses Composer for managing PHP dependencies and Node Package Manager (npm) for frontend related dependencies.

Initially only the Composer dependencies need to be installed by running the following commands:

  • composer install --no-interaction --optimize-autoloader --no-suggest
  • composer install -d vendor/shopware/recovery --no-interaction --optimize-autoloader --no-suggest

This step is defined in the Install dependencies job in the .gitlab-ci.yml:

 

3. Building assets

From this step on, all other steps are handled by Deployer, defined in the deploy.php.

In order to compile and copy assets, the Shopware production template provides a script, which is located under bin/build-js.sh. This script installs the NPM dependencies and builds assets that are needed for the administration, storefront and plugins.

It's important to know, that you need a database connection to execute this script, because before actually compiling the assets, the console command bin/console bundle:dump is executed. This command creates the file var/plugins.json, which contains information about the asset paths of all activated plugins.

If you don't want to build the assets on the target server (for performance reasons), you could execute the bundle:command on the target server and download the generated plugins.json into your runner's workspace, before executing bin/build-js.sh.

This step is defined to be executed on the target server in the sw:build job in the deploy.php and will be executed before transferring the files to the target server:

 

4. Transferring the workspace

For transferring the files to the target server, please configure at least one host in the deploy.php:

 

This step is defined in the deploy:update_code job in the deploy.php:

 

5. Applying migrations

The migrations need to be applied on the target server.

If you are deploying to a cluster with multiple web servers, please make sure to run the migrations only on one of the servers.

This step is defined in the sw:database:migrate job in the deploy.php, which is part of the sw:deploy task group:

 

6. Warming up caches

If you have the HTTP cache enabled in your .env file, it's recommended to warm up the caches, so that the first user, who visits the recently deployed version, doesn't have to wait, until the page is rendered for the first time.

This step is defined in the sw:cache:warmup job in the deploy.php:

 

7. Creating the install.lock file

Before putting the new version live, please make sure to create an empty file install.lock in the root of the build workspace. Otherwise, Shopware will redirect every request to the Shopware installer, because it assumes, that Shopware isn't installed yet.

This task is defined in the sw:touch_install_lock job in the deploy.php, which is part of the sw:deploy task group:

 

8. Switching the document root

After all steps are done, Deployer will switch the symlinks destination to the new release.

This task is defined in the deploy:symlink default job in the deploy.php.

Deployer output

This is the output of dep deploy production:

Migrating existing instance to Deployer structure

After the very first deployment with Deployer, you have to copy some files and directories from your existing Shopware instance into the directory structure, that was created by Deployer.

Let's agree on the following two paths for the examples:

  1. You have copied your existing Shopware instance to /var/www/shopware_backup.
  2. You have set the deploy_path in the deploy.php to /var/www/shopware.

Now have a look at the shared_files and shared_dirs configuration in the deploy.php. Simply copy all the paths into /var/www/shopware/shared. For the configuration of the deploy.php the commands would be the following:

Sources

Please have a closer look at the following files. All steps are provided with helpful comments.

.gitlab-ci.yml

deploy.php

Newsletter

Never miss out - get all the latest news sent straight to your inbox.