Table of contents

Overview

Current OXID eShop development environment is inspired by PuPHPet and Phansible projects.

Virtual environment is built using:

Vagrant - virtual environment automation tool;
Ansible - environment orchestration tool;
YAML - solution configuration.

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

Base VM - Base LAMP stack (also used as base for other VMs);
eShop VM - Current repository, eShop specific configuration, roles and SDK components.

Getting started

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

Dependencies

Vagrant (>=1.7)
VirtualBox ¹ (>=4.2)
Git
OpenSSH
Vagrant plugins:
- vagrant plugin install vagrant-hostmanager
- vagrant plugin install vagrant-bindfs
- vagrant plugin install 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.)

Quick start

Clone² out current repository:

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

Start the VM:

cd oxvm_eshop
vagrant up

After successful provision process use the following links to:
- Open OXID eShop: http://www.oxideshop.dev/
- Access admin area: http://www.oxideshop.dev/admin/
  - Username: admin
  - Password: admin

Configuration

Default virtual environment configuration should be sufficient enough to get the eShop CE/PE/EE versions up and running. However, it is possible to adjust the configuration of virtual environment to better match personal 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 ³ 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 stat over from a clean state.

Examples

Below is a list of possible frequent changes which are typically done after cloning this repository.

One can just copy and paste the example snippets from the list below to the personal.yml file at the root of this repository.

Change PHP version

By default latest PHP version found in ubuntu repository is installed.

When PHP version is specified, PHPBrew is installed and used for switching between versions. Requested version will be either built on the fly or downloaded from assets⁴ repository.

---
php:
  version: 5.3

To disable downloading of cached versions from assets repository, set cache_repository to empty value. Alternatively it is possible to build your own PHP packages and place them into any svn repository.

Only when php version is specified, PHPBrew will be installed so those commands became available inside VM:

phpbrew list - lists installed PHP versions
phpbrew known - lists available PHP versions
phpbuild [version] - builds PHP version
phpswitch [version] - switch PHP version
phpswitch off - switch back to default PHP version

When versions is downloaded from assets repository, phpbrew will not have its source code and therefore will not be able to build php extensions. To download PHP source run this command with full php version specified:

phpbrew download [phpversion] && tar jxf ~/.phpbrew/distfiles/php-[phpversion].tar.bz2 -C ~/.phpbrew/build/

Change VM provider

Change VM provider from VirtualBox (default) to LXC. A list of available and tested providers⁵:

virtualbox - Default provider which is free to use and available on all major operating systems;
lxc ⁶ - Operating system level virtualization which vastly improves I/O performance compared to para-virtualization solutions;
parallels ⁷ - Commercial VM provider for OS X.

---
vagrant_local:
  vm:
    provider: lxc

Set eShop to UTF-8 mode

By default shop will be installed with UTF-8 mode disabled (with iUtfMode = '0' value inside config.inc.php).

In order to turn on the UTF-8 mode:

---
eshop:
  config:
    utf_mode: 1

This change will not affect the already configured shop⁸ .

Change shared folder path

Change the default application shared folder from oxideshop to local path /var/www and update eShop target folder⁹.

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

Define github token for composer

Provide OAuth token from github for composer so that the access API limit could be removed¹⁰.

---
php:
  composer:
    github_token: example_secret_token

Change ubuntu repository mirror url

Change the default ubuntu repository mirror url from http://us.archive.ubuntu.com/ubuntu/ to http://de.archive.ubuntu.com/ubuntu/.

---
server:
  apt_mirror: http://de.archive.ubuntu.com/ubuntu/

Change virtual host

Change the default virtual host from www.oxideshop.dev to www.myproject.dev.

---
vagrant_local:
  vm:
    aliases:
      - www.myproject.dev

Change MySQL password

Change the default MySQL user password from oxid to secret.

---
mysql:
  password: secret

Trigger Varnish installation

Trigger Varnish ¹¹ installation so that it can be used within eShop.

---
varnish:
  install: true

Trigger Selenium installation

Trigger Selenium installation so that it can be used to run Selenium tests with the help of OXID testing library.

---
selenium:
  install: true

Customize email monitoring integration

Integration of Mailhog allows to monitor e-mail activity from the eShop. List of e-mails could be seen at: http://www.oxideshop.dev/mail/

Possible configuration options for Mailhog:

web_port - web UI port (8025 is the default value which means that the UI can be accessed by the following URL: http://www.oxideshop.dev:8025/)
smtp_port - SMTP server port (1025 is the default value)
web_alias - an URL alias for the default virtual host to act as a proxy for web UI of mailhog (/mail/ is the default value which means that the UI can be access by the following URL: http://www.oxideshop.dev/mail/)

An example configuration which changes web UI port to 8024, SMTP port to 1026 and alias to /emails/:

---
mailhog:
  web_port: 8024
  smtp_port: 1026
  web_alias: /emails/

Mailhog is installed by default as it has install: true option in the default configuration file. In order to disable email monitoring please use the following configuration snippet:

---
mailhog:
  install: false

Composer parallel install plugin

The composer parallel install plugin hirak/prestissimo is enabled by default. In order to disable it please use the following snippet:

---
php:
  composer:
    prestissimo:
      install: false

SDK

Out of the box the VM is equipped with the following SDK components:

Module skeleton generator - module which helps to create new OXID eShop modules;
Module certification tools - a collection of tools which allows one to see a detailed report from module certification process;
Testing library - a library for writing various kind of tests inside eShop and a set of tools for running those tests.

There are also other SDK components which could be found at: http://wiki.oxidforge.org/SDK

Usage

Module skeleton generator

By default this module is installed under eShop's modules directory (by default it will be /var/www/oxideshop/source/modules/ which is defined by eshop_path.modules key in configuration).

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

Module certification tools

By default the tools are installed under VM's home folder (~/eshop_sdk which is defined by eshop.sdk.path key in configuration). The repository of tools is cloned out in ~/eshop_sdk/module_certification_tools and an extra shortcut ox_cert is created inside ~/eshop_sdk/bin/ (it's included in PATH environment variable automatically).

There is no need to do any installation part for tools to work as it is already done by the VM's provision process.

In order to invoke the certification report generator just use the provided shortcut:

ox_cert <vendor_name>/<module_name>

An example of invoking the reporting tool for module generator ¹²:

$ ox_cert oxps/modulegenerator

After the execution it will generate a HTML document which will be placed at ~/eshop_sdk/module_certification_tools/result/<datetime>/report.html.

Once the report is generated one can just view the contents of it straight from inside the VM using command line tools or copy the file to shared folder and view it from host machine, e.g.:

cp ~/eshop_sdk/module_certification_tools/result/20150916101719/report.html \
  /var/www/oxideshop

Testing library

Library needed for various testing purposes is already installed in the VM through the help of composer, because it's defined in composer.json as development requirement inside eShop (at least in CE latest development version).

All binary tools are installed inside /var/www/oxideshop/source/vendor/bin/ (this value may be changed through eshop_path.source key in configuration).

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 could be found at: https://github.com/OXID-eSales/testing_library

Guides

List of guides for working with VM:

Use eShop packages instead of repositories

Our current eShop packages have different file/directory structure compared to eShop repositories. VM is suited to work for eShop repository file/directory structure (because it holds our source and test files at the same place). Due to this reason one would need to manually extract eShop source and test packages into shared folder.

In order to prepare VM for usage of eShop packages please follow the steps below before running the VM:

Create shared folder¹³ (By default it's oxideshop folder);
Extract source package into oxideshop/source folder;
Extract tests package into oxideshop/tests folder (This step is optional for eShop runtime).

If the above steps were done after the creation/provision of VM please make sure to re-run vagrant provision command for provision process to make necessary changes.

Directory structure overview of eShop packages placed for the VM:

oxvm_eshop - root of oxvm_eshop repository
+ <oxvm_eshop repository files>
+ oxideshop - shared folder
   + source
      + <eShop source package contents>
   + tests
      + <eShop tests package contents>

An example of commands to prepare VM for using eShop packages:

Keep in mind that the below example only demonstrates how one should prepare the VM for source and test packages. In order to actually get/download source and test packages for eShop PE/EE versions please contact OXID eSales support.

In case the following two packages were received:

OXID_ESHOP_EE_5.2.5_for_PHP_5.6.zip - source package
OXID_ESHOP_TESTS_EE_5.2.5_for_PHP_5.6_SOURCE.rar - test package

# Clone out VM repository
git clone --recursive https://github.com/OXID-eSales/oxvm_eshop.git
cd oxvm_eshop

# Download packages
wget http://<url provided by support>/OXID_ESHOP_EE_5.2.5_for_PHP_5.6.zip
wget http://<url provided by support>/OXID_ESHOP_TESTS_EE_5.2.5_for_PHP_5.6_SOURCE.rar

# Extract packages
mkdir oxideshop
unzip OXID_ESHOP_TESTS_EE_5.2.5_for_PHP_5.6_SOURCE.rar -d ./oxideshop/source/
unrar x OXID_ESHOP_TESTS_EE_5.2.5_for_PHP_5.6_SOURCE.rar ./oxideshop/tests/

# Start the VM
vagrant up

Troubleshooting

List of troubleshooting items:

Provision process hangs on "Run composer install" task

During the provision process (which could be invoked implicitly by vagrant up or explicitly by vagrant provision) a task Run composer install might hang (waiting for time-out) because github access API limit has been reached and composer is asking for github account username/password which could resolve the API limit. Ansible will not provide this information to STDOUT or STDERR so it will look like the task just hanged.

Since there are no options to provide username/password for this particular task one could just use a github API token which will allow to overcome the API access limit.

How to create and configure a github token is described in Define github token for composer chapter.

Error from Unit_Admin_ModuleListTest::testRender() method while testing eShop

Older versions of eShop contains a very strict test inside Unit_Admin_ModuleListTest::testRender() method which tries to match the exact list of available modules. The test method might fail because VM includes SDK components and some of them are actual modules (which will result in modified list of available modules).

This is a known issue which is fixed in the development and new upcoming releases of eShop.

To check which shop is compatible with testing library please refer to compatibility list.

Browser shows "Zend Guard Run-time support missing!"

This message will only appear if a Zend Guard encoded eShop package is being used. In order to solve the issue one has to install Zend Guard Loader which will decode the encoded PHP files on execution.

To install and enable Zend Guard Loader PHP extension inside VM:

# From host (local machine)
vagrant ssh

# From guest (virtual machine)
cd /usr/lib/php5/20121212/
sudo wget https://github.com/OXID-eSales/oxvm_assets/blob/master/zend-loader-php5.5-linux-x86_64.tar.gz?raw=true -O zend.tar.gz
sudo tar zxvf zend.tar.gz
sudo cp zend-loader-php5.5-linux-x86_64/ZendGuardLoader.so ./
sudo cp zend-loader-php5.5-linux-x86_64/opcache.so ./zend_opcache.so
cd /etc/php5/mods-available/
sudo sh -c 'echo "zend_extension=ZendGuardLoader.so" > zend.ini'
sudo sh -c 'echo "zend_extension=zend_opcache.so" >> zend.ini'
sudo php5dismod opcache
sudo php5enmod zend
sudo service apache2 restart

Keep in mind that different PHP version needs different version of Zend Guard Loader extension. List of possible extension versions can be found in oxvm_assets repository.

More information on how to install and configure Zend Guard Loader can be found at: http://files.zend.com/help/Zend-Guard/content/installing_zend_guard_loader.htm

On Windows machines, getting "requires a TTY"

The example of error message:

{ oxvm_eshop } master » vagrant destroy
Vagrant is attempting to interface with the UI in a way that requires
a TTY. Most actions in Vagrant that require a TTY have configuration
switches to disable this requirement. Please do that or run Vagrant
with TTY.

Please check answers on stackoverflow for your specific case: http://stackoverflow.com/questions/23633276/vagrant-is-attempting-to-interface-with-the-ui-in-a-way-that-requires-a-tty

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.↩
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.↩
personal.yml configuration file is already included in .gitignore and should not be visible as changes to the actual repository.↩
Repository with some already prebuilt versions of php for faster installation.↩
VM solutions from VMWare, such as workstation and fusion were not yet adapted or tested with our current configuration of VM.↩
Keep in mind that LXC provider is only available for GNU/Linux based operating systems. In order to start using this provider with vagrant a plugin must be installed for it (vagrant plugin install vagrant-lxc). So far it has been only tested with Ubuntu based OS with lxc package installed (sudo apt-get install lxc).↩
A vagrant plugin must be installed (vagrant plugin install vagrant-parallels) in order to use vagrant with Parallels.↩
Keep in mind that the provided snippet will not change the UTF-8 mode of the eShop if the configuration file (config.inc.php) is already present and defined. In this case one has to make the change of iUtfMode value directly in the config.inc.php file of the eShop.↩
Keep in mind that if the shared folder target does not match actual application (eShop) target it has to be specified explicitly by defining eshop_target_path.↩
By default github has API access limits set for anonymous access. In order to overcome these limits one has to create a github token, which could be done as described in: https://help.github.com/articles/creating-an-access-token-for-command-line-use/↩
Varnish can only be used with the eShop EE version and with purchased "performance pack" (https://www.oxid-esales.com/performance/). Keep in mind that the default Varnish port 6081 is being used to access the shop. This should also be reflected in config.inc.php file as sShopURL parameter, e.g. http://www.oxideshop.dev:6081/ .↩
The tools can be invoked from any working directory as long as the ox_cert shortcut is being used.↩
The actual sharing process of the folder will be done by the VM provision process, end-user only needs to create this folder and make sure the folder exists. The path and name of the folder is configurable via the vagrant_local.vm.app_shared_folder parameter. By default it's <oxvm_eshop_root>/oxideshop. More information about how to configure this value can be found in: Change shared folder path .↩

keywan-ghadami/oxvm_eshop