Understanding Your Shopware Project

You have just installed Shopware, and this section guides you through the fundamentals you will use throughout the rest of your development workflow.

Development tooling

The Docker setup provisions Shopware for development. The recommended way to manage your environment is through the Development Environment TUI, available via shopware-cli project dev. It provides:

• One-command start/stop of the entire stack
• Real-time log streaming from var/log/ and Docker containers
• Admin and Storefront Watchers (HMR)
• PHP version and profiler configuration (xdebug, blackfire, tideways, etc.)
• Service discovery (Adminer, Mailpit, queue, etc.)

Development tools such as:

• shopware/dev-tools
• Symfony profiler (only in development mode)
• linting and testing tools

are managed via the Shopware CLI. These are installed into the user's environment and shared across projects and extensions, rather than being added as project-level require-dev dependencies.

Demo data is optional. For developer setups, prefer terminal-based setup and development workflows instead of the in-browser First Run Wizard.

Your local project is ready for debugging, profiling, and extension development out of the box.

In day-to-day development, you'll mostly interact with:

• shopware-cli project dev: starts and manages the Docker-based development environment, including containers, logs, watchers, credentials, and service URLs.
• shopware-cli project console <command>: runs Shopware application commands from your host without opening an interactive container shell.
• swx <command>: shortcut for shopware-cli project console <command>, for example swx cache:clear.
• custom/: where you build your own plugins and themes.

bin/console is the application CLI that ships with Shopware (Symfony console). Use it for Shopware application commands such as migrations, plugin installation, cache clearing, or configuration changes. In Docker-based setups, run those commands through shopware-cli project console or swx so they execute in the correct container context.

The standalone Shopware CLI is different from bin/console: it manages project workflows such as the development environment, helper commands, extension builds, and CI workflows.

Project template

All setups start from the Shopware Project Template - a Composer-based project that installs Shopware as a dependency. It serves as the foundation for new Shopware projects and for developing plugins, apps, or themes. This allows you to:

• Extend the project with plugins, apps, or themes
• Customize configuration and services
• Tailor the environment to your development needs

Components

The following table explains the Docker-level components created when you start the project. Container names depend on the name of your project folder.

Name	Type	Purpose
Network my-project_default	Docker network	A private virtual network so all containers can communicate (for example, the web container connects to the database).
Volume my-project_db-data	Persistent storage	Stores the MariaDB database files so your data isn't lost when containers are stopped or rebuilt.
Container my-project-mailer-1	Mailpit service	Captures outgoing emails for local testing. View at http://localhost:8025.
Container my-project-database-1	MariaDB service	Runs the Shopware database. Inside the Docker network, its hostname is database.
Container my-project-web-1	PHP + Caddy web service	Runs Shopware itself and serves the Storefront and Admin UI at http://localhost:8000.
Container my-project-adminer-1	Adminer (DB UI)	Lightweight web interface for viewing and editing your database. Available at http://localhost:8080.

Project structure

After installation, your Shopware project contains the following root-level directories and files:

project-root/
├── bin/
├── config/
├── custom/
│   ├── plugins/
│   ├── apps/
│   └── static-plugins/
├── files/
├── public/
├── src/
├── var/
├── vendor/
├── compose.yaml
├── compose.override.yaml
├── composer.json
├── composer.lock
├── symfony.lock
├── Makefile
├── .env
└── README.md

This table outlines the key directories and files in your Shopware project and their uses.

Item	Type	Purpose / what it contains	Notes
bin/	Directory	Executable scripts (e.g., bin/console - the main CLI for Shopware/Symfony).	Think of it like npm run or go run scripts. Use bin/console to run commands inside the app.
compose.yaml	Docker	Defines the Docker services (web, database, mailpit, etc.).	Equivalent to your project's "infrastructure recipe."
compose.override.yaml	Docker	Local overrides for the default Docker Compose stack (e.g., port mappings, extra volumes).	Optional; used to customize or extend services locally.
composer.json	PHP dependency manifest	Lists PHP dependencies and metadata (like package.json).	composer install reads this.
composer.lock	Dependency lock file	Locks exact versions of PHP packages.	Don't edit manually; committed to git.
config/	Directory	Symfony configuration files (framework, database, mail, etc.).	Similar to config/ in many web frameworks.
custom/	Directory	Your plugins, themes, or app customizations.	This is where you add new extensions - your "src" for Shopware plugins.
files/	Directory	Uploaded media and temporary files.	Ignored by git; generated at runtime.
Makefile	Legacy build helper	May exist in older setups with shortcuts for Docker tasks (make up, make setup, etc.).	Replaces long Docker commands with memorable aliases.
public/	Web root	The actual web-server-accessible directory (contains index.php, assets, etc.).	Like /dist in JS frameworks or /public_html.
src/	Source code	Shopware's core application source.	Where the main PHP codebase lives; not usually edited in a project clone.
symfony.lock	Symfony dependency snapshot	Records Symfony recipes applied during setup.	Used internally by Symfony Flex; no manual editing.
var/	Runtime data	Cache, logs, temporary files.	Can safely be deleted (Shopware rebuilds it).
vendor/	Dependency code	All installed PHP libraries from Composer.	Analogous to node_modules/.

Now, continue to the next section to start implementing your changes.