Installation Using Docker on Windows 10

Expected installation time: less than 1 hour.

This guide covers building new projects based on Shopsys Framework. In case you want to contribute to the framework itself, you need to install the whole shopsys/shopsys monorepo. Take a look at the article about Monorepo for more information.

Supported systems

  • Windows 10 version 2004 and higher

System requirements

  • enabled Virtualization in BIOS

Installation of application requirement

Setup WSL 2 and download Debian


This guide covers installation using Debian distribution. Rest of guide might not be suitable for you, if you decide to select different distribution.

In Windows Subsystem for Linux Installation Guide for Windows 10 follow steps 1 to 5. Select Debian GNU/Linux distribution in step 6.

After installation open Debian application. You will be prompted to create new user.

Install Docker Desktop

Enable WSL 2 and Debian integration in Docker Desktop

  • Open settings of Docker Desktop.
  • Go to General section.
  • Check Expose daemon on tcp://localhost:2375 without TLS option.
  • Check Use the WSL 2 based engine option.
  • Click Apply & Restart button.
  • Go to Resources section and then to WSL INTEGRATION subsection.
  • Check Enable integration with my default WSL distro option.
  • Also turn on Debian under Enable integration with additional distros.
  • Click Apply & Restart button.

Install dependencies, Docker and docker-compose in Debian

We have prepared installation script for Debian dependencies in order to speed up the installation process. In Debian application run these commands: * sudo apt update * sudo apt install -y --no-install-recommends wget * wget --no-check-certificate * sudo bash * You can delete the downloaded file at the end of installation using rm command. * To ensure everything is working alright, restart Docker Desktop and Debian applications.


If you prefer to know more about what is happening during installation, open script and run all commands manually.

Installation of Shopsys Framework

1. Create new project from Shopsys Framework sources

Open Debian application.

Change your current directory to your home directory (/home/<your-linux-user-name>/)

cd ~/

Install project with composer

composer create-project shopsys/project-base --no-install --keep-vcs
cd project-base


Now you can access your project files directly from Windows Explorer under this address \\wsl$\Debian\home\<your-linux-user-name>\project-base\


  • The --no-install option disables installation of the vendors - this will be done later in the Docker container
  • The --keep-vcs option initializes GIT repository in your project folder that is needed for diff commands of the application build and keeps the GIT history of shopsys/project-base

2. Installation

Now, you have two options:

Option 1

In the case you want to start demo of the application as fast as possible, you can simply execute the installation script and that is all:


Select Linux or Windows with WSL 2 from list of operating systems as you are installing it in Debian.

After the script is finished with installing the application, you can skip all the other steps and see the last chapter of Application Setup Guide to get all the important information you might need right after the installation.

Option 2

If you prefer to know more about what is happening during installation, continue with the steps #2.1 - #2.3.

2.1 Create docker-compose.yml and docker-sync.yml file

Create docker-compose.yml from template docker-compose.yml.dist.

cp docker/conf/docker-compose.yml.dist docker-compose.yml

2.2. Compose Docker container

You need to create a directory for persisting vendor, PostgreSQL and Elasticsearch data so you won't lose them when the container is shut down.

mkdir -p vendor var/postgres-data var/elasticsearch-data

Then rebuild and start containers

docker-compose up -d


During installation there will be installed 3-rd party software as dependencies of Shopsys Framework by Dockerfile with licenses that are described in document Open Source License Acknowledgements and Third-Party Copyrights

2.3 Setup the application

Application setup guide