The Vagrant Solution for Magento Developers

Bootstrap your Magento development!

Find Out More


Magestead 2.0 is the perfect development toolbox to manage and control your Magento development workflow. A command line utility that will not only get you a custom pre-configured vagrant development environment with the tools you want, but also install the latest version of Magento or Magento 2

Magestead will also help you manage your daily development workflow with tools for flushing Redis, clearing your cache and re-indexing your data. Without ever needing to SSH into your virtual machine.

You can even use Magestead to help you manage your Behat and PhpSpec tests. Pretty cool right?

What's in the box?

Choose between CentOS and Ubuntu as your main operating system, select your webserver from NGINX or Apache and finally select which version of PHP you would like from PHP 5.6 and PHP 7. MariaDB 10.1 & Redis comes as standard.

Get Started!

The Full Stack

CentOS or Ubuntu NGINX or Apache PHP 5.6 or PHP 7
MariaDB 10.1 Redis Composer
Ruby 2.1.2 SASS (gem) Compass (gem)
Python NodeJS Gulp
Grunt Yeoman JSLint
CSSLint Coffee Script Grunt-CLI
ESLint Bower Nano

The Docs


System Requirements

To test your PHP installation run the following in your terminal -

php -ini | grep intl

You should see something similar -

intl.default_locale => no value => no value
intl.error_level => 0 => 0
client-id: your-client-id
intl.use_exceptions => 0 => 0

php -ini | grep mcrypt

You should see something similar -

mcrypt support => enabled
mcrypt_filter support => enabled
mcrypt.algorithms_dir => no value => no value
mcrypt.modes_dir => no value => no value

Optional Requirements

  • vagrant-hostsupdater - A Vagrant plugin for updating your hosts file automatically with your project URL
  • vagrant-bindfs - A Vagrant plugin to automate bindfs mount in the VM


Magestead uses Composer to manage it's dependencies. It is important that you have this installed prior to trying to install Magestead.

Download and install Magestead globally using Composer:

composer global require "richdynamix/magestead"

Make sure to place the ~/.composer/vendor/bin directory (or the equivalent directory for your OS) in your PATH so the magestead executable can be located by your system.

Once installed, the magestead new command will start a fresh new development environment in the directory you specify. For instance, magestead new my-project will create a directory named my-project and start the setup process for your new development environment.

Create a New Project

Magestead started as a way to bootstrap the Magento development and it remains the main purpose of the utility. To get started creating a Magento project we will use the magestead new command followed by your project name.

magestead new my-project

You will then be presented with a list of options, the default values are within the parentheses.

Configure the IP for your VM (
How many CPU's would you like to use? (1):
Define the VM memory limit (2048):

After you have have configured the VM specific settings you will be asked to configure the operating system and webserver.

Which OS would you like to install?
  [0] CentOS 6.5
  [1] Ubuntu 14

Which webserver would you like?
  [0] NGINX
  [1] Apache

Which version of PHP should be installed?
  [0] 56
  [1] 70

You should then choose the version of Magento you wish to install

Which application do you want to install?
  [0] Magento
  [1] Magento2

After these options you can now configure the application installation.

Enter your application's base_url (
Enter your application's default currency (GBP):
Enter your application's default locale (en_GB):

By default the base URL is set to the name of the project you created with the extension of .dev. You are free to change that here along with the default currency and locale.

If you chose Magento 2 as your application Magestead will need to verify your authentication details with It does this by checking the auth.json file inside your composer directory.

If the file does not exist, or the credentials for do not exist then Magestead will prompt you for this information.

Please enter your Magento username (public key):
Please enter your Magento password (private key):
Info: You will only be asked for this information once as Magestead will save this information to your auth.json file for future use.

The last option in the setup is to set your GIT repo.

Would you like to add your project to GIT? (no/yes)

The default option is set to NO, however, if you select YES then you will be given the opportunity to enter your projects GIT full URL. Please note the GIT project needs to be setup in your remote repo. This will then initialise your GIT project once the application has been installed and push your project up to the remote repo.

Enter your repo -

Once this is complete the pre-configured box will be downloaded, if you do not already have that box. Install your application and push your project to your remote repo.

Vagrant may ask for your password if you have the hostsupdater plugin installed as elevated permissions are required to update your hosts file.

Once complete your system notification centre will notify you when the installation is complete. If you have the hostupdater plugin installed you can now browse to new project site.
Note: For Magento 2 projects, the initial load of the site can be a little slow to build all the caches.


Magestead comes with several VM commands that act as a proxy to vagrant. You do not need to use these commands to control your development environment, you can use the default vagrant command.

VM Commands
magestead vm:up Spin up your development machine
magestead vm:suspend Pause your development machine (saving memory state)
magestead vm:halt Pause your development machine (removing memory state)
magestead vm:destroy Delete your development machine
magestead vm:ssh SSH into your development machine
magestead vm:status Get the status of your development machine
magestead vm:resume Resume your suspended development machine
magestead vm:run Run commands on your development machine via SSH

The magestead vm:run command requires you to add your argument as a string to incapsulate the entire command or group of commands i.e.

magestead vm:run 'sudo cat /var/log/nginx/error.log;'


Index Commands
magestead index:info Show available indexes
magestead index:reindex {index} Reindex data

If no {index} is passed to the magestead index:reindex {index} command then all indexes will be reindexed

Magento 2 Only Commands
magestead index:status Show status of index
magestead index:mode:set {mode} Set index mode type
magestead index:mode:show {index} Show index mode


Magestead provides a convenient way to access your server logs. You can now stream or view your application specific access log or error log.

Viewing a log will dump the entire log contents to your terminal's window, whereas streaming a log will perform a tail -f on the log.

Log Commands
magestead log:view {log} View a specific server log
magestead log:stream {log} Stream a specific server log


Much like the index command, Magestead can help you manage your cache regardless of which operating system or Magento version you have installed.

Cache Commands
magestead cache:clean Cleans cache types
magestead cache:disable Disable cache types
magestead cache:enable Enable cache types
magestead cache:flush Flushes cache storage used by cache types
magestead cache:status Checks cache status


Since Redis is used for storing the Magento cache and Magento 2 FPC, you will find yourself needing to giving it a flush from time to time.

Redis Commands
magestead redis:flush:all Flush redis storage


Magestead will install PHPSpec for you during the inital setup of your project, however, you will need to configure the project manually to meet your projects requirements.

When installed you can run your PHPSpec test suite using Magestead

PhpSpec Commands
magestead phpspec {option} Run PHPSpec against your project


Magestead will install Behat for you during the inital setup of your project, however, you will need to configure the project manually to meet your projects requirements.

When installed you can run your Behat test suite using Magestead

Behat Commands
magestead behat {option} Run Behat against your project


MailHog is a web and API SMTP testing server, which is very useful when you are in a development environment. You no longer need to worry about waiting on emails coming to your inbox for testing.

MailHog works much like Mailcatcher where it will provide you with a webUI email client for all emails being sent from your Magento application.

MailHog is already configured. There is nothing you need to do :)

To access the MailHog webUI, simply access your site on over HTTP on port 8025

Connect to your DB

The easiest way to connect to your DB using a dedicated application on your host machine is to use a SSH tunnel.

Connect to the SSH tunnel with the username vagrant and the generated SSH key at puphpet/files/dot/ssh/id_rsa. This key is generated when you build the initial new project.

When connecting to the DB use the username root and password of vagrant.

Both the DB host and the SSH tunnel should be on

See screen shot of Sequel Pro setup.

DB Screen Shot

v1.6 Docs

Installation & Setup

There are a few obvious prerequisites before you can use your Magestead environment, you must install VirtualBox and Vagrant. Please install the latest versions of these before continuing.

Since Magestead is a per project based vagrant solution we need to clone the Magestead GitHub repository into a new project folder -

git clone my-project-dir

Once the download is complete you can simply run vagrant up in your project directory i.e.

cd my-project-dir;
vagrant up;

On the very first run of vagrant up the vagrant box will need to download, this may take a while depending on your network connection. Grab a coffee…. Check your Facebook.

When vagrant has finished provisioning your box you can access your site at

Configuring Magestead

Anyone familiar with Laravel Homestead will recognise the Magestead.yaml file. This is pretty much a direct copy of the Homestead.yaml file with some obvious changes and cutbacks.

The first section hasn’t changed other than the default IP address. This was done to resolve any clashes you may have with Laravel Homestead or ScotchBox.

At present Magestead has only been configured to work with virtualbox. This is simply because its free and easy to use. I don’t use any virtualisation software to try and test however you are free to submit a pull request.

The authorize: setting will require you to provide your SSH public key, this is used for connecting to the box without the need for a password. Usually you won’t need to edit this as it is configured to use default settings.

The database magestead has been defined for you in databases: setting, you are free to add as many of these as you like. Perhaps you need a separate database for a blog.

The bootstrap: setting is a new setting to magestead and has two different options. The first option is the magento setting, when activated it will install Magento CE into your public directory using composer. The additional composer libraries like PHPUnit, PhpSpec & Magento Hackathon Composer Installer will also be installed along with the autoloader patch. It will also install the Cm_Cache_Backend_Redis extension should you wish to configure the redis backend.

See for documentation.

New to version v1.1 is Magento 2 using the option magento2. This will download the latest stable release from github, currently 1.0.0-beta, setup database and install the Magento2 software. Please note that the admin url is left to autogenerate during installation, pay attention to the output when magestead finishes running. It will prompt you with admin login credentials.

The third bootstrap: option is laravel. When you choose this option laravel will be downloaded and installed into a laravel directory and a symbolic link is created to the web public directory from your laravel public directory. The key is already set using composer and the directories of storage and bootstrap/cache are made writable by the server.

Launching The Vagrant Box

Vagrant Commands
Start or resume your server vagrant up
Pause your server (saving memory state) vagrant suspend
Pause your server (removing memory state) vagrant halt
Delete your server vagrant destroy
SSH into your server vagrant ssh

Blackfire Profiler

Blackfire Profiler by SensioLabs automatically gathers data about your code's execution, such as RAM, CPU time, and disk I/O. Homestead makes it a breeze to use this profiler for your own applications.

All of the proper packages have already been installed on your Magestead box, you simply need to set a Blackfire Server ID and token in your Magestead.yaml file:

- id: your-server-id
token: your-server-token
client-id: your-client-id
client-token: your-client-token

Once you have configured your Blackfire settings, re-provision the box using vagrant provision. Before you can use Blackfire you will need to install the companion extension for your web browser. The Blackfire documentation to will explain how to install the Blackfire companion extension