Table of contents

• Overview
• Getting started
  • Dependencies
  • Quick start
• SDK
  • Usage
    • Testing library
    • Module skeleton generator
• How to update the VM
• Configuration
  • Shared Folder
  • Setting up Varnish
    • Trigger Varnish installation
    • Download and install composer package
    • Adapt servers_conf.vcl
    • Restart Varnish service
    • Update OXID eShop config.inc.php
    • Update OXID eShop admin settings
  • More configuration options

Overview

This project extends the Base VM and is optimized for specific versions of the OXID eShop.

Final solution is composed of two repositories (linked using git sub-modules):

• Base VM - Base LAMP stack
• eShop VM - Current repository, eShop specific configuration and roles.

Getting started

Before proceeding with Quick start please ensure that the Dependencies listed below are installed.

Dependencies

• Vagrant (>=1.8.6)
• VirtualBox [1] (>=4.2, except 5.1.8, see #29; Windows users see #32)
• Git
• OpenSSH (Only client part is needed)
• Vagrant plugins:
  • vagrant plugin install vagrant-hostmanager vagrant-triggers
  • vagrant plugin install vagrant-lxc (If LXC will be used for provision process.)
  • vagrant plugin install vagrant-parallels (If Parallels will be used for provision process.)

[1]	VirtualBox is listed as dependency due to the fact that it is the default chosen provider for the VM. In case other providers will be used there is no need to install VirtualBox. Please refer to the list of possible providers in the configuration section to get more information.

Quick start

Notice: For OXID eShop Professional Edition or OXID eShop Enterprise Edition, you need to enter the credentials you should have received when purchasing the product.

Note for Windows users: Use console with Administrator privileges to run vagrant commands!

• Clone [2] out current repository:

git clone -b b-6.1 --recursive https://github.com/OXID-eSales/oxvm_eshop.git

• Start the VM [3]:

cd oxvm_eshop
vagrant up
vagrant ssh
# for the Community Edition
composer create-project oxid-esales/oxideshop-project /var/www/oxideshop dev-b-6.1-ce
# for the Professional Edition
composer create-project oxid-esales/oxideshop-project /var/www/oxideshop dev-b-6.1-pe
# for the Enterprise Edition
composer create-project oxid-esales/oxideshop-project /var/www/oxideshop dev-b-6.1-ee

• Set up your shop via http://www.oxideshop.local/Setup
  • Database Name, User and Password: oxid
  • Keep track of the admin Email and Password you define
• After successful installation and setup use the following links to:
  • Open OXID eShop: http://www.oxideshop.local/
  • Access admin area: http://www.oxideshop.local/admin/
    • Username: Defined during the setup
    • Password: Defined during the setup

[2]	Since the current eShop VM repository is linked through git sub-modules it is mandatory to use --recursive option to instruct git and clone base VM repository as well.

[3]	You may skip the development requirements with "composer create-project --no-dev [...]", if you don't need to work on the source code.

SDK

• Out of the box the VM is equipped with the Testing library - a library for writing various kind of tests inside eShop and a set of tools for running those tests. It will not be installed if you use the --no-dev option for composer.
• Also you can easily install the Module skeleton generator - module which helps to create new OXID eShop modules within the VM (remember to vagrant ssh).

composer require oxid-esales/module-generator:v6.x-dev -d /var/www/oxideshop

Usage

Testing library

This library is needed for various testing purposes. It is already installed in the VM through the help of composer, because it's defined in composer.json as development requirement inside OXID eShop.

All binary tools are installed inside /var/www/oxideshop/vendor/oxid-esales/testing-library/bin.

A list of available binary tools:

• reset-shop - restore eShop's database to it's default state (demo);
• runmetrics - run pdepend against eShop and modules code to collect various code metrics information;
• runtests - run unit/integartion tests against eShop and modules code;
• runtests-coverage - generate coverage report by running unit/integration tests;
• runtests-selenium - run acceptance tests written for Selenium.

More details on how to use and configure the library can be found at: https://github.com/OXID-eSales/testing_library

Module skeleton generator

The module needs to be activated manually. Further instructions on how to enable and use the module can be found at (installation part can be skipped): https://github.com/OXID-eSales/module_skeleton_generator#usage

How to update the VM

• Open VM directory:

cd oxvm_eshop

• Destroy old VM:

vagrant destroy

• Update eShop VM:

git pull

• Update Base VM:

git submodule update --recursive

• Start VM:

vagrant up

Configuration

The default virtual environment configuration ensures the shop will run out of the box. However, it is possible to adjust the configuration of the virtual environment to better match individual preferences.

All configuration changes should be done by overriding variables from:

• default.yml - base vm variables;
• oxideshop.yml - eShop specific variables.

These overridden values must be placed in personal.yml [4] file at the root level of current repository.

For the overridden values to take effect please run vagrant provision. If the changes are related to the shared folder use vagrant reload. In case the provision process will start to show any kind of errors, please try to use vagrant destroy && vagrant up for the process to start over from a clean state.

To double check the merged version of configuration just run vagrant config.

Hint: you have to care for the syntax/semantics for yourself. So, if you get an error while vagrant provision your personal.yml is the start point for troubleshooting. Hint: Check if every entry has a value. At the moment no empty entries will work.

[4]	personal.yml configuration file is already included in .gitignore and should not be visible as changes to the actual repository.

Shared Folder

The shared folder will be created at the first run of vagrant up and will reside within the VM folder at oxideshop, within the guest machine this directory is located at /var/www/oxideshop.

---
vagrant_local:
  vm:
    app_shared_folder:
      source: oxideshop
      target: /var/www/oxideshop

For composer create-project the target folder has to be empty, so if you need to do another installation remember to either delete its contents or better do a vagrant destroy

Setting up Varnish

Notice: Varnish integration is a feature of the Enterprise Edition (EE) of the OXID eShop.

The following steps are required to successfully activate varnish:

• Trigger Varnish installation in the VM
• Download and install composer package
• Adapt servers_conf.vcl
• Restart Varnish service
• Update OXID eShop config.inc.php
• Update OXID eShop admin settings

The above steps are described with more detail below.

Trigger Varnish installation

---
varnish:
  install: true

The above change will only trigger installation of Varnish with the distributed default configuration default.vcl which is not compatible with OXID eShop! If you change the parameter for a running VM you can use vagrant provision to trigger the installation.

Download and install composer package

Keep in mind that composer will ask for username and password as the package is available only to users who have bought the performance package. Please use the credentials which were provided during the purchase.

Because oxid-esales/varnish-configuration is a composer package and composer tool is available for VM by default we can use the following OXID eShop version independent way to download the package:

# Register private password protected repository
composer global config repositories.oxid-esales/varnish-configuration \
  composer https://varnish.packages.oxid-esales.com/

# Download the actual package
composer global require oxid-esales/varnish-configuration

Now the package has been downloaded into the global vendor directory and we can transfer the configuration files into the system by using these commands:

sudo cp $HOME/.composer/vendor/oxid-esales/varnish-configuration/default.vcl \
  /etc/varnish/

sudo cp $HOME/.composer/vendor/oxid-esales/varnish-configuration/servers_conf.vcl.dist \
  /etc/varnish/servers_conf.vcl

Adapt servers_conf.vcl

There are two mandatory placeholders which need to be updated inside the servers_conf.vcl file:

• <my_shop_hostname> - a valid host which could be used to communicate with the shop internaly;
• <my_shop_IP> - an inbound external IP address which has rights to trigger cache invalidation.

The following commands can be used with a default configuration of the VM to replace the placeholder values with suitable ones:

sudo sed -i "s/<my_shop_hostname>/127.0.0.1/g" /etc/varnish/servers_conf.vcl

sudo sed -i "s/<my_shop_IP>/$(ip addr | grep eth0 | tail -n 1 \
  | grep -oE "(\b([0-9]{1,3}\.){3}[0-9]{1,3}\b)" | head -n 1)/g" \
  /etc/varnish/servers_conf.vcl

Restart Varnish service

After adapting the configuration files we need to restart the Varnish service in order for the updated configuration to take effect:

sudo /etc/init.d/varnish restart

Update OXID eShop config.inc.php

Because Varnish uses 6081 port by default this needs to be reflected in the configuration file /var/www/oxideshop/source/config.inc.php.

For a default setup we need to change $this->sShopURL = 'http://www.oxideshop.local'; to $this->sShopURL = 'http://www.oxideshop.local:6081';, which can be automatically applied with:

sed -i "s/www\.oxideshop\.local/&:6081/g" /var/www/oxideshop/source/config.inc.php

Update OXID eShop admin settings

After all of the steps above one must apply necessary changes in the admin area of the OXID eShop:

• Visit http://www.oxideshop.local:6081/admin/ and select English as language
• Choose Master Settings
• Select Core Settings
• Switch to Caching
• Expand Reverse Proxy
• Tick Enable caching

To check if Reverse proxy cache is active, please click Test Reverse Proxy's availability. In case of successful configuration the following green colored message will appear "Reverse Proxy test succeed".

More configuration options

There are more configuration settings that can be changed to adapt the virtual environment to your needs. Be sure to take a look at the examples provided in the README of Base VM.

Settings that can be changed include among other things:

• Use NFS for shared-folder
• Change PHP version
• Change MySQL version
• Change VM provider
• Change shared folder path
• Define github token for composer
• Change ubuntu repository mirror url
• Change virtual host
• Change the display mode of errors
• Change MySQL password
• Trigger Selenium installation
• Trigger IonCube integration
• Customize email monitoring integration
• Customize MySQL administration web app integration
• Composer parallel install plugin