Project Template
The Shopware project template is a Composer project that can be used as starting point for new Shopware Projects, or if you want to develop extensions or themes for Shopware.
Set up a new project
To create a new Shopware project, run the following command:
composer create-project shopware/production <project-name>
# or install a specific version
composer create-project shopware/production:6.6.10.0 <project-name>
INFO
Composer create-project clones the latest tag from the Template repository and installs the dependencies. If you don't have Composer installed, you could also clone the repository itself and run composer install
in Docker to proceed with the installation.
This creates a new project in the <project-name>
directory.
The template contains all Shopware bundles like shopware/administration
, shopware/storefront
and shopware/elasticsearch
. If you don't need any, then you can uninstall them with:
composer remove shopware/<bundle-name>
Installation
After you have created the project, you have automatically a .env
file in your project root. This file contains all the environment variables you need to run Shopware.
If you want to adjust a variable, you should put the variable in a .env.local
file. This file will override the variables in the .env
file.
INFO
The .env
will be overwritten when the Shopware Web Installer is used for Shopware updates, so it's highly recommended to use a .env.local
file.
After you have adjusted the .env
file, you can run the following command to install Shopware:
bin/console system:install --basic-setup
The flag --basic-setup
will automatically create an admin user and a default sales channel for the given APP_URL
. If you haven't created a MySQL Database yet, you can pass the --create-database
flag to create a new database.
The Shopware's default Administration credentials are:
Username | Password |
---|---|
admin | shopware |
Change these credentials after finishing the installation.
Optional packages
The template is small and does not contain any dev-tooling or integrations like PaaS or Fastly. You can easily add them to your project with the following commands:
# Install profiler and other dev tools, eg Faker for demo data generation
composer require --dev shopware/dev-tools
# Or Install symfony dev tools
composer require --dev symfony/profiler-pack
# Install PaaS integration
composer require paas --ignore-platform-req=ext-amqp
# Install Fastly integration
composer require fastly
Add Shopware packagist
Using Shopware Packagist, you can manage all your Shopware Store plugins directly in the composer.json
. Refer to "Using Composer for plugin installation in Shopware" blog post for detailed information.
Building/Watching Administration and Storefront
The created project contains Bash scripts in bin/
folder to build and watch the Administration and Storefront. You can run the following commands:
./bin/build-administration.sh
./bin/build-storefront.sh
./bin/watch-administration.sh
./bin/watch-storefront.sh
Use these scripts to build the Administration and Storefront. The watch
commands will watch for changes in the Administration and Storefront and rebuild them automatically.
Update Shopware
There are two ways to update Shopware:
Initially run
bin/console system:update:prepare
to enable the maintenance mode and then update all Composer packages usingcomposer update --no-scripts
. The--no-scripts
flag instructs composer to not run any scripts that may reference Shopware CLI commands. They will only be functional after updating the recipes. To disable the maintenance mode, runbin/console system:update:finish
.To force-update all config files, run
composer recipes:update
.
Migrate from old zip installation to new Project Template
Before Shopware 6.5, we provided a zip file for installation. The zip file contained all dependencies required to run Shopware. This method has been deprecated and replaced with a Composer project template. The Composer project template is way more flexible and allows you to manage extensions together with Shopware itself using Composer.
To migrate from the old zip installation to the new Composer project template, you can use shopware-cli project autofix flex
command to migrate it automatically, or you can do it manually by following the steps below.
1. Backup
Start with a clean git state, stash everything or make a backup of your files.
2. Adjust root composer.json
First, adjust your root composer.json
. Add the following lines to your composer.json
:
"extra": {
"symfony": {
"allow-contrib": true,
"endpoint": [
"https://raw.githubusercontent.com/shopware/recipes/flex/main/index.json",
"flex://defaults"
]
}
}
Next, replace all the existing scripts with the following:
"scripts": {
"auto-scripts": [],
"post-install-cmd": [
"@auto-scripts"
],
"post-update-cmd": [
"@auto-scripts"
]
}
Finally, remove the fixed platform as it will now be determined by the required packages.
"config": {
"optimize-autoloader": true,
- "platform": {
- "php": "7.4.3"
- },
"sort-packages": true,
"allow-plugins": {
"composer/package-versions-deprecated": true
}
},
3. Cleanup the template
After having installed the new Composer packages, you can clean up the template by removing the following files:
rm -r .dockerignore \
.editorconfig \
.env.dist \
.github \
.gitlab-ci \
.gitlab-ci.yml \
Dockerfile \
docker-compose.yml \
easy-coding-standard.php \
PLATFORM_COMMIT_SHA \
artifacts \
bin/deleted_files_vendor.sh \
bin/entrypoint.sh \
bin/package.sh \
config/etc \
src \
config/secrets \
config/services \
config/services.xml \
config/services_test.xml \
license.txt \
phpstan.neon \
phpunit.xml.dist \
psalm.xml
touch .env
4. Install required Composer packages
To install Symfony Flex, you need to have Composer installed. If you don't have Composer installed, please follow the official documentation.
To install Symfony Flex, you need to run the following commands and allow both new Composer plugins.
composer require "symfony/flex:*" "symfony/runtime:*"
composer recipe:install --force --reset
5. Review changes
Review the changes and commit them to your Git repository. All upcoming config changes can be applied with composer recipes:update
.
You may need to adjust some environment variables as the names have changed:
Old name | New name |
---|---|
MAILER_URL | MAILER_DSN |
SHOPWARE_ES_HOSTS | OPENSEARCH_URL |
Known issues
APP_ENV=dev
web_profiler missing extension error
Prior to Shopware 6.4.17.0, you have to install the Profiler bundle to get APP_ENV=dev
working with:
composer require --dev profiler
framework:demo-data is missing faker classes
Prior to Shopware 6.4.17.0, you have to install some packages to get framework:demo-data
command working:
composer require --dev mbezhanov/faker-provider-collection maltyxx/images-generator