Setting Up a Local Environment with Virtual Box

Introduction

This article will show you how to set up a virtual machine for a local Shopware 6 environment in development mode. Some of you might stumbled upon the restrictions of Shopware when it comes to Windows as operating system. Everyone that might have tried to get shopware working on Windows might know, that it is more likely to fail than to succeed. It is important to use a Unix-based system (like Linux or MacOS) as environment for a local setup. Surely not everyone is that familiar with Linux or has an Apple product to work with. This guide will help you to set up a Linux virtual machine on your local operating system regardless with OS you are currently using.

First of all you will need a local installation of Virtual Box from Oracle. Just download it from https://www.oracle.com/de/index.html and start the installation process. The main reason for a virtual box image is, that you can use it independently on every operating system you are using - even if you change e.g. from Windows to MacOS in the future. Since the settings are saved inside the virtual image, a re-installation of your laptop will keep the configuration and you are ready to go in a few steps after the installation of virtual box.

Downloading Ubuntu

This guide will focus on Ubuntu and use it as a foundation for the setup. Ubuntu is a well known and documented Linux distribution and might be the best choice for beginners. Since we won’t need the whole Desktop-Manager version of Ubuntu, just grab the network installer image from their site: https://ubuntu.com/download/alternative-downloads

Just wait until the download finishes and we will start with the configuration of the virtual box.
 

Creating a Virtual Box Image

First of all, you need to start your newly installed Virtual Box. Just create a new virtual machine by using the „new“ button on the right side of the new menu or use the top menu (Machine -> New).

Further you need to define what operating system you want to virtualize and have to Select „Type: Linux“ and „Version: Ubuntu“ in the sub-menu. Feel free to choose any name you want for the newly created virtual box image.
You can confirm your selection with „continue“.
The next context menu will ask you about the preferred memory size, we recommend using 2GB or more for your environment, but it highly depends on your available resources on your computer (e.g. if you have only 4gb of RAM, you won’t be able to add more than 2GB to the virtual machine). In our case we will use „2048MB“ as selection. Confirm to go to the next step.
Now you need to define your hard disk for the virtual machine - just keep the selection at „Create a virtual hard disk now“ and use the „create“ button to confirm this.

Inside this new sub-menu you can keep the selection at „VDI (VirtualBox Disk Image“) and go on with continue. The new image should be „Dynamically Allocated“ in our case and 15-20GB should be enough for the local environment. The steps will show you comprehensive information on what to do. After you have finished the configuration of your VM, you will be back at the start screen from above.

Before we will start our newly created virtual box, we need to do some additional configuration. Just select the newly created VM and open the „Settings“ menu. Change to the „Network“ configuration and open the hidden „advanced“ configuration. In this section you will find the „Port Forwarding“ - just click this button for a new sub-menu.

Add the configuration from the screenshot in order to make your VM available from your local computer on localhost. If you need to change this ports, please keep those changes in mind, because we need them later on. Often there are already services listening to port 22 and 80 on your local computer, so we changed the host ports to unused ones. Confirm your selection and close the sub-menues.

Environment Setup

Ubuntu Setup

Just start your newly created virtual machine in the main menu of virtual box. Since the virtual environment is empty for now, you will need to add your downloaded iso file of Ubuntu in the menu. Just select it from your hard drive and hit the start button.
The system will boot from your Ubuntu ISO and will show the boot loader with some possible selections. Start the standard installation in this case.
The Ubuntu installer will start and you are asked for your preferred language and region. After you confirm your selection the system will try to guess your keyboard layout, this can be done automatically or by choosing the right one. Either way you will use, make sure that you choose the right one. After this basic system configuration is done, the installer will establish a connection to the Ubuntu servers to download the needed packages for the installation. You will be prompted to define hostname (feel free to choose any) and a mirror (just select the pre-defined one). When using a proxy for your internet connection you can configure it as well, but in most cases you won’t need to do anything.

The next step will be the setup of the user name and password. In our case we will select „shopware“ as username and „shopware“ as password, but you are free to define a different one - but please make sure, that you will remember it. The time zone will be detected afterwards, you only need to change this, if it really differs from your current time zone.

Just choose the guided partitioning of the hard drive in the next menu and go on with the installation and write your changes to the disk. The basic installation of the software will take place. Since most of the packages will be downloaded from the Ubuntu mirrors, this will take a while depending on your internet connection. Feel free to install security updates automatically in the next step. Further on we will be asked for additional software that might needs to be installed. From this new menu choose „LAMP Server“ (Apache, MySQL, PHP) and „OpenSSH server“ (the selection can be done by hitting the space bar). The process will install the newly choosen software and the bootloader (you may need to confirm this too). Finish the installation and we are ready to do some additional configuration of the system.
 

Ubuntu Configuration

Remove the Ubuntu ISO from the VM (by clicking the small CD-ROM symbol at the bottom of the VM window) and shut down your newly created virtual image. Start it again while holding the „Shift“-key. This will start the VM in the background and we are able to access it via SSH. On most environments this is possible via a terminal with the command „ssh shopware@127.0.0.1 -p2222“. Please make sure to add your newly created user instead of „shopware“ if it differs. On Windows environments software like Putty is used for SSH connections, but you can use the VM window too, if you don’t want to use an additional software.

First of all, you can check your installation. Just open 127.0.0.1:8080 (keep in mind,  that you might have changed this port) - an Apache test page should be visible in your browser. Inside the terminal you can verify the installation of PHP by using „php -v“ and it will show you the used PHP version (it should be 7.2 at least).

We will need to set a password for MySQL - you can do this with the following commands:

sudo mysql
ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'root';
FLUSH PRIVILEGES;
exit

 

In our case we will set the password of the user „root“ to „root“. You may want to change this, but keep in mind to remember this password at a later time.
 

Installation of dependencies

In order to use Shopware, you will need to install some additional dependencies on your local machine. This can be done by the following commands:

sudo apt-get install php-intl php-xml php-zip php-apcu php-mbstring php-json php-gd unzip nodejs openssh-server git php-curl curl npm

After the installation make sure, that you use a current version of npm by ececuting this:
 

sudo npm install -g npm@latest

Installation of Virtual Box guest additions

For a smooth integration of virtual box on your computer, we recommend adding the guest additions to your virtual machine. Just open your virtual machine (button „show“ in the virtual box main menu) and add it via the conext menu Devices -> Insert Guest Additions CD Image. After the image is inserted, you need to mount it and start the installation:

sudo mount /dev/cdrom /mnt
cd /mnt
sudo ./VBoxLinuxAdditions.run
sudo reboot

You might have to establish the SSH connection again after rebooting.
 

Configuration of Apache

First of all you need to activate mod-rewrite, this can be done by executing the following command in your vitual machine:

sudo a2enmod rewrite

After this you will need to add a new vhost-configuration, just disable the existing one:

sudo a2dissite 000-default.conf

And at last you need to create a new configuration:

sudo nano /etc/apache2/sites-enabled/sw6.conf

Just add the following configuration to the editor:

<VirtualHost *:80>
        <Directory "/var/www/html/sw6/public">
            Options FollowSymLinks
            AllowOverride All

            Order allow,deny
            Allow from all
        </Directory>

        ServerAdmin webmaster@localhost
        DocumentRoot /var/www/html/sw6/public

        ErrorLog ${APACHE_LOG_DIR}/error.log
        CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

With CTRL + O you can save it and with CTRL + X you can leave the editor. Afterwards you need to restart the webserver:

sudo service apache2 restart

Since Linux is a system that is really strict with right- and permission management, we need to add the user "shopware" to the "www-data" group, in order to prevent issues with the permissions:

sudo usermod -g www-data shopware
sudo chown -R www-data:www-data /var/www/
sudo chmod 0777 -R /var/www/html
sudo reboot

You might need to restart the SSH connection after rebooting the VM.

Installation of Composer

Just keep in mind, that the verification of the installer might change, so you need to use the commands from the Composer website to make sure: https://getcomposer.org/download/
 

For Example:

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('sha384', 'composer-setup.php') === '756890a4488ce9024fc62c56153228907f1545c228516cbf63f885e036d37e9a59d27d63f46af1d4d07ee0f76181c7d3') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
php composer-setup.php
php -r "unlink('composer-setup.php');"

After you have downloaded Composer sucessfully, you need to make it executable via the command „composer“, just copy it to the /bin folder:

sudo mv composer.phar /bin/composer

You can verify your installation by running „composer“ in your terminal.

Installation of Shopware 6 development environment

Shopware 6 comes in two different versions. There is an official release-package for production systems, that won’t provide you any development tooling (e.g. for building plugin assets) and there is the GitHub repository that will be your development environment. Change the directory to the web folder and download shopware 6 from github:

cd /var/www/html
git clone https://github.com/shopware/development.git sw6

In order to start the installation, you can simply execute the following commands, a wizard will guide you through the installation of Shopware.

cd sw6
php bin/setup

You will be asked for your environment (select „dev“), your public url (in our case http://127.0.0.1:8080, the port may differ according to your configuration), your database (keep localhost, shopware as database name and root/root as user/password).

After you confirm your environment parameters, the installation will take place. It will take 37 steps to finish this installation, so you might have to wait a bit. The Composer dependencies will be downloaded at first. 
For the next installation they will be taken from cache, this will speed up the installation quite a bit. When the installation is finished, you can access the installation via your browser on your local environment: http://127.0.0.1:8080. The administration is accessible with /admin and the user/password combination of admin/shopware.

Optional configuration

Reset installation

Since the master branch of Shopware 6 is updated frequently, you may want to reset your installation. This can be easily done by deleting the folder and cloning the repository once again. But you may want to have a script for that, here is an example:

nano /sw6.sh

Add the following content to it:
 

#!/bin/bash
sudo mv /var/www/html/sw6/.psh.yaml.override /var/www/html/.psh.yaml.override
sudo rm -R /var/www/html/sw6
cd /var/www/html
git clone -b master https://github.com/shopware/development.git sw6
cp /var/www/html/.psh.yaml.override /var/www/html/sw6/.psh.yaml.override
cd /var/www/html/sw6
composer install
php psh.phar install

Now you can re-install your whole installation by just executing the newly created script. Just make it executable and move it to the /bin folder:

sudo chmod +x sw6.sh
sudo mv sw6.sh /bin/sw6

Updating the master branch

In some cases you might want to keep your settings and database and just get the newest files from Github. This can be achieved by the following commands inside the Shopware 6 folder:
 

git pull
composer update
php bin/console database:migrate
php bin/console database:migrate --all Storefront
php bin/console cache:clear
php psh.phar storefront:build
php psh.phar administration:build

 
Feel free to create a script from it like the one we created above.
 

Installation of a Release-Tag

Since we already have a released version of Shopware 6 available on our download page, you might want to install this exact version instead the current master branch. You can achieve this by adding a specific parameter that points to the tag:
 

git clone --branch v6.0.0+ea1 https://github.com/shopware/development.git

 

PHPStorm configuration

You can use this setup as development environment, so you surely want to configure PHPStorm accordingly. When creating a new project in PHPStorm you can choose the option "Create new project from existing files" from the sub menu. Just choose "Web server is on remote host, files are accessible via FTP/SFTP/FTPS".
 
When going to the next step you need to add a project name and a local folder (feel free to choose anything).
In the next window you need to add your SSH/SFTP configuration of the virtual environment.
 
Just finish the wizard afterwards without any further configuration and the download of your project files will start. This may take a while. After the download, you are able to use this connection to develop locally on e.g. on Windows and upload your changes to the Linux virtual environment.
   

Visual Studio Code configuration

Visual Studio Code might be a good alternative to PHPStorm, when it comes to license costs, since it is completely free. You can add a remote host too, but you will need the "Visual Studio Code Remote Development Extension Pack" from the extension list. Just open the extension list from the left panel and search for this extension and install it. A restart may be required. After rebooting a whole new menu will appear on the left of the Visual Studio Code menu.

Create a new ssh configuration:

Host 127.0.0.1
    HostName 127.0.0.1
    User shopware
    Port 2222

At first you may be promted with a new input field for the password while trying to connect:

Afterwards you can use the terminal and the file editor of Visual Studio Code to access your Shopware 6 installation and start development.
 

Download the VM 

We highly recommend creating your own VM in order to learn about the difficulties and challenges while using Linux, but we do offer you a ready to use VM that will be updated frequently: shopware-vm.ova

Just use the import dialog of Virtual Box, all settings will be imported.
 
Shopware 6:

• Frontend: 127.0.0.1:8080
• Administration; 127.0.0.1:8080/admin
• Admin Username/Password: admin/shopware
   

Virtual Machine:

• SSH-Host/Port: 127.0.0.1 / Port 2222
• SSH Username/Password: shopware/shopware
• Database Username/Password: root/root

Please note, that there is already an installation inside this VM, if you want to make sure that it is the current master, please execute the command "sw6" inside the VM the check out the newest version.

As one step of the installation process we set up a network share that you can access directly from your local computer without using any SSH/SFTP connection. This is also part of the VM. In the next steps we will show you how to use it on your local computer.

 

MacOS network share

Open the Finder and go the the "Go" menu at the top. Open to "connect to server". Add your network share adress and port to the new window:

smb://127.0.0.1:4455/VM

  To finish the set up of the local network share, just hit "connect" on this menu. The Finder will establish a connection to the network share and you can use those files as a local folder:
 

Windows network share

Unfortunately it is not possible under Windows to map a network drive to a share in the VM under the IP 127.0.0.1. For this a few adjustments are necessary

Network adapter in Virtual Box
First change the network adapter from NAT to Bridged Adapter in the Virtual Box Manager for the Shopware VM
(It is necessary that the VM is switched off at this time)
At Settings > Network > Adapter 1 > Attached to: select Bridged Adapter

This assigns a new, own IP address to the VM through the DHCP server in the network.
(If no DHCP server is available in the network, it is necessary to manually assign an IP to the VM.)

Find out the IP assigned by DHCP
This is possible, for example, via the console displayed in the window of the VM.
To do this, type ifconfig in the console and the IP settings will be listed.
(net-tools is required for this. This is included in the prepared VM, if you have your own system you may have to install it.)

Now the connection via SSH is possible via the IP of the VM and Port 22

Customize settings in Shopware
First call the admin via http://IPoftheVM/admin
Now it is necessary to adjust the URL for the sales channel "Storefront" in the section "Domains" to http://IPoftheVM
After you have saved the URL change, you can directly call the frontend via IPoftheVM
 
Mapping the network drive
It is now possible to mount the network drive in Windows.
To do this, proceed as follows

Open "This PC" and in the tab "Computer" click on "Map network drive"
 

In the new window choose a drive letter and enter as folder "\\IPoftheVM\VM" and also check "Connect using different credentials"
Optional you can also check "Reconnect at sign-in"

When you click on the Finish button, a window to enter the credentials is shown.
As user enter "ubuntu/shopware" and as password "shopware".
(if the connection is to be re-established when logging on, it is recommended to save the login credentials)


 

After confirming via the OK button, the connection is now established and the network drive is connected.