---
title: >-
  Options for Setting up a local Development Environment | Shopware Community
  Hub
description: >-
  Comprehensive guide to configuring local development environments for
  Shopware, including Docker-based solutions and virtual machine setups
canonical_url: 'https://hub.shopware.com/learn/unit/solutions-architect-local-environments'
---

# Options for Setting up a local Development Environment

<LearningObjectives>

- Learn the different options for setting up a **local development environment** for Shopware.
- Understand the **key differences** between each setup method and when to use them.
- Be able to **evaluate and choose** an appropriate local development setup based on project and team requirements.

</LearningObjectives>

# Options for Setting up a local Development Environment

Shopware can run in different local development environments, but not all of them are equally relevant today. The
current recommended default is the Docker-based setup, which is now closely aligned with the Shopware CLI workflow.
Older installation approaches should be treated as legacy options for existing projects or migration scenarios.

## **1. Docker with Shopware CLI (Recommended)**

**Brief Steps**:

1. Install Docker on your machine
2. Create an empty project directory
3. Run the Shopware Docker setup to create the project
4. Start the containers with `make up`
5. Complete the installation with `make setup`

**Key Features**:

- Recommended by Shopware for new development projects
- Provides a consistent, production-like environment
- Includes the Shopware CLI in the setup workflow
- Ships with common development tooling and services inside the Docker stack
- Reduces local dependency issues because PHP, Composer, database, and supporting services run in containers

**Key Differences**:

- Uses containers instead of installing dependencies directly on the host
- Standardizes onboarding across teams and operating systems
- Makes it easier to align local development with CI/CD and modern Shopware workflows
- Requires Docker knowledge, but avoids much of the manual host setup work

**Documentation**: [Install Shopware with Docker](https://developer.shopware.com/docs/guides/installation/setups/docker.html).

## **2. Dockware**

Dockware is also Docker-based, but it serves a different purpose than the official Shopware Docker setup. While the
recommended Docker workflow is meant to create and run a regular development project, Dockware focuses on providing
ready-made Shopware environments for quick starts, demos, version testing, or temporary debugging scenarios.

**Brief Steps**:

1. Pull a pre-built Shopware image from Dockware using `docker pull dockware/flex`.
2. Start the container with `docker run` and map local ports.  
   Example of port mapping in docker-compose.yaml:

    ```yaml
    ports:
      - "22:22"     # ssh
      - "80:80"     # apache2
      - "443:443"   # apache2 https
      - "3306:3306" # mysql port
      - "8888:8888" # watch admin
      - "9998:9998" # watch storefront proxy
      - "9999:9999" # watch storefront
    ```

3. Access the Shopware instance via the container's IP or configured domain.

**Key Features**:

- Offers pre-built Docker containers with different Shopware configurations (e.g., dev, prod, debug).
- Includes features like Xdebug for debugging and MailHog for email testing.
- Ideal for quick setups or testing specific Shopware versions.

**Key Differences**:

- Faster initial setup compared to Devenv or VirtualBox, as it uses pre-built images.
- It includes debugging tools like Xdebug, which is out of the box.
- Dockware is based on Docker and offers similar flexibility to modify PHP configuration, Apache settings, and add additional packages as needed.

**Documentation**: [Dockware Setup Guide](https://dockware.io/#play).

## **3. Legacy Setups**

Some older local development workflows are still documented for reference, but they are no longer the preferred
starting point for new projects.

**When they may still appear**:

- Long-lived projects with an established setup
- Teams that have not yet migrated to the current Docker workflow
- Transitional migration scenarios

**Important context**:

- Legacy setups may receive less attention than the current Docker-based workflow
- They are useful mainly for compatibility or migration, not as the default recommendation
- Older VM-based approaches such as VirtualBox should be considered outdated in this context

**Documentation**: [Legacy Setups](https://developer.shopware.com/docs/guides/installation/legacy-setups/).

## Choosing the Right Option

While multiple local setups exist, they do not have the same strategic relevance anymore.

- **Docker with Shopware CLI**: Best default choice for new projects and modern team workflows.
- **Dockware**: Useful for quick setups, demos, or testing specific Shopware versions with prebuilt containers.
- **Legacy Setups**: Only choose these when maintaining an older workflow or handling a migration scenario.

In practice, the first question is no longer "Which setup is possible?" but rather "Do we have a reason not to use the
recommended Docker workflow?" If the answer is no, Docker should be your default starting point.