Welcome to the dockware documentation!

This is your knowledge base from installing docker, starting your first shopware on to developing plugins or even Shopware with dockware #contribution.

If you have anything that might be missing, don't hesitate to contact us.
Thank You!


In this section you will install Docker on your system,
and prepare everything to run as smooth and fast as possible.

Docker Setup

Start by downloading the latest version of Docker Desktop for MAC and install it on your system.

Download Docker for MAC

You can find more about Docker for MAC here.
Start by downloading the latest version of Docker and install it on your system.

Docker for CentOS
Docker for Debian
Docker for Fedora
Docker for Ubuntu

You can find more about Docker here.
Start by downloading the latest version of Docker Desktop for Windows and install it on your system.

Download Docker for Windows

You can find more about Docker for Windows here.

Performance Tweaks

To improve the performance of your overall docker system, you might want to tweak a few things.
We do this by opening our docker preferences on our host machine.

Please note, these are no must-haves, but still help give you a better overall experience of your docker system.

Linux based users need to configure it using the bash, if even needed for their systems.


We start by configuring the amount of CPUs and Memory Docker will get from your host system.
This obviously depends on your system and its resources.

When changing these numbers, please keep in mind that the more resources you give Docker, the less your host system has.

We had the best experience by using half of the CPUs (3-4) and about 6-8 GBM RAM for Docker.

docker ressources settings for mac

Resource File Sharing

This section tells Docker what folders are ready to be used with bind-mounting.
As you might see after installing Docker, the whole system is available.

That means, when docker starts, it will prepare the whole system to be used for bind-mounting,
which is of course an overload that can be reduced.

We recommend only adding your projects root folder and for some special use cases your ~/.ssh folder.

docker file sharing settings for mac

Storage Driver

Docker works with different storage drivers.
The fastest one at the moment is "overlay-2".

To enable this as global storage driver, just add the following entry to your Docker Engine settings.
        "storage-driver" : "overlay2"

docker overlay2 storage driver

First Run

It's finally time to start your first Shopware 6 with dockware.
For this we use the dockware #play version, which brings everything you need to simply start and explore Shopware 6.

Run Shopware 6 with latest version
docker run --rm -p 80:80 dockware/play:latest
The dockware image will be downloaded the first time you run this command.
Upcoming starts will not download it again, and will be much faster.

As soon as dockware is ready, you will see an output that shows you all available URLs.

That's it - give it a try!

SUCCESS - Shopware is now ready!
SHOP URL: http://localhost
ADMIN URL: http://localhost/admin
ADMINER URL: http://localhost/adminer.php
MAILCATCHER URL: http://localhost/mailcatcher
Attention! If you use a https connection and chrome as browser, it might block your connection to https://localhost.
This can be easily changed by following these steps from our FAQ.

There are also other ways to start a Shopware 6 shop.

Run Shopware 6 with specific version
docker run --rm -p 80:80 dockware/play:6.1.3

Run Shopware 6 with another PHP version
docker run --rm -p 80:80 --env PHP_VERSION=7.2 dockware/play:latest

Tutorial Video available
Watch our short video about starting and exploring Shopware 6 with dockware.

dockware play explore shopware 6

Update Dockware

We work hard on maintaining dockware.
So there might be updates from time to time to existing images.

These updates will not get a new tag version, but stick with the tagged Shopware version.
Run this command to test for new updates and automatically download it.
docker pull dockware/play:latest

Run this command to update and download all versions of this image.
Please note that this consumes more disk space.
docker pull dockware/play -a

Please keep in mind, if you use any type of volume for your Shopware source code - the source code will not be updated!
Only the container is being updated locally on your host.

Advanced Run

Let's talk about an advanced setup for running Shopware 6.

The easy first run is perfect to immediately start Shopware, but does not persist any data or allows you to reuse that Shopware 6 instance again after restarting your host.

Use this content and place it in a file called docker-compose.yml.

It will use internal Docker volumes to persist your database and everything that is stored within your DocRoot, such as "media" files, "download" files and more.
    version: "3"

      image: dockware/play:latest
      container_name: shopware
         - "80:80"
         - web
    external: false
Now start dockware with this command from the terminal with the directory that contains your yaml file as working directory:
docker-compose up -d

The option "-d" means "detached" and makes sure your container isn't quit when you close your terminal.
If you still want to see the output of dockware, use this command.
docker logs -f shopware

Mor examples for using docker-compose can be found here

Symfony or Shopware 5

The main focus of dockware is to focus on existing and upcoming Shopware 6 versions.

Still we heard the requests from the community and are now also providing limited support for Shopware 5 versions.
Both, #play and #dev images come with additional versions of previous Shopware 5 editions.

Run Shopware 5 with dockware
docker run --rm -p 80:80 dockware/play:5.6.7
Please keep in mind that there is only limited support for Shopware 5.
If you find any problems, just let us know and we try to find a solution.

FLEX for Symfony

The latest image of dockware is "dockware/flex:latest".
That one gives you a blank container that has everything you need to run all kinds of projects such as classic Symfony based applications.

Run empty container for Symfony (or other) with dockware
docker run --rm -p 80:80 dockware/flex:latest


Yes, we finally have a changelog too.

That changelog focuses on new features that will be available in general across all images and tags.
There will not be a changelog, if a new Shopware version ist being released - only if new features are available.



With dockware, we tried to bring you everything you need to run and develop Shopware 6 in a smooth and easy to use environment.

We've created a couple of features that should help you on your journey to explore Shopware 6.


We know that it's very important to access your database when exploring Shopware 6.
And that should be possible in an easy and convenient way.

That's why dockware comes with an installed version of Adminer, the Shopware 6 preferred MySQL client.

Open Adminer in your web browser with the following URL:

  • /adminer.php
Then enter the default MySQL credentials of dockware.
You can leave the database empty for now.

dockware MySQL connection
Now select the database you want to explore.
The default database of dockware is called "shopware".

dockware MySQL connection
Alright, you do now have access to all tables of the database.
You might become a bit familiar with Adminer.
Select a table, then click on "Select data" and you should see some rows.

dockware MySQL connection


E-Mails are always a "special" challenge when speaking about setups :)
They should just work, they should not be sent out accidentally and you don't really want to configure anything just to explore Shopware 6, right?!

Dockware has a built-in Mailcatcher installed.
That one is already configured for E-Mails that are being sent out either through Shopware or directly with PHP.

But wait! What's Mailcatcher?

Mailcatcher is a web application that acts as a mail server.
The interesting thing is, it receives your email but doesn't send it out to the recipient!
Instead of this, it shows you the mail in its mailbox so you can review it and see how it would look like.

Open Mailcatcher in your web browser with the following URL:

  • /mailcatcher
Here you can see the Mailcatcher inbox.
As soon as emails are sent out, you see them right here!

Please note, in case it's not auto-refreshing, just refresh the page manually.

The Mailcatcher mail server settings can be found here
dockware MySQL connection

Pimp my Log

Logs are very important.
And we know about the frustration when not being able to access it easily.
And that's why every dockware images comes with an installed Pimp my Log log viewer.

Open the log viewer in your web browser with the following URL:

dockware Pimp my Log
Switch between different prepared logs, such as Apache error logs, access logs as well as Shopware logs for either production or development.

dockware Pimp my Log

Switch PHP Version

Every dockware version allows you to switch to any PHP version that is supported by Shopware 6.
This is done when starting your container.
You can either use a command option when using "docker run", or set the PHP version in your docker-compose.yml file.

Set PHP Version with docker run
docker run --rm -p 80:80 --env PHP_VERSION=7.2 dockware/play:latest

Set PHP Version in docker-compose.yml
      image: dockware/play:latest
         - PHP_VERSION=7.2

Tutorial Video available
You can also watch a tutorial video.
Let us know what you think and subscribe to our channel.

dockware video switch php version dockware video switch php version in docker-composer

Tideways Profiling

Want to take a deep look into your code performance?

Then use the PHP profiler tideways. You only need to do 2 things:

  1. Create a tideways account
  2. Configure your API key in the docker environment

Possible Configuration:
Variable Default Value Description
TIDEWAYS_ENV production Set an environment variable to seperate the profiles in tideways. The default is production, as this is in the flex plan of tidwayes the only available environment.
TIDEWAYS_SERVICE web Use this differe between different components/services of your project such as example shop, api etc.
      image: dockware/dev:latest
         - TIDEWAYS_KEY=xxx
         - TIDEWAYS_ENV=production
         - TIDEWAYS_SERVICE=myshop


The Filebeat integration allows you to automatically send log data and files to your Logstash instance if you use an ELK stack.

How to configure filebeat?

If you want to use Filebeat in dockware, you do not only need to turn ON the feature, but also provide a valid filebeat configuration.

The easiest way to do this, is to mount that single file into /etc/filebeat/filebeat.yml.

In addition to this, your Docker container must have access to your logstash container by either using the links or networks in Docker. This needs to be done only if you also have your Logstash within your Docker network :)

Here is an example of a filebeat.yml configuration:
    name: "shop"

  - type: log
    enabled: true
        - /var/log/apache2/error.log
    tags: ["server", "apache"]

  - type: log
    enabled: true
        - /var/www/html/var/log/*.log
    tags: ["shop"]

    hosts: ["logstash:5044"]

Possible configuration variables for the Filebeat integration:

Variable Default Value Description
FILEBEAT_ENABLED 0 Required, 1 (ON), 0 (OFF)

Now that we have all single parts, we can combine them and create our configuration for our docker container.
      image: dockware/dev:latest
        - ./elk/my_shop/filebeat.yml:/etc/filebeat/filebeat.yml

If you start your container, the "docker logs (container_name)" output should show you that Filebeat is now being used.

SSH Users

It's possible to create a separate SSH access that replaces the one that comes out of the box with dockware.

For this, please provide the corresponding environment variables.
This will lead to an automatically created new SSH user when the docker container is launched.
The original default SSH user will not be available anymore!

Variable Default Value Description
SSH_USER not-set Name of the optional new SSH user that replaces the existing one from dockware
SSH_PWD not-set Password of the optional new SSH user that replaces the existing one from dockware
      image: dockware/dev:latest
         - SSH_USER=userABC
         - SSH_PWD=supersecret

MySQL Users

You can easily switch the credentials for the installed MySQL instance.
If you do this, the original root user is being blocked for new remote connections and a new user with the provided credentials is being created for you.

You can also change the password whenever you want as long as the original root user password stays the same.

For this, please provide the corresponding environment variables.

Variable Default Value Description
MYSQL_USER not-set Optional variable to create a separate MySQL user. This is the name of the user.
MYSQL_PWD not-set Optional variable to create a separate MySQL user. This is the password of the user.
      image: dockware/dev:latest
         - MYSQL_USER=userABC
         - MYSQL_PWD=supersecret
Please note, this will only work if you have not touched the original MySQL root user password.
Also, we recommend database backups before changing any credentials.

Shopware Currency

The default currency of a Shopware installation is EURO.
This can only be changed when running the install wizard of Shopware.

With dockware we provide a way to switch the default currency also for existing Shopware 6 shops.

Use the ENV variable SW_CURRENCY with an existing ISO currency value.
      image: dockware/play:latest
         - SW_CURRENCY=GBP

This will not only change the default currency for the system to the selected currency, but also recalculate the factors.
Your new default currency gets the base factor 1.0, and all other currencies will be calculated based on the new default.

Thanks to Shyim for helping with this ;)


If you want to develop your own plugins or if you are working on a project you should definitely use the dockware #dev image.

It comes with all tools you need, whether you are doing some PHP coding or implementing features in the storefront or administration.

Start Developing

We start by preparing our environment.
To develop new plugins, themes and features, in the most efficient way, we recommend a few things.

  • Docker Compose
    This helps you to create a good architecture and blue prints of your setup.
  • IDE with SFTP upload
    We recommend PhpStorm ❤️
    It's just so good...and it also has automatic uploads.
  • Chrome XDebug Extension
    Dockware comes with plug'n'play XDebug.
    All you need is this extension to enable it in your browser.

1. Start Docker
Alright, we're ready to start our development container.
You need 2 basic things for this.

  • docker-compose.yml (template below)
  • a few commands plain or in makefile (below)
We recommend creating a new folder for your project that contains your docker files.

Template File
Use this template file to get started.
It already comes with all ports you might need and volume mounting for both the database and the DocRoot of Shopware.

You can decide to either use the prepared "dev" image with a ready to use Shopware, or use the new "essentials" image that provides you a full environment without an installed Shopware. (see instructions below)


    version: "3"

      image: dockware/dev:latest
      container_name: shopware
         - "80:80"
         - "3306:3306"
         - "22:22"
         - "8888:8888"
         - "9999:9999"
         - web
         - XDEBUG_ENABLED=1

    external: false

Now open your terminal, navigate to the directory with your docker-compose.yml and run this command:
docker-compose up -d

2. Prepare Development
Great, you should now have a running Shopware 6 on your local machine.
The prepared application environment is DEV and should already contain everything you need.

You can immediately access the database with the exposed port 3306 (see FAQ for more).

Now it's time to download the current version of Shopware to your host.
This is required to have code completion and IntelliSense right in your IDE, and thus we need it.

If you want to know why we don't use bind-mounting, please scroll down to the Performance on MAC section.
mkdir -p ./src
docker cp shopware:/var/www/html/. ./src

3. Prepare IDE
Open the src folder with your preferred IDE and wait until finished loading.
Then add a new SFTP connection to your container. We recommend Automatic-Upload if possible.
If you need the SSH/SFTP credentials, please see the FAQ section for details.

If you have PhpStorm, we also recommend enabling the Symfony Plugin for better code completion.

That's it, you're done and ready to develop your Shopware projects!

4. Sample Plugin
To get you started as fast as possible, we've already prepared a Dockware Sample Plugin which is already installed and active.
So you can start right from this plugin with your experiments in Shopware 6....or create your own plugin.

The plugin comes with an active storefront subscriber, sample unit tests and more.
Please review the file within the plugin directory for further instructions.

Switch Branches

We start by preparing our environment.
To develop new plugins, themes and features, in the most efficient way, we recommend a few things.

Switching Branches?
Now that you've completed your first steps in developing with dockware, you might ask yourself "What if I switch branches?" or "What if I just want to restart my container?"

That's actually not a problem, still it relies on the way you and your team work.
The most accurate way would be to clear the container and upload your local source code.
It might also work if you just upload your plugin again after switching branches.

Here are some commands that clean your container and upload everything again - doesn't take long - trust me :).
docker exec -it shopware bash -c 'sudo rm -rf /var/www/html/*'
docker cp ./src/. shopware:/var/www/html/
docker exec -it shopware bash -c 'sudo chown www-data:www-data /var/www -R'


We love rock solid debugging tools and so do you!

XDebug is by far one of the most important debugging tools for PHP developers out there.
That's why our dockware #dev images come with a plug'n'play solution out of the box.

All you need is the recommended Chrome Extension for XDebug.

Download the extension here:

As soon as you start your dockware container with the environment variable XDEBUG_ENABLED=1, you're ready to go.
This environment variable helps you to turn ON or OFF XDebug in case you want to switch over to a production similar environment for some tests.
      image: dockware/dev:latest
         - XDEBUG_ENABLED=1 // 1|0 for ON|OFF

Enable Xdebug in your client

Eanble Xdebug in Chrome
Enable Xdebug in your chrome extension by clicking on the option "Debug".
Now start your XDebug listener in your IDE and start debugging.

dockware with xdebug

Eanble Xdebug in API clients
You might want to debug your API requests or other requets in clients without the Xdebug Helper Tool. In this case you can simply append "XDEBUG_SESSION_START=PHPSTORM" as a get parameter to your Url and it will also debug this request.

Toggling Xdebug
As Xdebug will slow down your dev environment for every request and also for each command like "cache:clear, watch-storefront" etc. You might not wan't to enable it all the time. For this we have built another useful command.
In our global makefile in /var/www we provide the commands for instantly enabling and disabling Xdebug.
make xdebug-on
make xdebug-off

We do also have additional environment variables, that you can use for further configuration.

Variable Default Value Description
XDEBUG_ENABLED 0 Enable or disable XDebug by using 1 or 0 as value.
XDEBUG_REMOTE_HOST host.docker.internal Use default value for MAC + Windows, and for Linux
XDEBUG_CONFIG idekey=PHPSTORM IDE Key identifier for XDebug
PHP_IDE_CONFIG serverName=localhost Used for the serverName export for XDebug usage on CLI

Both MAC and Windows have the Docker variable "host.docker.internal" as default value, which should work great as Loopback IP to automatically recognize the host IP.

For Linux however this does not work! Please use this as ENV variable to make it work!


If you are either working on the storefront or the administration you might want to use the watchers for it.
These will make sure to compile everything as soon as new changes and file modifications have been recognized.
You only need to reload your browser and all changes are visible immediately.

Because the watchers are not very dev-friendly sometimes, we've prepared a small little makefile for you.
It's outside the DocRoot in the directory /var/www
cd /var/www
watch-storefront               Starts watcher for storefront at http://localhost
stop-watch-storefront          Reverts everything back to normal operation
watch-admin                    Starts watcher for admin at http://localhost:8888

Administration Watcher
If you want to start the watcher for the administration, run the corresponding makefile command.
This takes a bit, but not that long.
Afterwards please open the administration with this URL:


As soon as you modify any files in the administration and upload them to the container, the watcher will recognize the changes, and compile the app again. In addition to this, it will also automatically refresh your browser (Hot Module Replacement).

To stop the watcher, simply cancel the command / process.

Storefront Watcher
If you want to work on the storefront, please start the watcher command for this.
The storefront is available with this URL:


In case you are wondering why no additional port 9999 is being used, the answer is pretty simple.
If you take a close look at the XHR request, you'll see that only the assets like JavaScript files are being loaded from that port.

One of the things in Shopware 6 that makes using the storefront watcher a bit harder, is that the trigger if port 9999 should be used or not, is done by using a request header entry.

Most developers out there tend to just change that variable in the twig file.

If you use our make commands, a new .htaccess file is being injected which automatically inserts that header for you.
So there's no need to do anything on your side! Just code!

Please consider, due to this, there's a separate "stop" command, to remove it again and get back to the original storefront without the watcher.

Update Shopware

If you want to update Shopware itself, then there are 2 basic options.

  • If you are a plugin manufacturer, you could simply switch to a new dockware Shopware version and upload your plugin again. That should be fine.
  • If you have full projects, then you might either want to update Shopware using composer or through the built-in Shopware updater tool.
    Afterwards make sure you download the source again to your host to keep it consistent.

    Please note, it might be irritating, but in this case your used container still has the older Shopware version.
    Due to your custom update, that tag has no effect anymore as long as you use some kind of volume mounting.
    You can set your new tag if you prefer that for visual aspects.

Dockware Essentials

With dockware #dev you always see the preinstalled Shopware version in your docker-compose.yml (dockware/dev:6.2.0, ..).

However, if you have longer running projects, especially when developing for a client, and you have "more" than just a plugin, you might handle Shopware and all additional updates on your own.

This means that the version of your compose file, can actually differ from the one that is currently used.

In this case dockware #essentials can help you :)

This image does not contain any Shopware version, but still offers you a complete Shopware 6 environment.
Just upload any of your projects in any Shopware 6 version.

It's also a perfect fit if you decide to migrate to dockware.

How to use
We recommend starting with our #dev guidelines and then use #essentials.

It's basically the same as in our #dev workflow, only without the "downloading" process to your host.
Using #essentials is more about "uploading" your shop from the host to your container.

You can also use all tools like XDebug, watchers, mailcatcher, and also additional features of Docker and more.
(Please keep in mind that you might need to modify some commands in your own project to make them work with the integrated dockware services).

Essentials Image:


Shopware is Open Source!
And that means you can actively support the community and improve the platform for everyone around the world.

Still, sometimes it's a bit hard to setup everything and prepare your Pull Request on Github.

Thats why dockware #contribute exists.

It should help you to get the latest version of Shopware up and running in a minimum amount of time.
Please keep in mind, we do our best to make it as fast as possible.
Though we cannot make PSH commands faster, we can only try to speed up the whole workflow for you.

Setup Github Version

Let's start again with our environment.
You need the same things as already mentioned in the dev version of Shopware.
If you are not familiar with the dev version, you might want to read through that first.

Let's take a look at our main goals for the contribution version.

  1. Start Docker
  2. Prepare Development + IDE
  3. Github Fork and Remote

1. Start Docker
Start dockware with our docker-compose.yml template file or your own file.
We recommend creating a new folder for your project that contains your docker files.

    version: "3"

      image: dockware/contribute:latest
      container_name: shopware
         - "80:80"
         - "3306:3306"
         - "22:22"
         - "8888:8888"
         - "9999:9999"
         - web

    external: false

2. Prepare Development + IDE
Download the source code, and open it in your IDE.
mkdir -p ./src
docker cp shopware:/var/www/html/. ./src

You will now see a folder "platform" that contains Shopware 6.

There are indeed 2 repositories inside each other.

  • shopware/development
    The main symfony project that has Shopware as dependency in the vendor folder
  • shopware/platform
    This is the actual Shopware 6 source code. It should be modified in the directory "platform" and is automatically symlinked to the vendor directory of our symfony development project.
Now add the SFTP connection again to upload changes to the dockware container.

That's it, you're ready to improve Shopware and help the community!
Please keep in mind, that you should only develop in the folder "platform"!

3. Github Fork and Remote
To create pull requests, you need to have a fork of the Shopware platform on Github.
Open this page, sign in on the Github page and fork the repository:

Afterwards add your new fork as remote in your local git repository.
Open your platform directory in your terminal and execute these commands with your username:
git remote add myfork

Create Feature

It's finally time to create our new feature.

dockware brings you a running Github version of Shopware 6.
Still, its not possible to always deliver the latest commit. There will be multiple new ones everyday on Github.

We recommend pulling the latest version before you start a new feature.
Do this by pulling the "development" and the "platform" repository on your host machine.
Open your terminal and navigate to the "src" folder.
git pull
cd platform && git pull

Great, we are up to date.
Now just start a new feature branch that will be used for the pull request later on.
git checkout -b my-new-feature origin/master

Upload Source / Switch Branches

To restart your work from your updated repository, please upload the source to your docker container.
Please note, that due to branch switching it can happen that symlinks get lost!

Just remove the "composer.lock" along with the "/vendor" folder and use "composer install" one more time.

An even better and cleaner idea is to completely reinstall Shopware when starting all over.

Here is a script that completely reinstalls Shopware and makes sure that you can work smoothly:
cd ((outside src directory)
docker exec -it shopware bash -c 'sudo rm -rf /var/www/html/*'
docker cp ./src/. shopware:/var/www/html/
docker exec -it shopware bash -c 'sudo rm -rf composer.lock'
docker exec -it shopware bash -c 'sudo rm -rf /var/www/html/vendor'
docker exec -it shopware bash -c 'sudo chown www-data:www-data /var/www -R'
docker exec -it shopware bash -c './psh.phar install'

Open http://localhost and your updated Shopware 6 should be back.

Code Styles

Please ensure that your source code uses the Shopware guidelines regarding code styles.

Use the following tools and commands to scan your source code.
Please note some features provide the option to "auto-fix" problems. Keep in mind that you need to download affected files to your host in that case. Maybe just download everything, GIT will show you all diffs anyway.

CS Fixer
./psh.phar fix-cs

Run this command do analyze and auto-fix your modifications in the administration.
cd platform/src/Administration/Resources/app/administration && ./node_modules/.bin/eslint --fix --ext .js,.vue src test

PHPStan and Psalm
Last but not least, run the static analyzer to check your code quality with help of PHPStan and Psalm.
./psh.phar static-analyze

Here is a final copy-paste script that you can use to run all these tools and also automatically download the source code again.
docker exec -it shopware bash -c './psh.phar fix-cs'
docker exec -it shopware bash -c 'cd platform/src/Administration/Resources/app/administration && ./node_modules/.bin/eslint --fix --ext .js,.vue src test'
docker exec -it shopware bash -c './psh.phar static-analyze'
docker cp shopware:/var/www/html/platform/src/. ./src/platform/src


PHP Unit Tests
We highly encourage you to execute the unit tests before creating a Pull Request.
Connect into your container and run this command:
./psh.phar unit

We know the unit tests take quite a long time.

If you want to just execute tests you have created, simply assign your custom group to your test.
Then run the test suite only for the tests of your custom group.

That should be way faster

Don't forget to still run all tests before creating your pull request.
     * @group mysample
    public function testMyFeature(): void
php ./vendor/bin/phpunit --configuration ./vendor/shopware/platform/phpunit.xml.dist --group mysample

Administration Tests
There is also a test suite for unit tests in the administration.
You can run the Javascript tests with the following command:
./psh.phar administration:unit 

Create Pull Requests

Push your feature branch to Github and submit your new feature with a new Pull Request.
Open the Shopware Platform Github repository and click the "Compare & pull request"-Button.

Shopware Contribution Guideline
Please see this guideline before creating your first pull request.
It helps you to avoid any unnecessary stops before your feature is being merged.

That's it, you've just created your first pull request.
Now it's up to Shopware to decide if its all OK and can be merged.

Thank you for being a part of the Shopware community!

Every feature, every improvement and every bug fix counts.
We all appreciate all those devs out there who make Shopware better and better with every single day.

Tutorial Video available
Watch the video and get everything explained in easy and simple steps.
Let us know what you think and subscribe to our channel.

dockware contribute getting started

Performance on MAC

Docker is slow on your MAC?
This can have many reasons!
It's good to have a basic knowledge in Docker and also to cleanup your system.
We want to give you some insight in our best practices which work really good for us.
Don't use Bind-Mounting!
One of the most mistaken things out there when people say Docker for MAC is slow,
is because they use bind-mounting with a huge number of files (assets, caches, and more).
And yes, Shopware and also Symfony have lots of these files.
In Linux it works better, but shouldn't we just make a step back and focus on what the problem is?!

Docker offers us a way of running a separate and isolated system on our host machine.
In combination with lots of deeper integrations such as "docker cp", "docker exec", "bind-mounting" and more, we tend to think we really need these things. And that's the problem!

Our best practice is to use SSH/SFTP and strictly avoid any bind-mounting and anything that shares files between your host and your container!
But what about coding and all these developer tools?!
No worries. It always worked that way in earlier days.
Write code on your host, and use SFTP automatic uploads.

If you have any watchers - just run it in your container and as soon as you upload anything using SFTP, they will start to recognize changes and give you the expected output.

Simple and easy, isn't it?!
But hey, my initial upload with SFTP just takes too much time!
Yes, that's correct!
For initial uploads we do indeed use the "docker cp" command. That's a lot faster.
So just use this command, maybe do some "chown" permission changes and then go back to SFTP upload.

Here's an example:
docker cp src/. my-container:/var/www/html
docker exec my-container bash -c 'chown www-data:www-data /var/www -R'
Docker is slow again after lunch break
You might experience performance problems after your MAC has been in sleep mode for a while.
This is usually if you come back from lunch or from long meetings.

If it's disturbingly slow, simply restart Docker and start dockware again.
That's the easiest thing.

You can also prevent your host from sleeping or from turning off its disks in such cases.

Persisting Data

We learned to avoid bind-mounting.
But what if you want to persist data to have it all available again after recreating your containers?

Docker offers a way of using internal volumes to persist data.
And that works fast, really fast.

So if you want to persist the state of your current work, use internal volume mountings and just do plain SFTP from your host.

Here's an example of a docker-compose.yml that persists the DocRoot of your shop and also your database:
    version: "3"

      image: dockware/play:latest
      container_name: shopware
         - "db_volume:/var/lib/mysql"
         - "shop_volume:/var/www/html"
         - web
    driver: local
    driver: local

    external: false


As it is in real life - some house keeping doesn't hurt nobody!
If your hallway is loaded with lots of messy stuff, you just can't walk through it as fast as you want to.

And it's the same with Docker.
Cleaning and removing unused and dangling images and volumes makes things faster again.

Removing all unused images can save Gigabytes of space on your machine.
docker image prune

Removing volumes that are not used by a container anymore keeps overhead small...
docker volume prune

For further information, please visit the Docker website


Please keep in mind that you might lose important data when removing images or volumes.


Security is always important!
Please keep in mind, that dockware is primary made for local development!

This does not mean you cannot use it for a server that is available on the internet.
But please consider a few security related things.
Don't expose ports like you would do locally
In our docker-compose.yaml samples, you see all kinds of ports being exposed.
This is great for local development - but not for a server - even it's "just" a staging system.

Our recommendation is to only expose ports that are really necessary to use your app.
And this should only be done through 1 single docker container, probably a proxy like NGINX.
This helps you to avoid losing control over what is exposed throughout your (bigger) yaml file.

If you expose a port, make sure to add an additional restriction if possible.

This sample would only expose the port 3306 MySQL for connections from the localhost (host system).
So you can do a default SSH connection to your host, and then a connection from there to your MySQL container. This is pretty much the basic workflow of such a scenario - only with Docker ;).


Please do never expose port 22 from dockware on an online server if you do not know what you are doing! Pay attention to the weak default credentials - and consider using a firewall.


Default Credentials

What are the default Shopware Admin credentials?
User: admin
Password: shopware

Shopware Admin login screen
What are the default dockware MySQL credentials?
User: root
Password: root
Port: 3306

Please note, that you need to make the port available to your host machine.

dockware MySQL connection
What are the default dockware SSH/SFTP credentials?
User: dockware
Password: dockware
Port: 22

Please note, that you need to make the port available to your host machine.

dockware SSH SFTP connection
What are the default dockware Mailcatcher settings?
Host: localhost
Port: 1025

dockware mailcatcher integration
What are the default Shopware 5 Backend credentials?
User: demo
Password: demo

Shopware 5 Backend login screen

Sequel Pro

How to use Sequel Pro?

You can use Sequel Pro or any other MySQL client to access the Shopware database.

To connect to MySQL from outside your docker container, make sure to expose the port 3306 and make it accessible by hour host.

This can either be done by providing a port when using "docker run -p 3306:3306" or within the "ports" section of your docker-compose.yml.

Please note, you don't need to use 3306 on your host, you can use any free port like 3300:3306, but keep in mind to use that one when connecting from Sequel Pro.

dockware with mysql tool - connection

Dockware and other images

Can i use dockware in combination with other images?
Dockware is a Docker image like every other image.
You can combine it with 3rd party services such as Redis, Elasticsearch, a separate MySQL, Percona or anything else.

Make sure they are on the same Docker network and use the key names of the containers as host addresses.

Here's an example:
    version: "3"

      image: dockware/play:latest
      container_name: shopware
         - "80:80"
         - web
      image: mysql:5.7
      container_name: mysql
        - web
        - MYSQL_ROOT_PASSWORD=hidden
        - MYSQL_USER=shopuser
        - MYSQL_PASSWORD=secret
        - MYSQL_DATABASE=shopware

    external: false
To access the standalone MySQL instance, use this connection string:
mysql://shopuser:[email protected]:3306/shopware


Where are my scripts?
If you are looking for official scripts to e.g. build the storefront or administration, you might want to look into the bin folder of Shopware.

the #play and #dev images of dockware are both based on the production template.

If you want to dig deeper, please see this page for further details: shopware/production on GitHub.

If you use dockware #contribute, you can use the official PSH commands of Shopware.

Custom Domains

We have prepared everything for a smooth launch using http://localhost - but you don't need to stick with that.
It's of course possible to switch domains.
You only need 2 things to make this happen:

  • Database Domain:
    Change the "url" field of your sales channel in the database table "sales_channel_domain".
    This should be the one you want to use.

  • "/etc/hosts" file:
    This file on your host is a lookup dictionary that tells your machine that a certain IP should be used for a domain. Just insert this to say that your domain is your localhost IP.

Your Shopware should now be available using this domain.


How to use Redis?
Redis is a Key/Value storage that allows you to save data outside your database with blazing fast access.
Shopware supports the usage of Redis for session and cache handling.

Here is a sample of a docker setup that adds a new Redis instance to your Docker network. Just add the container and make sure its on the same network.
    version: "3"

      image: dockware/play:latest
      container_name: shopware
         - "80:80"
         - web
      image: redis:5.0.6
      container_name: redis
        - web

    external: false
Now make sure you configure the Redis instance to be used either for session handling, cache handling or both.

Add the following to your ".env" file:

MySQL failed

MySQL failed on startup.
This is a very rare error.
It has to do with sharing of layers (we think).
So in fact, we haven't been quite able to figure it out, but we have a solution.

Solution for alle Images since 2020-11-05

We have fixed that error on 5th november 2020. So just pull the newest image and the error should not happen again.

Please keep in mind that this will remove any persistent data if you do not have mounted a volume for mysql.

You have to remove the volumes for your container.


Please keep in mind that this will remove any persistent data that you have.
Think about this step before proceeding.

We start by removing our container.
Use this script with the name of your actual container (shopware in our case).
docker rm -f shopware
Now we have to remove the volumes. Let's find their names.
docker volume ls
Figure out what volumes belong to your image (by using their names) and then delete the mysql (and maybe shop) volumes.
docker volume rm -f [name]

If you now restart your docker container, it should work again.
It's also time to restore your clean MySQL dump, if you have a running project ;)


How to use Elasticsearch?
Elasticsearch is a full-text, distributed NoSQL database for big data.
It has amazing options for real-time searching and data analyzing.

Shopware recommends the usage of Elasticsearch for large data sets of products.
They also support in its search engine for better search results.

Here is a sample of a docker setup that adds a new Elasticsearch instance to your Docker network. Just add the container and make sure its on the same network.
    version: "3"

      image: dockware/play:latest
      container_name: shopware
         - "80:80"
         - web
      image: elasticsearch:7.5.2
      container_name: elasticsearch
        - web
        - "EA_JAVA_OPTS=-Xms512m -Xms512m"
        - discovery.type=single-node

    external: false
Now make sure you configure the Elasticsearch instance to be used.

Add the following to your ".env" file:

Windows Problems

Can't connect into container on Windows
If your terminal says that you don't have an tty or interactive terminal, you might want to prefix winpty which should work for you:
winpty docker exec -it shopware bash

System cannot find the path specified in "docker cp".
Some directories and paths are long in Shopware...really long :).
Unfortunately Windows might tell you this too. The good thing is, there's a fix for long file names.

Please try these things:
  • Move your project to C:\ which might shorten things automatically if you've had a deeper directory before.
  • If you are on Windows 10, you can enable long paths.
    Open the Computer Configuration > Administrative Templates > System -> Filesystem > Enable NTFS long paths. You can also modify the corresponding registry entry HKLM\SYSTEM\CurrentControlSet\Control\FileSystem to LongPathsEnabled (Type: REG_DWORD) to remove most of the MAX_PATH limitations.

Chrome Problems

Google Chrome shows "Your connection is not private"
This can happen if you use localhost in combination with https.
Please open this URL in your Chrome Browser to access the chrome settings:


Then set "Allow invalid certificates for resources loaded from localhost." to be enabled.

Google chrome -  Your connection is not private
Allow invalid certificates for resources loaded from localhost

Shopware 5 Support

Do we support Shopware 5?
The main focus of dockware is definitely Shopware 6.
Still we heard your requests about supporting Shopware 5.

So we have decided to do a limited support of Shopware 5 with a few versions (and not every single one).

It works basically the same as with Shopware 6. Only a few things like watchers and so on are either different or not included.

Please see Docker Hub for existing Shopware 5 versions.

dockware is built with passion and proudly presented by
shopware agency dasistweb.

report Issue