Template for developing and testing Shopware 6 plugins and themes. It is a local development setup, not a production environment.
This repository has two intended modes:
- Template maintenance: improve the shared Docker, Make, script, documentation and extension template foundation.
- Project usage: create a new project from the template and commit customer-, plugin- or theme-specific code there.
Do not develop long-lived customer extensions directly in the template repository. Create a project repository from the template first.
See docs/template-usage.md for the recommended GitHub workflow and parallel project setup.
Dockware is the primary runtime. Only ./custom/plugins is bind-mounted into /var/www/html/custom/plugins; the Shopware core stays inside the pinned image. A local source mirror for IDE completion can be created with make ide-sync.
Dockware provides a prepared Shopware installation, MySQL, Mailcatcher, Adminer, logs and watcher helpers. The official Shopware CLI is integrated for stable extension workflows, but it does not replace Dockware automatically.
The pinned Shopware CLI is installed into tools/ by make shopware-cli-install. It is used for extension validation and archive builds. make shopware-cli-evaluate writes a maturity report to docs/shopware-cli-evaluation.md.
Git, Docker Engine/Desktop, Docker Compose v2, Make, curl, tar and unzip. Local PHP, Composer and Node.js are not required for the Dockware workflow, except optional host-side validation.
For a project created from this template:
git clone <repository-url>
cd <repository>
cp .env.example .env
make doctor
make initFor template maintainers:
git clone <template-repository-url>
cd <template-repository>
cp .env.example .env
make doctor
make smoke-testDefaults from Dockware:
- Storefront:
http://localhost:8080 - Administration:
http://localhost:8080/admin - Admin login:
admin/shopware - Mailcatcher:
http://localhost:1080 - Adminer:
http://localhost:18081 - MySQL:
127.0.0.1:3307, userroot, passwordroot - SSH/SFTP:
dockware@127.0.0.1:2222, passworddockware
Own extensions live in custom/plugins. Generated reports, dumps, build artifacts and IDE source mirrors are below var/ and ignored by Git.
Publish this repository as a GitHub template repository. New projects should be created from that template and get their own Git history, version pins, ports and extension code.
Recommended template release flow:
make doctor
make smoke-test
make validate
git status --short
git tag v0.1.0
git push origin main --tagsWhen a project was created from the template, update its .env before starting if another local project already uses the default ports.
Multiple projects can run side by side. Each project needs a unique COMPOSE_PROJECT_NAME and unique published ports in its local .env.
Example for a second local project:
COMPOSE_PROJECT_NAME=shopware-client-b
HTTP_PORT=8090
HTTPS_PORT=8453
DB_PORT=3317
SSH_PORT=2232
MAILCATCHER_PORT=1090
ADMINER_PORT=18091
PIMPMYLOG_PORT=18092
ADMIN_WATCH_PORT=5183
STOREFRONT_WATCH_PORT=10008
STOREFRONT_HMR_PORT=10009make plugin-create NAME=AcmeExamplePlugin VENDOR=Acme
make plugin-refresh
make plugin-install NAME=AcmeExamplePlugin
make plugin-activate NAME=AcmeExamplePlugin
make test-plugin NAME=AcmeExamplePluginmake theme-create NAME=AcmeExampleTheme VENDOR=Acme
make plugin-refresh
make plugin-install NAME=AcmeExampleTheme
make plugin-activate NAME=AcmeExampleTheme
make theme-refresh
make theme-compileAssign themes in Administration under sales channel theme settings, or inspect available commands with make console CMD="list theme".
make storefront-build
make storefront-watch
make admin-build
make admin-watchDockware watcher ports are exposed through .env: Administration 5173, storefront 9998 and HMR 9999.
make test
make test-plugin NAME=AcmeExamplePluginTests run in the Shopware container and install plugin-local Composer dev dependencies where needed.
make shopware-cli-install
make validate
make extension-buildArtifacts are written to var/artifacts/ and reports to var/reports/.
Change versions only to a Dockware tag confirmed by docker manifest inspect.
make version-switch VERSION=6.7.11.0
make down
make upFor a clean database volume:
make destroy CONFIRM=yes
make initmake db-dump
make db-restore FILE=var/dumps/example.sqlreset restarts the environment and keeps the volume. destroy CONFIRM=yes removes containers and volumes.
make ide-syncConfigure PhpStorm or VS Code to use var/shopware-source as read-only library source. Map /var/www/html/custom/plugins to ./custom/plugins for debugging.
Set XDEBUG_ENABLED=1 in .env, restart with make restart, and listen on port 9003. The Compose file adds host.docker.internal:host-gateway for Linux. PhpStorm server path mapping: /var/www/html/custom/plugins to <repo>/custom/plugins.
Commit template, scripts and docs. Do not commit .env, dumps, artifacts, tools/shopware-cli, source mirrors, vendors or node modules.
.github/workflows/extension-quality.yml mirrors local validation: shell checks where available, YAML parse, Shopware CLI install, extension validation and archive build.
The setup targets local development and test workflows. It does not manage production secrets, deployments, high availability, external services or Shopware account/store publishing.
No automatic migration is performed. See docs/adr/0001-dockware-as-primary-development-environment.md and docs/shopware-cli-evaluation.md.
Run make doctor first. On WSL2 keep the repository in the Linux filesystem, not under /mnt/c. If ports are busy, edit .env. If the browser rejects HTTPS, use HTTP or trust the local certificate manually.
- Dockware docs: https://docs.dockware.io/
- Dockware image tags: https://hub.docker.com/r/dockware/shopware
- Shopware CLI docs: https://developer.shopware.com/docs/products/tools/cli/
- Shopware releases: https://github.com/shopware/shopware/releases
- Docker Compose docs: https://docs.docker.com/compose/