Versioning & Dependencies

Versioning & Dependencies

Shopware 6 production template

The Shopware 6 production template enables you to build, package and deploy Shopware 6 to production shops. This template is also used to build the official packages distributed by shopware.
GitHub - shopware/production: Shopware 6 production template
GitHub
The template is optimized for production usage and contains basic development tooling. It's intended as a basis for project customizations, which are usually done by agencies.
If you want to contribute to the Shopware Platform or develop store plugins, you should use the development template.

Branches and stability

In each commit a composer.lock is contained to ensure that the version being deployed is the version that was tested in our CI. We currently provide the following branches:
    6.3: stable minor and patch releases (v6.3.0.0-rc2, v6.3.0.1, v6.3.1.0, v6.1.*, but not v6.4.0.0)
    trunk: stable major, minor and patch releases (v6.3.0.0, v6.3.1.0, v6.4.0.0, v6.5.0.0...)
The 6.3 branch contains all the 6.3 releases. It's stable now and only gets non-breaking changes. (security issues are an exception).
The trunk branch contains the newest stable release, including major releases. That may result in plugins being incompatible, so be careful.
Starting with 6.3.0.0, we use a slightly modified version of SemVer. The pattern looks like this: 6.MAJOR.MINOR.PATCH. Examples:
    6.3.2.5 - Major=3, Minor=2, Patch=5
    6.4.1.0 - Major=4, Minor=1, Patch=0
See also:
https://www.shopware.com/en/news/shopware-6-versioning-strategy
www.shopware.com

Requirements

To get an overview of the requirements see the following guide of your documentation first:
NPM and Node are only required during the build process and for development. If you don't have javascript customizations, it's not required at all. Because the storefront and admin are pre-build.
If you are using a separate build server, consider having NPM and Node as build-only requirements. Your operating application server doesn't require any of these to run Shopware 6.

Setup and install

To set up the environment and install with a basic setup run the following commands:
1
# clone newest 6.3 patch version from github
2
git clone --branch=6.3 https://github.com/shopware/production shopware
3
cd shopware
4
​
5
# install shopware and dependencies according to the composer.lock
6
composer install
7
​
8
# setup the environment
9
bin/console system:setup
10
# or create .env yourself, if you need more control
11
# create jwt secret: bin/console system:generate-jwt-secret
12
# create app secret: APP_SECRET=$(bin/console system:generate-app-secret)
13
# create .env
14
​
15
# create database with a basic setup (admin user and storefront sales channel)
16
bin/console system:install --create-database --basic-setup
17
​
18
# or use the interactive installer in the browser: /recovery/install/index.php
Copied!

Update

To update Shopware 6 just run this:
1
# pull newest changes from origin
2
git pull origin
3
​
4
# the (pre|post)-(install|update)-cmd will execute all steps automatically
5
composer install
Copied!

Customization

This project is called production template because it can be used to create project specific configurations. The template provides a basic setup that is equivalent to the official distribution. If you need customization, the workflow could look like this:
    Fork template
    Make customization
    Add dependencies
    Add project specific plugins
    Update var/plugins.json (bin/console bundle:dump, paths need to be relative to the project root)
    Build administration/storefront
    Update composer.json and composer.lock
    Commit changes

Development

Command overview

The following commands and scripts are available
Setup/Install/Deployment
Command
Description
bin/console system:setup
Configure and create .env and optionally create jwt secret
bin/console system:generate-jwt-secret
Generates a new jwt secret
bin/console system:generate-app-secret
Outputs a new app secret. This does not update your .env!
bin/console system:install
Setup database and optional install some basic data
bin/console system:update:prepare
Run update preparations before the update. Do not update if this fails
bin/console system:update:finish
Executes the migrations and finishes the update
bin/console theme:change
Assign theme to a sales channel
Build
Bash is required for the shell scripts.
Command
Description
bin/console theme:compile
Compile all assigned themes
bin/build.sh
Complete build including composer install
bin/build-js.sh
Build administration and storefront, including all plugins in var/plugins.json.
bin/build-administration.sh
Just build the administration.
bin/build-storefront.sh
Just build the storefront. You need to have built the administration once.
Dev
Run bin/build-js.sh once to install the npm dependencies.
Bash is required for the shell scripts.
Command
Description
bin/console theme:refresh
Reload theme.json of active themes
bin/watch-administration.sh
Watcher for administration changes, recompile and reload page if required
bin/watch-storefront.sh
Watcher for storefront changes, recompile and reload page if required

Configuration

See also the README.md in the config folder of the production template.

Template overview

This directory tree should give an overview of the template structure.
1
β”œβ”€β”€ bin/ # binaries to setup, build and run symfony console commands
2
β”œβ”€β”€ composer.json # defines dependencies and setups autoloading
3
β”œβ”€β”€ composer.lock # pins all dependencies to allow for reproducible installs
4
β”œβ”€β”€ config # contains application configuration
5
β”‚ β”œβ”€β”€ bundles.php # defines static symfony bundles - use plugins for dynamic bundles
6
β”‚ β”œβ”€β”€ etc/ # contains the configuration of the docker image
7
β”‚ β”œβ”€β”€ jwt/ # secrets for generating jwt tokens - DO NOT COMMIT these secrets
8
β”‚ β”œβ”€β”€ packages/ # configure packages - see: config/README.md
9
β”‚ β”œβ”€β”€ secrets/ # symfony secrets store - DO NOT COMMIT these secrets
10
β”‚ β”œβ”€β”€ services/ # contains some default overrides
11
β”‚ β”œβ”€β”€ services.xml # just imports the default overrides - this file should not change
12
β”‚ └── services_test.xml # just imports the default overrides for tests
13
β”œβ”€β”€ custom # contains custom files
14
β”‚ β”œβ”€β”€ plugins # store plugins
15
β”‚ β”œβ”€β”€ static-plugins # static project specific plugins
16
β”œβ”€β”€ docker-compose.yml # example docker-compose
17
β”œβ”€β”€ Dockerfile # minimal docker image
18
β”œβ”€β”€ phpunit.xml.dist # phpunit config
19
β”œβ”€β”€ public # should be the web root
20
β”‚ β”œβ”€β”€ index.php # main entrypoint for the web application
21
β”œβ”€β”€ README.md # this file
22
β”œβ”€β”€ src
23
β”‚ β”œβ”€β”€ Command/*
24
β”‚ β”œβ”€β”€ Kernel.php # our kernel extension
25
β”‚ └── TestBootstrap.php # required to run unit tests
26
└── var
27
β”œβ”€β”€ log/ # log dir
28
|── cache/ # cache directory for symfony
29
└── plugins.json # javascript build configuration
Copied!

Managing Dependencies

Composer

You only need to require the things you want. If you only want to run shopware 6 in headless mode, your composer.json could look like this:
1
{
2
"name": "acme/shopware-production",
3
"type": "project",
4
"license": "MIT",
5
"config": {
6
"optimize-autoloader": true
7
},
8
"prefer-stable": true,
9
"minimum-stability": "stable",
10
"autoload": {
11
"psr-4": {
12
"Shopware\\Production\\": "src/"
13
}
14
},
15
"require": {
16
"php": "~7.2",
17
"composer/package-versions-deprecated": "^1.8.0",
18
"shopware/core": "~v6.3.0"
19
}
20
}
Copied!

Require project plugins

If you have project specific plugins, place them under custom/static-plugins/{YourPlugin} and require them in your composer.json.
Note: The plugins needs a (stable) version to work with the default stability stable.
1
composer require "exampleorg/myplugin"
Copied!
External plugins in private repositories can also be required by adding the repository to your composer.json. To learn more about the usage of private repositories, see here:
Repositories - Composer

Update shopware packages

Run the following command, to update all shopware dependencies:
1
composer update "shopware/*"
Copied!

Deployment

Docker

The DOCKERFILE and docker-compose.yml service definitions should work but are still experimental.

Storage and caches

The following directories should be shared by all app servers:
1
.
2
β”œβ”€β”€ config
3
β”‚ β”œβ”€β”€ jwt # ro - should be written on first deployment
4
β”‚ β”œβ”€β”€ secrets # rw shared - see, if you want to use it: https://symfony.com/blog/new-in-symfony-4-4-encrypted-secrets-management
5
β”œβ”€β”€ public
6
β”‚ β”œβ”€β”€ bundles # rw shared - Written by `assets:install` / `theme:compile`, can also be initiated by the administration
7
β”‚ β”œβ”€β”€ media # rw shared
8
β”‚ β”œβ”€β”€ theme # rw shared - generated themes by `theme:compile/change`
9
β”‚ └── thumbnail # rw shared - media thumbnails
10
β”‚ └── sitemap # rw shared - generated sitemaps
11
β”œβ”€β”€ var
12
β”‚ β”œβ”€β”€ cache # rw local - contains the containers, which contains additional cache directories (twig, translations, etc)
13
β”‚ β”œβ”€β”€ log # a - append only, can be change in the monlog config
14
​
15
ro - Readonly after deployment
16
rw shared - read and write access, it should be shared across the app servers
17
rw local - locale read and write access
Copied!
Some of these directories like public can also be changed to different flysystem to host the files on s3 for example.
Last modified 5mo ago