upload your config

  1. Download the latest version of VirtualBox from here
  2. Download the latest version of Vagrant from here.

To login to your VM you must use $ vagrant ssh or user vagrant using the private key automatically generated at puphpet/files/dot/ssh/id_rsa.key. This key is generated after your initial $ vagrant up!

Local VM Details


Local VM Forwarded Ports

Sharing Folders with Local VM


If you are on OSX or Linux, it is highly recommended you choose "NFS" as the Shared Folder Type, and install the vagrant-bindfs plugin with $ vagrant plugin install vagrant-bindfs.

Rackspace Instance

Login to Rackspace and go to the API page. You will need an API Key.

Installation Requirements

Run the following commands from your host's terminal (not within the VM):

$ vagrant plugin install vagrant-rackspace
$ vagrant box add dummy https://github.com/mitchellh/vagrant-rackspace/raw/master/dummy.box
$ vagrant plugin install vagrant-rackspace
$ vagrant box add dummy https://github.com/mitchellh/vagrant-rackspace/raw/master/dummy.box

You need rsync installed. Easiest way is to use Cygwin and install it through there. Alternatively, you can install rsync separately and add it to your PATH.

$ vagrant plugin install vagrant-rackspace
$ vagrant box add dummy https://github.com/mitchellh/vagrant-rackspace/raw/master/dummy.box

Accessing Your VM

To access your VM after running $ vagrant up, type $ vagrant ssh-config to get the IP address assigned to the server you created, and add the IP address to your computer's hosts file. Type $ vagrant ssh to be immediately connected via SSH to your new server!

Rackspace VM Details

Sharing Your Folders

Linode

Don't have a Linode account? Click here to create one

Login to Linode and go to the API page. You will need an API Key.

Installation Requirements

Run the following commands from your host's terminal (not within the VM):

$ vagrant plugin install vagrant-linode
$ vagrant box add dummy https://github.com/displague/vagrant-linode/raw/master/box/linode.box
$ vagrant plugin install vagrant-linode
$ vagrant box add dummy https://github.com/displague/vagrant-linode/raw/master/box/linode.box

You need rsync installed. Easiest way is to use Cygwin and install it through there. Alternatively, you can install rsync separately and add it to your PATH.

$ vagrant plugin install vagrant-linode
$ vagrant box add dummy https://github.com/displague/vagrant-linode/raw/master/box/linode.box

Accessing Your VM

To access your VM after running $ vagrant up, type $ vagrant ssh-config to get the IP address assigned to the server you created, and add the IP address to your computer's hosts file. Type $ vagrant ssh to be immediately connected via SSH to your new server!

If you choose CentOS

The CentOS distributions do not ship with rsync installed! The first time you run $ vagrant up IT WILL ERROR, but this is OK! Simply $ vagrant ssh and type $ sudo yum install rsync. Once it finished installing, run $ vagrant provision.

Linode Details

Sharing Your Folders

Softlayer Instance

Login to Softlayer and go to the profile page. You will need an API Key.

Installation Requirements

Run the following commands from your host's terminal (not within the VM):

$ vagrant plugin install vagrant-softlayer
$ vagrant box add dummy https://github.com/audiolize/vagrant-softlayer/raw/master/dummy.box
$ vagrant plugin install vagrant-softlayer
$ vagrant box add dummy https://github.com/audiolize/vagrant-softlayer/raw/master/dummy.box

You need rsync installed. Easiest way is to use Cygwin and install it through there. Alternatively, you can install rsync separately and add it to your PATH.

$ vagrant plugin install vagrant-softlayer
$ vagrant box add dummy https://github.com/audiolize/vagrant-softlayer/raw/master/dummy.box

Accessing Your VM

To access your VM after running $ vagrant up, type $ vagrant ssh-config to get the IP address assigned to the server you created, and add the IP address to your computer's hosts file. Type $ vagrant ssh to be immediately connected via SSH to your new server!

Softlayer VM Details

Did you read the instructions? READ THE INSTRUCTIONS!

Your VM will be named {HOSTNAME}.{DOMAIN}

Sharing Your Folders

AWS EC2 Instance

Use Amazon's famously reliable servers for your app!

Installation Requirements

Run the following commands from your host's terminal (not within the VM):

$ vagrant plugin install vagrant-aws
$ vagrant box add dummy https://github.com/mitchellh/vagrant-aws/raw/master/dummy.box
$ vagrant plugin install vagrant-aws
$ vagrant box add dummy https://github.com/mitchellh/vagrant-aws/raw/master/dummy.box

You need rsync installed. Easiest way is to use Cygwin and install it through there. Alternatively, you can install rsync separately and add it to your PATH.

$ vagrant plugin install vagrant-aws
$ vagrant box add dummy https://github.com/mitchellh/vagrant-aws/raw/master/dummy.box

AWS EC2 Instance Details


US East (Northern Virginia) Region
US West (Northern California) Region
US West (Oregon) Region
EU (Ireland) Region
South America (Sao Paulo) Region
Asia Pacific (Tokyo) Region
Asia Pacific (Singapore) Region
Asia Pacific (Sydney) Region

Sharing Your Folders

Google Compute Engine Instance

Visit the Developers Console and make sure to enable the Google Compute Engine service for your project. If prompted, review and agree to the terms of service.

While still in the Developers Console, go to API & AUTH -> Credentials section and click the Create new Client ID button. In the pop-up dialog, select the Service Account radio button and the click the Create Client ID button.

When prompted, select the Download private key button and make sure to save this file in a secure and reliable location. This key file will be used to authorize all Vagrant commands available in this plugin.

Still on the same page, find the newly created Service Account text block on the API Access page. Record the Email address (it should end with @developer.gserviceaccount.com) associated with the new Service Account you just created. You will need this email address and the location of the private key file to properly configure this Vagrant plugin.

Then, you must go to Compute -> Compute Engine -> Metadata -> SSH KEYS and add the public key you will be using below.

Installation Requirements

Run the following commands from your host's terminal (not within the VM):

$ vagrant plugin install vagrant-google
$ vagrant box add gce https://github.com/mitchellh/vagrant-google/raw/master/google.box
$ vagrant plugin install vagrant-google
$ vagrant box add gce https://github.com/mitchellh/vagrant-google/raw/master/google.box

You need rsync installed. Easiest way is to use Cygwin and install it through there. Alternatively, you can install rsync separately and add it to your PATH.

$ vagrant plugin install vagrant-google
$ vagrant box add gce https://github.com/mitchellh/vagrant-google/raw/master/google.box

Accessing Your VM

To access your VM after running $ vagrant up, type $ vagrant ssh-config to get the IP address assigned to the server you created, and add the IP address to your computer's hosts file. Type $ vagrant ssh to be immediately connected via SSH to your new server!

Google Compute Engine Details

Sharing Your Folders

Digital Ocean Droplet

Don't have a Digital Ocean account? Click here to create one (affiliate link - help support this free service)!

Login to Digital Ocean and go to the API page. You will need a Client ID and API Key.

Installation Requirements

Run the following commands from your host's terminal (not within the VM):

$ vagrant plugin install vagrant-digitalocean
$ vagrant box add dummy https://github.com/smdahlen/vagrant-digitalocean/raw/master/box/digital_ocean.box
$ vagrant plugin install vagrant-digitalocean
$ vagrant box add dummy https://github.com/smdahlen/vagrant-digitalocean/raw/master/box/digital_ocean.box

You need rsync installed. Easiest way is to use Cygwin and install it through there. Alternatively, you can install rsync separately and add it to your PATH.

$ vagrant plugin install vagrant-digitalocean
$ vagrant box add dummy https://github.com/smdahlen/vagrant-digitalocean/raw/master/box/digital_ocean.box

Accessing Your VM

To access your VM after running $ vagrant up, type $ vagrant ssh-config to get the IP address assigned to the server you created, and add the IP address to your computer's hosts file. Type $ vagrant ssh to be immediately connected via SSH to your new server!

If you choose CentOS

The CentOS images do not ship with rsync installed! The first time you run $ vagrant up IT WILL ERROR, but this is OK! Simply $ vagrant ssh and type $ sudo yum install rsync. Once it finished installing, run $ vagrant provision.

Digital Ocean VM Details

Sharing Your Folders

Ikoula Cloud

Don't have an Ikoula Cloud account ? Click here to create one

Information on Ikoula Cloud Instances.

Installation Requirements

Run the following commands from your host's terminal (not within the VM):

$ vagrant plugin install vagrant-cloudstack
$ vagrant box add ikoulacloud https://github.com/klarna/vagrant-cloudstack/raw/master/dummy.box
$ vagrant plugin install vagrant-cloudstack
$ vagrant box add ikoulacloud https://github.com/klarna/vagrant-cloudstack/raw/master/dummy.box

You need rsync installed. Easiest way is to use Cygwin and install it through there. Alternatively, you can install rsync separately and add it to your PATH.

$ vagrant plugin install vagrant-cloudstack
$ vagrant box add ikoulacloud https://github.com/klarna/vagrant-cloudstack/raw/master/dummy.box

Ikoula Cloud Instance Details


Zone 3 France Direct Routing (Z03-R0-IKDC01-FR)

Sharing Your Folders

System Packages

Packages to install via the OS package manager, separated by comma. Do not add Apache/Nginx or PHP here - you will choose those later.

Some common packages are (do not mix!):

Users & Groups

Add groups here. Not all groups require users.

Add users here. Not all users require groups, but if you want to add a user to a group, the group must be listed above in the Groups section.

The required format for users to be added to groups is {USER}:{GROUP}. If you want to create a user without assigning to a group, simply use {USER}. You can also assign a user to multiple groups using {USER}:{GROUP}:{GROUP} - a user can belong to as many groups as you want.

User home directories will be placed at /home/{USER}.

Cron Jobs

The user must exist. root is a valid option. If you're deploying locally, vagrant is also valid, if deploying remotely then enter the ssh username you chose in the Deploy Target area. If you'd like a different user make sure to add them here.

If you don't define a user, the user that runs Puppet will be used by default. This user has root access, and most likely is root.

Minute, hour, day and month values can all be left blank, as long as one of them is not blank. e.g. hour, day and month can be blank if minute has a value.

dotfiles

You can add all your dot files (.bash_aliases, .vimrc, .gitconfig, etc), to the puphpet/files/dot/ folder that will appear after you extract your generated zip file.

During initial startup, they will automatically be copied into the VM. There is a sample .bash_aliases file there for you to start with - overwrite at will!

Script Files

You can run your own custom code after the VM finishes provisioning by adding files to the puphpet/files/exec-always, puphpet/files/exec-once, puphpet/files/startup-always, and puphpet/files/startup-once folders.

Files are executed in alphabetical order. Files within exec-once are run before files within exec-always, and files within startup-once are run before files within startup-always. Files in exec-once and exec-always are run before files in startup-once and startup-always.

Files within exec-always will run on initial $ vagrant up and all $ vagrant provision, while files within exec-once will run only the first time you run Vagrant, unless you SSH into the VM and remove the /.puphpet-stuff/exec-once-ran file and re-run Vagrant.

Files within startup-always will run on each $ vagrant up, while files within startup-once will only run on the next time you run Vagrant, unless you SSH into the VM and remove the /.puphpet-stuff/startup-once-ran file and re-run Vagrant.

Firewall Settings

Warning: This is for fairly advanced use! Try to only open ports as you need them. The SSH port (usually 22 and defined in vagrantfile.ssh.port) is automatically opened for you.

Apache Modules

Only Apache or Nginx can be installed (or none at all). Installing both at the same time is not supported.


mod_pagespeed is not compatible with mod_php.

Apache Virtual Host

Install Nginx

Only Apache or Nginx can be installed (or none at all). Installing both at the same time is not supported.

Nginx Virtual Host

Check the box to proxy the vhost. Make sure you configure the upstream above.

PHP Quick Settings

If you install PHP, you cannot install HHVM.



PuPHPet uses PHP-FPM (FastCGI Process Manager) by default. If you want to use mod_php, check the box above. This only affects your VM if you have chosen to use Apache. Nginx uses PHP-FPM.

If you check this box, then PuPHPet will use Apache 2.2. It is recommended you not use mod_php and keep the box unchecked so that you can use the latest, better-performing Apache 2.4.

PHP Libraries

Not using Xdebug? Still pounding out var_dump() and print_r() and echo?
Xdebug and You: Why You Should be Using a Real Debugger

CLI debugging will be automatically available. Simply run $ xdebug foo.php!

Follow instructions here to setup PHPStorm to listen for a CLI connection. Other IDEs should be similar.

It is highly recommended not installing Xhprof on production servers.

Logs will be available from http://<ip_address>/xhprof/xhprof_html.
The IP address is the one you chose here.

Click here for instructions

WP-Cli requires PHP or HHVM, and Composer.

Drush requires PHP or HHVM, and Composer.

HHVM Quick Settings

If you install HHVM, you cannot install PHP.

This will install the nightly release of HHVM. If you want to test out Hack, you must choose this option!


HHVM will run in FastCGI mode. In short: it will use Apache or Nginx (whatever you have chosen) so all your htaccess and redirect rules should continue working as normal. Only instead of using the official PHP engine, HHVM will be used.

Ruby Quick Settings

Ruby 1.9.3 is already installed in PuPHPet boxes using RVM. It is set as the system default version.

To add Gems to the installed 1.9.3, choose it from the list below.

Choosing to install a lower version and setting it as default may break things, so proceed with caution.

NodeJS Quick Settings

To install a specific version, use {package}@{version}. ex: express@4.10.4 . For latest just use {package}.

Python Quick Settings

Debian and Ubuntu come with Python 2.7, and CentOS comes with Python 2.6 out of the box.

Any extra Python versions you choose will be installed using pyenv as system installations, not user installations.

All extra Python versions require compiling. Choose sparingly - each additional version will add extra time to the initial $ vagrant up!

To install a specific package version, use {package}@{version}. ex: Django@1.6.5. For latest just use {package}.

MySQL Quick Settings

If you install MySQL, you cannot install MariaDB.


It is highly recommended not installing Adminer on production servers.

The preferred way to connect to your database is using a dedicated application like Sequel Pro (OS X), HeidiSQL (Windows), and MySQL Workbench (Cross Platform).

Connect using SSH tunnel, username vagrant and SSH key generated at puphpet/files/dot/ssh/id_rsa. This key is generated after your initial $ vagrant up!

If you want to assign a user to multiple hosts or databases, simply create more databases and type in the same username and password. Only the password for the first entry will be considered, but all fields must be completed!

MySQL Create User & Database

Important! This cannot be blank!

PostgreSQL Quick Settings



It is highly recommended not installing Adminer on production servers.

The preferred way to connect to your database is using a dedicated application like Valentina Studio (OS X) and pgAdmin (Cross Platform).

Connect using SSH tunnel, username vagrant and SSH key generated at puphpet/files/dot/ssh/id_rsa. This key is generated after your initial $ vagrant up!

If you want to assign a user to multiple databases, simply create more databases and type in the same username and password. Only the password for the first entry will be considered, but all fields must be completed!

MariaDB Quick Settings

If you install MariaDB, you cannot install MySQL.



It is highly recommended not installing Adminer on production servers.

The preferred way to connect to your database is using a dedicated application like Sequel Pro (OS X), HeidiSQL (Windows), and MySQL Workbench (Cross Platform).

Connect using SSH tunnel, username vagrant and SSH key generated at puphpet/files/dot/ssh/id_rsa. This key is generated after your initial $ vagrant up!

If you want to assign a user to multiple databases, simply create more databases and type in the same username and password. Only the password for the first entry will be considered, but all fields must be completed!

MongoDB Quick Settings

If you want to assign a user to multiple databases, simply create more databases and type in the same username and password. Only the password for the first entry will be considered, but all fields must be completed!

Redis Quick Settings

SQLite Quick Settings


It is highly recommended not installing Adminer on production servers.

The preferred way to connect to your database is using a dedicated application like Valentina Studio (OS X), Sqliteman (Windows/Linux), SQLite Administrator (Windows), and SQLite Manager (FireFox).

Connect using SSH tunnel, username vagrant and SSH key generated at puphpet/files/dot/ssh/id_rsa. This key is generated after your initial $ vagrant up!

MailCatcher Quick Settings

MailCatcher will be available at http://{SERVER_IP_ADDRESS}:{HTTP_PORT}

It is highly recommended not installing Mailcatcher on production servers.

Minimum port number is 1000


Per this issue Mailcatcher seems to have a bug where you can define your email's from value either inline in your code, or as header values.

If you send email like mail('to@email.com', 'the subject', 'the message', null, 'from@email.com'); then choose Inline above. Otherwise, choose Headers.

Beanstalkd Quick Settings

It is highly recommended not installing Beanstalk Console on production servers.

RabbitMQ Quick Settings

Apache Solr

Minimum port number is 1000

Solr is the popular, blazing-fast, open source enterprise search platform built on Apache Lucene. Learn about Apache Solr.

Solr will be available at http://{SERVER_IP_ADDRESS}:{HTTP_PORT}/solr


Great! Now what?

  1. Extract the downloaded zip file
  2. Open a terminal window and go to the extracted folder
  3. Run $ vagrant up and go grab a coffee

Read the instructions!

After you run $ vagrant up you'll get a list of instructions. Please read them if you have any questions or problems! They will answer most of the frequently asked questions. If you open an issue on the github page, MAKE SURE TO PASTE YOUR config.yaml CONTENTS! I cannot help if I do not have this information! In fact, I will ignore your ticket until you add it!

The config file

Everything in your VM is controlled via the puphpet/config.yaml file. Here, you can choose which packages you want installed and change the settings for many things.

If you change anything, you can have it take effect within your virtual machine by running $ vagrant provision. If you make changes before you actually spin up your vm, the changes will be applied on your first $ vagrant up.

Follow on Twitter

New features are added all the time. The best way to keep up to date is to follow @puphpet!