Installation Using Docker for Windows 10 Pro and higher¶
Expected installation time: 3 hours.
This guide covers building new projects based on Shopsys Framework. If 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.
This solution uses docker-sync (for relatively fast two-way synchronization of the application files between the host machine and Docker volume).
Warning
Docker-sync might be a burden for intensive project development, especially when there is a huge amount of files in shared volumes of virtualized docker and when switching between branches or even between projects often. In such a case, you should consider using native installation.
Supported systems¶
- Windows 10 Pro
- Windows 10 Enterprise
- Windows 10 Education
Requirements¶
- GIT
- PHP
- At least version 7.1 or higher
- Docker for Windows
- Docker for Windows requires at least 4 GB of memory, otherwise,
composer install
can result inKilled
status (we recommend to set 2 GB RAM, 1 CPU and 2 GB Swap inDocker -> Preferences… -> Advanced
) - Version of Docker Engine should be at least 17.05 or higher so it supports multi-stage builds.
- Version of Docker Compose should be at least 1.17.0 or higher because we use compose file version
3.4
- Docker for Windows requires at least 4 GB of memory, otherwise,
- Docker-sync (installation guide see below)
Installation of Docker-sync for Windows¶
Warning
Be aware of using custom firewalls or protection tools other than default Windows Defender
, we experienced that some of them make synchronization malfunctioning because of blocking synchronization ports.
To speed up the synchronization and developing faster, you can exclude folder from indexing and search path of Windows Defender
.
Prerequisites¶
In settings of Windows docker check Expose daemon on localhost:2375
in General
tab and check drive option in Shared Drives
tab, where the project will be installed, you will be prompted for your Windows credentials.
Enable WSL¶
Open the Windows Control Panel
, Programs and Features
, click on the left on Turn Windows features on or off
and check Windows Subsystem for Linux
near the bottom, restart of Windows is required.
Install Debian app¶
Install Debian
app form Microsoft Store
and launch it, so console window is opened.
Execute following commands in console window.¶
Update linux packages so system will be up to date to install packages needed for running docker-sync.
sudo apt update
Now install the tools needed for adding package repositories from which the system will be able to download docker, docker-sync and unison synchronization strategy driver.
sudo apt install -y --no-install-recommends apt-transport-https ca-certificates curl gnupg2 software-properties-common
Add repository for docker, then install it and configure environment variable for connecting to Windows docker.
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -
sudo apt-key fingerprint 0EBFCD88
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable"
sudo apt update
sudo apt install -y --no-install-recommends docker-ce
echo "export DOCKER_HOST=tcp://127.0.0.1:2375" >> ~/.bashrc && source ~/.bashrc
Install docker-compose tool that will help us to launch containers via docker-compose.yml
configuration file.
sudo curl -L "https://github.com/docker/compose/releases/download/1.25.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
Install ruby as installation tool for docker-sync in specific version for working unison synchronization strategy driver.
sudo apt install -y --no-install-recommends ruby ruby-dev
sudo gem install docker-sync -v 0.5.7
Download, compile and install OCaml.
sudo apt install -y --no-install-recommends build-essential make wget git
wget http://caml.inria.fr/pub/distrib/ocaml-4.08/ocaml-4.08.1.tar.gz
tar xvf ocaml-4.08.1.tar.gz
cd ocaml-4.08.1
./configure
make world opt
umask 022
sudo make install clean
Download, compile and install Unison.
wget https://github.com/bcpierce00/unison/archive/v2.51.2.tar.gz
tar xvf v2.51.2.tar.gz
cd unison-2.51.2
# The implementation src/system.ml does not match the interface system.cmi:curl and needs to be patched
curl https://github.com/bcpierce00/unison/commit/23fa1292.diff?full_index=1 -o patch.diff
git apply patch.diff
make UISTYLE=text
sudo cp src/unison /usr/local/bin/unison
sudo cp src/unison-fsmonitor /usr/local/bin/unison-fsmonitor
Remove sources of sync tools
cd ../..
rm -rf ocaml-4.08.1 *.tar.gz
Set timezone of the system as docker-sync requirement.
sudo dpkg-reconfigure tzdata
Set WSL init script for mounting of computer drives from root path /
instead of /mnt
path.
echo -e [automount]\\nenabled = true\\nroot = /\\noptions = \"metadata,umask=22,fmask=11\" | sudo dd of=/etc/wsl.conf
Add valid Debian repository for php version that is used by composer and install composer.
sudo wget -O /etc/apt/trusted.gpg.d/php.gpg https://packages.sury.org/php/apt.gpg
echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/php.list
sudo apt update
sudo apt install -y --no-install-recommends composer
Close console window and open it again so the new configuration is loaded.
Note
Sometimes something may not work correctly, so we highly recommend you do restart system and continue by guide
Shopsys Framework Installation¶
1. Create new project from Shopsys Framework sources¶
After WSL installation use linux console for each command.
Pick path of some directory in Windows filesystem and move into it, for example documents of windows user myuser
so path will be like this.
cd /c/Users/myuser/Documents/
Install project with composer.
composer create-project shopsys/project-base --no-install --keep-vcs
cd project-base
Notes
- 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 ofshopsys/project-base
2.1 Use install script¶
In case you want to start demo of the app as fast as possible, you can now execute install script.
./scripts/install.sh
If you want to know more about what is happening during installation, continue with next step.
2.2 Create docker-compose.yml and docker-sync.yml file¶
Create docker-compose.yml
from template docker-compose-win.yml.dist
.
cp docker/conf/docker-compose-win.yml.dist docker-compose.yml
Create docker-sync.yml
from template docker-sync-win.yml.dist
.
cp docker/conf/docker-sync-win.yml.dist docker-sync.yml
3. Compose Docker container¶
On Windows you need to synchronize folders using docker-sync. Before starting synchronization you need to create a directory for persisting Vendor data so you won't lose it when the container is shut down.
mkdir -p vendor
docker-sync start
Then rebuild and start containers
docker-compose up -d
Note
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