Installing / Developing Shopware 6 with ddev

[Guide updated on 23.10.2020 - based on Shopware 6.3, better ddev port settings - updated in 03/2021 - added hint on resolving APP_URL message -
updated in 07/2021 - added hint about mailer config in admin backend]

This guide shows how to install Shopware 6 based on ddev including Elasticsearch and file watchers.

What's ddev?
ddev is an open source tool providing simple, cross-platform, docker based local development setups for web / PHP projects.
Find out more at https://ddev.com/ddev-local/

Basic Installation

First, we need to clone the production template from shopware and add the basic ddev configuration and do a composer install:

git clone --branch=6.3 github.com/shopware/production shopware
ddev config [with defaults]
ddev start
ddev composer install

Warning:
If you want to use the hot module reload part for frontend development do not use https!

Then, we use the provided system setup command to add a basic .env file.

The following excerpt only shows those settings, that are different from the default:

ddev exec bin/console system:setup

> URL to your /public folder [http://shopware.local]:
> shopware.ddev.site

## Database information

Database user [app]:
> db

Database password:
> db

Database host [localhost]:
> db

Database port [3306]:
>

Database name [shopware]:
> db

Resolve: Environment variable not found: "APP_URL"
Might happen until https://issues.shopware.com/issues/NEXT-12476 is fixed. !!! !!! Create the .env file manually, and fill in the single value like this: !!! APP_URL="https://shopware.ddev.site" !!! !!! Then run the command again with the -f option:
ddev exec bin/console system:setup -f
Now the procedure starts as expected. (Thanks to Anja)

Tip
Display infos about your ddev environment (including database credentials) with ddev describe

To get started quickly, we can now use the system:install command to install with a basic setup:

ddev exec bin/console system:install --create-database --basic-setup

Only one thing left: Adjust the .env file to allow shopware to send mails to ddev's mailhog:

MAILER_URL="smtp://localhost:1025?encryption=&auth_mode="

To make sure shopware uses the env variable, go to the shopware administration -> Settings -> System -> Mailer and select "Use environment configuration" from the drop down list. 

Ready :) - Launch with ddev launch and enjoy!

Adding Elasticsearch

To add Elasticsearch to your Shopware 6 ddev setup, first make sure ddev is stopped:

ddev stop

Then add the following config in file .ddev/docker-compose.elasticsearch.yaml:

version: '3.6'

services:
    elasticsearch:
        image: elastic/elasticsearch:7.1.1
        environment:
            - 'ES_JAVA_OPTS=-Xms512m -Xmx512m'
            - discovery.type=single-node

Adjust the .env file with the elastic specific settings:

SHOPWARE_ES_HOSTS="elasticsearch:9200"
SHOPWARE_ES_ENABLED="1"
SHOPWARE_ES_INDEXING_ENABLED="1"
SHOPWARE_ES_INDEX_PREFIX="sw"

And start the project again with ddev start.

You can test if it's working with:

ddev ssh
curl -X GET elasticsearch:9200/_aliases

Resulting in something like verifying that Shopware could connect.

{
    "sw_product_2fbb5fe2e29a4d70aa5854ce7ce3e20b_1595328482": { "aliases": {} },
    "sw_product_f3a34446aae24f5dbf689e32374b2c69_1595328482": { "aliases": {} }
}

You may need to clear/update indexes in the Shopware backend before you see a result.

Build Storefront

Building the Storefront for production is easy and does not require additional steps. Simply execute:

ddev exec bin/build-storefront.sh

... and wait for the build to finish (which might take some minutes).

Watch Storefront

When you develop custom frontends for Shopware you most likely do not want to build every time you make a change. Luckily, the Shopware production template provides us with a script to watch the Storefront.

To be able to use the Shopware watch command to directly see your frontend changes and make use of hot-reload functionality in ddev you need a few more steps:

• at least one build has to have run to ensure availability of all dependencies
• the ports used need to be added to the ddev docker config to make them reachable from the host

The watch command opens a web pack hot proxy and a shopware proxy - those ports need to be mapped.

Add a file .ddev/docker-compose.shopware.yaml with the following content:

version: "3.6"

services:
    web:
        expose:
            - 9998
            - 9999
        environment:
            - HTTP_EXPOSE=${DDEV_ROUTER_HTTP_PORT}:80,${DDEV_MAILHOG_PORT}:8025,9999:9999,9998:9998
            - HTTPS_EXPOSE=${DDEV_ROUTER_HTTPS_PORT}:80,${DDEV_MAILHOG_HTTPS_PORT}:8025,8899:9999,8888:9998

Restart ddev and execute

ddev exec bin/watch-storefront.sh

Open a browser with your-shopware.ddev.site and enjoy.

!!!
!!! The HTTP_EXPOSE / expose configuration helps ddev to keep track of the used ports per project and !!! allows having multiple projects with the same exposed ports (for example: if you run more than one !!! shopware project at the same time)
Read StackOverflow Post for more Info

Build Administration

Building the administration files is as easy as it was for the Storefront. Simply execute

ddev exec bin/build-administration.sh

Watch Administration

To enable the watcher for the Vuejs based administration of Shopware, we need to add a few settings again. As we run the watcher inside the ddev container, we need to change its binding from localhost to 0.0.0.0 and switch the port to a defined port we again make available on the host via docker-compose settings.

Adjust .ddev/docker-compose.shopware.yaml to combine both storefront and administration watcher settings:

version: "3.6"

services:
    web:
        expose:
            # Storefront Hot Proxy Ports
            - 9998
            - 9999
        ports:
            # Shopware Administration Watcher (see below)
            - 9997:9997
        environment:
            # Shopware Administration Watch Host
            - HOST=0.0.0.0
            # Shopware Administration Watch Port
            - PORT=9997
            # Expose APP_URL to administration watcher
            - APP_URL=http://shopware.ddev.site
            - HTTP_EXPOSE=${DDEV_ROUTER_HTTP_PORT}:80,${DDEV_MAILHOG_PORT}:8025,9999:9999,9998:9998
            - HTTPS_EXPOSE=${DDEV_ROUTER_HTTPS_PORT}:80,${DDEV_MAILHOG_HTTPS_PORT}:8025,8899:9999,8888:9998

and then run ddev exec bin/watch-administration.sh.

You can now access it via localhost:9997.

!!
At the time of writing, it is not possible to run the administration watcher on domains != localhost in this setup, as !! localhost is hard-coded into the main administration dev template and additionally, strict host checking is enabled.
!! Read related Shopware issue on Github

That's it. With this setup you have a complete Shopware 6 development setup based on ddev.