Start Developing

This guide covers what to do once your development environment is running.

Your environment

Once the containers are up, you have:

• Storefront: http://127.0.0.1:8000
• Administration: http://127.0.0.1:8000/admin (default credentials: admin / shopware)

The development terminal user interface (TUI) (shopware-cli project dev) shows these URLs and your credentials at a glance.

Common development areas:

• custom/ - your plugins and themes
• bin/console - application CLI (Symfony console), runnable from your host via shopware-cli project console
• The Administration UI

Running commands

Use shopware-cli project console to run bin/console commands from your host - no need to enter the container:

# Clear caches
shopware-cli project console cache:clear

# Install and activate a plugin
shopware-cli project console plugin:install --activate MyPlugin

# Run database migrations
shopware-cli project console database:migrate --all

For the shorter swx alias, see Running Shopware commands.

Legacy workflow

If your project uses the older make-based setup and you need to shell into the container manually:

make shell
docker compose exec web bash

Most tasks are now easier with shopware-cli project console and the development TUI.

Frontend development

When developing the Administration or Storefront, use watchers for Hot Module Replacement. Start them directly from the DevTUI Overview tab (key 1), or from the command line:

# Administration (Vite HMR on port 5173)
shopware-cli project admin-watch

# Storefront (webpack HMR on port 9998)
shopware-cli project storefront-watch

To only watch specific extensions:

shopware-cli project admin-watch --only-extensions MyPlugin,OtherPlugin
shopware-cli project storefront-watch --only-extensions MyPlugin,OtherPlugin

To exclude specific extensions:

shopware-cli project admin-watch --skip-extensions SomePlugin

For the Storefront Watcher, the CLI prompts you to select a sales channel if one isn't configured.

When working with many third-party extensions, building only custom extensions speeds things up:

shopware-cli project storefront-build --only-custom-static-extensions
shopware-cli project admin-build --only-custom-static-extensions

For more details, see Using Watchers.

Administration setup

When accessing the Administration for the first time:

• Sign in or create a Shopware account (required to install Store extensions)
• Connect to the Shopware Store
• Install plugins or themes from the Store
• Configure payment methods if needed

Basic shop settings (name, language, currency) can be changed later under Settings > Shop > Basic information.

Environment customization

compose.override.yaml

The compose.yaml file is managed by shopware-cli and regenerated automatically. Place all customizations in compose.override.yaml:

# compose.override.yaml
services:
  web:
    environment:
      APP_ENV: dev
    ports:
      - "9003:9003"   # Xdebug

  database:
    ports:
      - "3306:3306"   # Expose MySQL to host

Connecting to a remote database

To use an external database, set DATABASE_URL in .env.local:

DATABASE_URL="mysql://user:password@<host>:3306/<database>"

If the container can't reach localhost, try host.docker.internal or your host's LAN IP.

Environment variables

Create a .env file in the project root to override defaults. Most changes apply immediately. Changes to APP_ENV require a restart (shopware-cli project dev stop && shopware-cli project dev start).

Shopware account and private Composer packages

To install licensed extensions from Shopware's private Composer registry:

composer config --global http-basic.packages.shopware.com <username> <token>

Create an access token in your Shopware account under Shops > Licenses.

Next steps

• Build Extensions - Create plugins, apps, and themes
• Work with APIs - Integrate external systems
• Set up CI/CD - Automate builds and deployments