Setting up a Shopware Environment with Windows



Developer @ Shopware

At work I use Linux, but at home I prefer Windows due to gaming. In this short Tutorial I would like to share my Windows setup with you.

My recommended setup includes:

  • WSL 2
  • Docker Desktop for Windows
  • Ubuntu / Debian
  • GWSL (X-Server for Windows)
  • PhpStorm
  • Development Docker setup or my own Docker setup. (We will use my own in this tutorial)

At first we need to install WSL 2 and Docker Desktop. Please follow the tutorials below.

Configuration adjustments for GWSL and Docker


  • Click on the GWSL taskbar icon
  • Choose GWSL Distro Tools
  • Enable Auto-Export Display

and configure Firewall like in Documentation

Docker Desktop:

  • Enable integration for additional distros in Docker settings: Docker Desktop settings

Install PhpStorm

We can now start the Ubuntu shell and download PhpStorm for Linux and unpack it in a suitable folder e.g. ~/Apps/PhpStorm. In order to start PhpStorm, run the shell script bin/ in the unpacked folder from the Ubuntu shell (e.g. ~/Apps/PhpStorm/bin/ After that you should see the PhpStorm GUI running within Windows. PhpStorm will stop when you close this Ubuntu shell. You can use GWSL also to create a Windows Shortcut to launch PhpStorm. For more information refer to the GWSL documentation.

To fix the Markdown viewer you will need to install some additional dependencies for the browser in Ubuntu:

sudo apt install libnss3 libnspr4 libxcursor1 libpangocairo-1.0-0 libxss1 libatk1.0-0 libgbm1 libatspi2.0-0 libcups2 libatk-bridge2.0-0

Install SWDC (Shopware Docker Control)

At first we need to clone the repository

# Clone shopware-docker into $HOME/Apps/shopware-docker
git clone ~/Apps/shopware-docker
# Create an shortcut to be able to run `swdc` everywhere
sudo ln -s /home/$USER/Apps/shopware-docker/swdc /usr/local/bin/swdc

That should be all to have an installed swdc. Next we will install one example SW6 setup with the production template:

# Clone the production repository
# sw6 is the project identifier. You can have more than one SW6 setup.
git clone ~/Code/sw6
# Start SWDC
swdc up
# Automatically install Shopware 6. Credentials for administration are admin / shopware
swdc build sw6

After this step we have Shopware 6 installed at You may need to create a hosts entry to reach the domain ( Adminer is running at db.localhost

The swdc command-line contains some helpers like:

# Install NPM dependencies for Administration
swdc admin-init sw6
# Start admin watcher
swdc admin-watch sw6
# Running at localhost:8181
# Install NPM dependencies for Storefront
swdc storefront-init sw6
# Start storefront watcher
swdc storefront-watch sw6
# Running at localhost:9998

Limiting WSL 2 Resources

By default WSL uses up to 80% of your Resources. You can limit them by creating a .wslconfig file in your Home directory in Windows.

Example configuration:



We have a running WSL 2 with Docker, X-Server and SWDC. We can open the shop in the browser and use the admin and storefront watcher. To see all capabilities of swdc see Repository.

If you have Questions feel free to write me at Twitter or Shopware Community Slack.

Why I don't like Custom fields?



Developer @ Shopware

Normally every project needs custom values saved on products or another entities. Shopware does offer by default Custom fields. It looks nice, but it can produce very fast issues.

Before we start: This is my opinion

Let's start with a simple Pro Contra list.


  • Can be easily created in the Administration / Code.
  • Can define field types, labels etc and Shopware does the rendering in Administration for me
  • Loaded by default on the entities
  • Custom Fields are schema less. You can save anything in it


  • Custom Fields are schema less. You can save anything in it
  • They are saved as JSON
    • Hard to modify using SQL
    • Cannot have associations
    • Slow on SQL Filtering, Aggregation
  • Loaded by default on the entities
  • Support between MySQL and MariaDB differs and Performance
  • Cannot have Flags. All fields are public using Sales-Channel / Store-API
  • Cause it does not have a Schema they will be indexed as dynamic in Elasticsearch. This brings lot of other problems
  • You don't have a control is it translatable or not
  • Fields values cannot be easy deleted on all entities. You need to modify each entry.

The most problems are introduced cause of the usage of an JSON field. In SQL the accessed fields needs to be extracted. This takes some time of course. On a bigger shop using many products this could leak to performance issues in the listing when it's used inside a product filter.

But when search / filtering / aggregation is slow. Can I not just use Elasticsearch?

You can. But...

We learned before they don't have a Schema. So we have to index the custom Fields with dynamic enabled. With this option Elasticsearch tries to find the best suitable data type for your field. When we have multiple data types in the same field across entries the indexing will fail. Cause Elasticsearch decided to use first best suitable data type and rejects values does not match it.

But when is it okay to use them?

  • When you don't need to Filter / Aggregate / Search on it
  • When it's okay to be exposed in the Public API (Sales Channel / Store API)

But Entity Extensions are so annoying to create

The generation of the entities can be annoying. But I am working since some time on a generator. Give it a try.

How to deploy plugin updates automatically to the Shopware Store



Developer @ Shopware

This blog post describes a small example how to automaticly deploy plugin updates to the Store. I will use the FroshPerformance plugin as example.


You will need

  • a Plugin which based on the 5.2 Pluginsystem or Shopware 6 Plugin
  • a Continuous Integration (i will use Travis as example)
  • Credentials for the Shopware Account
  • FroshPluginUploader

Prepare the Plugin itself

You will need a plugin.xml with filled title, version, description, compability and changelog for the languages en and de. All these informations will be picked up automaticly and updated in the Account.


You can define also the plugin description, manual and images in Resources/store. Currently supported files are

  • [shortLanguage (de, en)].html - for the Description
  • [shortLanguage (de, en)]_manual.html - for the Install Manual
  • images/*.(png|jpg|jpeg) will be used for Images. First image will be used as preview image.

Setting up the ci

As first you should define following environment variables as secret in your favourite ci

  • ACCOUNT_USER - Username of Shopware Account
  • ACCOUNT_PASSWORD - Password of Shopware Account

As next we setup a job to build the store ready plugin zip. The Uploader has an command to generate an zip file for your

php frosh-plugin-uploader.phar ext:zip:dir [Path to Git Folder]

After building an zip, we validate the zip file using the uploader with

php frosh-plugin-uploader.phar ext:validate

This will check all requirements from the Uploader and also from the Plugin Guidelines. which are also describe in Prepare the Plugin itself

After the validating you can sync the optional folder Resources/store to the account with

php frosh-plugin-uploader.phar ext:update FroshPerformance

As last step you can upload the zip with

php frosh-plugin-uploader.phar ext:upload

The command will also wait for the automatic code-review and will fail, if its not green. Reuploading same version will replace existing binary.