Virtual Machine for Magento2

Supported system:

Supported release:

technical-stack

Requirements

Virtualbox

VirtualBox is an open source virtualizer, an application that can run an entire operating system within its own virtual machine.
Stable version >= 5.2.0

Download the installer for your laptop operating system using the links below.
- VirtualBox download
Run the installer, choosing all the default options.
- Windows: Grant the installer access every time you receive a security prompt.
- Mac: Enter your admin password.
- Linux: Enter your user password if prompted.
Reboot your laptop if prompted to do so when installation completes.
Close the VirtualBox window if it pops up at the end of the install.

Vagrant

Vagrant is an open source command line utility for managing reproducible developer environments.
Stable version >= 2.2.0

Download the installer for your laptop operating system using the links below.
- Vagrant download
Reboot your laptop if prompted to do so when installation completes.

Configurations

Related guide

Made by Onilab for Windows 10:
https://onilab.com/blog/install-magento-2-on-localhost-a-windows-10-guide/

Pre-installation

⚠ This vagrant installation is non-interactive: DO NOT USE SSH KEY WITH PASSPHRASE.
If your ssh key has been created with a passphrase, please create another one.

System	Steps
Windows	1. Open UEFI BIOS and make sure virtualization is turned 'on' 2. Open powershell as administrator and run: `Add-MpPreference -ExclusionProcess winnfsd.exe` 3. Open `C:\Windows\System32\drivers\etc\hosts` as administrator then add `network_ip` and `magento_url` Default values would be: `192.168.60.0 dev.magento.com`
MacOs	1. To avoid issue with guest additions, run: `sudo apt install linux-headers-$(uname -r)`
Linux	1. To install NFS properly, run: `sudo apt install nfs-kernel-server`
Linux/MacOS	2. Open `/etc/hosts` as sudo then add `network_ip` and `magento_url` Default values would be: `192.168.60.0 dev.magento.com`

Installation

Clone this project: git clone git@github.com:zepgram/magento2-fast-vm.git
Copy/past: ssh.example rename it ssh then put your id_rsa and id_rsa.pub keys
Copy/past: config.yaml.example rename it config.yaml
Then customize configurations according to Yaml config overview
If you want to import an existing database: create a compressed sql dump and name it db-dump.sql.gz.
You must also fill crypt_key in config.yaml
To start install run: vagrant up (duration: ~20 minutes)
Finally, run: vagrant ssh to access guest machine

Yaml config overview

Parent Node	Name	Default Value	Allowed Value	Is optional	Description
vmconf	machine_name	Vagrant Magento 2	string	no	Vagrant machine name
	network_ip	192.168.60.0	IP address	no	Accessible IP address /etc/hosts
	host_name	zepgram	string	no	Virtual host name
	memory	4096	number	no	RAM allocated
	cpus	1	number	no	CPU allocated
	mount	nfs	nfs / rsync / default	no	Mount strategy
	path	root	app / root	no	Mount whole directory or `app/` only
	provision	all	all / system / magento	no	Define script provision
composer	username	magentoUsernameKey	string	no	Composer auth user
	password	magentoPasswordKey	string	no	Composer auth password
git	name	John Doe	string	yes	Git user name
	email	john@doe.com	email	yes	Git user email
	host	github.com	url	yes	Git host server name
	repository	ssh://git@github.com:%.git	git repository	yes	Define repository to clone
magento	url	dev.magento.com	url	no	Magento site host name
	source	composer	composer / (master/develop..)	no	Define source installation. On git install set the branch name to clone.
	edition	community	community / enterprise	no	Magento project edition
	version	2.4.5	>=2.2	no	Magento version release
	php_version	default	default / 7.x / 8.x	no	PHP version
	sample	true	true / false	no	Install sample data
	mode	developer	developer / production	no	Magento execution mode
	currency	USD	ISO 4217	no	Default currency
	language	en_US	ISO 639-1 + ISO 3166	no	Default language
	time_zone	America/New_York	timezone	no	Default timezone
	crypt_key	-	string	yes	Crypt key form app/etc/env.php for db-dump.sql.gz (db import)
	search_engine	opensearch	opensearch / elasticsearch	false	Search engine for catalog search
	disable_two_factor_auth	true	true / false	false	Disable 2 factor authentication for admin access

Path

root directory: mount the entire project.
app directory: mount only app directory. Not sharing generated files between machines ensure great performance but in return, source code /vendor is missing.

Mount options

RSYNC

Only useful on path set to root.

Loss of performance is due to files generated on the fly, by excluding them you can mount the whole directory root and get performance equal to an app mount.
The vagrant rsync-auto is launched by default on vagrant up, even with that if you need to force an update you can run vagrant rsync. Terminal should be kept open for rsync-auto: do not close it.
Rsync is unilateral, your host machine push files to guest but not the other way.
Anyway if it's necessary, after a composer update for example, you can run vagrant rsync-back to push files from guest to host.
After first installation, you must run vagrant reload to enable file watching with rsync-auto.
See Rsync option

NFS

Recommended for root and app path.
The most stable option, config has been made to ensure compliance with all OS. Less performant than rsync but files are perfectly shared between guest and host machine.

See NFS option

DEFAULT

It can be used with app path if you encountered any issue with NFS and rsync mount.

See basic usage

Extra provisions

You can add extra shell provisions.
Those provisions will be executed on pre-defined sequences:

extra/001-env.sh his purpose is to provide extra environment variables or extra package, executed after script 001-system-env.sh
extra/100-pre-build.sh define your specific system configuration before installation, executed after script 100-magento-pre.sh
extra/120-post-build.sh you can execute magento command in this sequence, executed after script 120-magento-post.sh

To be executed you must remove the string -example from the filename script.
As an example of use, you can adapt data from your database import by using the script 100-pre-build.sh

System usage

Permission

Magento file system owner is configured for vagrant user, it means all commands in magento project must be executed by this user.
By default command line vagrant ssh will log you as vagrant user.

To re-apply magento permissions you can run permission directly in command line.

Command line

magento (Magento CLI alias)
magento-cloud (Magento Cloud CLI)
pestle (A collection of command line scripts for code generation)
magerun (The swiss army knife for Magento developers)
permission (Re-apply permissions to project)

Cron

Enable cron:

./bin/magento cron:install

Disable cron:

./bin/magento cron:remove

Configuration

Package & Software

php + required extensions
curl
git
gitflow
vim
composer
nginx
php-fpm
percona
redis-server
elasticsearch
opensearch
grunt
postfix
mailhog
pestle
magereun
adminer
magento-cloud cli
bin/magento bash completion

Access

User bash terminal
- user: vagrant
Back-office
- url: magento[url]/admin
- user: magento.admin
- pass: admin123
Database
- user: vagrant
- pass: vagrant
- name: magento
Mailhog
- url: [network_ip]:8025
Adminer
- url: [network_ip]/adminer
Phpinfo
- url: [network_ip]/php

Mysql

Percona server 8.0 is now installed for Magento >=2.4.0
Lower versions are handled foreach existing Magento versions.

PHP

PHP 8.2 is now installed by default for Magento >=2.4.6
Lower versions are handled foreach existing Magento versions.

Composer

Composer v2 is now installed by default for Magento >=2.4.2
Lower versions are handled foreach existing Magento versions.

Elasticsearch

Version 8.4.x of Elasticsearch is now available for Magento 2.4.6
Version 7.6.x of Elasticsearch is available for version between 2.4.0 and 2.4.5
Lower versions are handled foreach existing Magento versions
Otherwise, you can also completely disable elasticsearch by installing this module: https://github.com/zepgram/module-disable-search-engine

Opensearch

Version 2.5.x is now available for Magento 2.4.6
Elasticsearch will be installed by default on lower Magento versions.

Issues

Windows 10

There is a known issue with composer installation on windows 10.
This issue could not be solved yet, and has already been reported 2 times.

This is related to the computer and BIOS configuration.
This is only reported on "NFS" mount option.

To solve this, I recommend to set mount option to "rsync", then after full installation you should be able to fall back to NFS.

Others

If you have trouble during installation please open a new issue on this GitHub repository.

zepgram / magento2-fast-vm

readme