upload your config

Welcome to PuPHPet

A simple GUI to set up virtual machines for Web development.

Easily share with friends and coworkers

Everything is controlled via a simple-to-read YAML file, and comes packaged in a small ZIP archive.

Deploy to any server in the world!

Native support for Rackspace, Digital Ocean, Linode, and more! Free plugin to deploy to any SSH-enabled server.

Open sourced, MIT licensed.

Want to help out?

Important Notices

Latest news

Get started right away. It's free!

About This Project

A little bit of history.


My name is Juan. I like building things people love to use. I hope you enjoy PuPHPet!

What's all this about, then?

This is a gui configurator for the Vagrant automation tool. It uses Puppet as the provisioning backend.

What is Vagrant/Puppet and why should I care?

I used to develop locally on a virtual machine. In fact, I wrote a length, detailed step-by-step tutorial (Setting Up a Debian VM, Step by Step) that goes through the process from beginning to end on setting up a Debian VM. It works wonderfully, and I love editing my files on my daily OS (Windows back then, OS X now), and running the applications within a proper environment.

The first problem is obvious: there is a lot of setup involved. Just look at that tutorial. From beginning to end it may take upward of an hour to do the whole process! What happens if you mess up somewhere? You have to start all over!

The next problem comes after you've got the VM up and running. I had to be very careful when making changes to the system, because I was afraid of screwing it up and having to either restart it from scratch or googling trying to undo the damage.

The third large issue is, how to properly share my environment with other developers? Do I really want to upload this multi-GB file? That's a big pain in the butt!

Vagrant and Puppet takes care of all these issues, and more, for you!

The Debian tutorial can be written once, and run multiple times. I no longer have to worry about damaging my VM environment - if I screw something up I can destroy it, re-run Vagrant, and within 3 minutes I have a fully working environment once again! To share, I simply point developers to my Github repo where they download appx. 50KB of text files and run Vagrant on their own machines! Awesome!

Want some more details?

I wrote some fairly in-depth introductions to both Vagrant and Puppet:

How do I know you won't give me some virus?!

This app is completely open-sourced

You can always clone it locally and run it off of your own machine to make sure there is nothing shady going on behind the scenes.

Please fork me!

I have been using Puppet/Vagrant for a little under two weeks as of Monday, May 13. If you are a Vagrant or Puppet maestro, I would love it if you could contribute some of your knowledge by submitting pull requests! If you don't know either Vagrant or Puppet you can still be kick-ass and submit requests for other things!

Some FAQs

¡Ay, caramba! ¡No me gusta!

How do you pronounce PuPHPet?

The p is silent.

What do I need to get started with PuPHPet?

There are a few pre-requisites before you can begin your virtualized journey.

First, you must install the necessary tools. They're easy to get and will only take a minute:

Second … well, that's all you need, really.

I downloaded the zip file, now what?

Using the terminal, or cmd line, cd into your extracted directory and run $ vagrant up. This will kick-off the initial process.

Vagrant will download the box file, which can take a few minutes. It will only have to do this once, even if you create separate environments later on.

Then, it will hand control over to Puppet which will begin setting up your environment by installing required packages and configuring tools as desired.

You will then be able to ssh into your new box with $ vagrant ssh. You can also access any virtual hosts you created by editing your hosts file and creating entries for the Box IP Address and Server Name you provided during configuration (ex: puphpet.dev www.puphpet.dev). To shut down the VM, simply run $ vagrant halt. To start it back up run $ vagrant up again. Destroy it with $ vagrant destroy.

Further customizations with config.yaml

I have completely rewritten PuPHPet to take advantage of a built-in configuration tool for Puppet called Hiera. Simply look inside your downloaded folder and open puppet/config.yaml. This is the magical file that controls everything!

For example, if you want to have more OS-level packages installed (like vim, curl, git, etc) simply add more packages to server.packages. The exact same process exists for apache.modules.

To create a new Apache or Nginx vhost, simply copy/paste the one you may have created and customize to your needs.

Attention: if you see some sections with non-sensical array keys (ex: rIreAN33ne2a) that means they have to be unique! If you copy/paste to add new settings, you must ensure you change this unique key to some other random string! Bad Things Will Happen if you don't.

Learn you some Vagrant

You may want to learn the basics of Vagrant CLI by going here. You really only need to learn the very basics - that is what I created this app for!

How do I update my hosts file?

You will need to open and edit your hosts file with a text editor like notepad, sublime_text, nano, etc. The location of the hosts file varies by operation system.

Windows users could look here: c:\windows\system32\drivers\etc\hosts

Linux and Mac OSX users could look here: /etc/hosts.

Example Entry: puphpet.dev www.puphpet.dev

Download Your Customized Archive

Your server is ready to be spun up!

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!

Follow on Twitter

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

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.

Custom config file

You can create a custom config file at puphpet/config-custom.yaml to override anything that you have defined in puphpet/config.yaml. This file is ignored by Git by default. Simply copy the structure from config.yaml and replace the values you want. You can also create completely new keys to define functionality not present in PuPHPet by default!

Deploy your virtual machine on your local PC.
Free! Not as performant as VMWare. Free! Download Virtualbox here.
More performant than VirtualBox. Requires purchase of VMWare Fusion (affiliate link - help support this free service) and purchase of Vagrant VMWare Fusion Plugin.
More performant than VirtualBox. Requires purchase of VMWare Workstation (affiliate link - help support this free service) and purchase of Vagrant VMWare Workstation Plugin.
More performant than VirtualBox. Requires purchase of Parallels Desktop 9 (affiliate link - help support this free service) and installing the free Vagrant Parallels Plugin.

Choose the operating system for your VM. It will be downloaded the first time you run Vagrant. More information may be found here.

Note: Listed are the PHP installs that we have confirmed as working for their respective operating system. You are welcome to attempt to install higher if you'd like, but we cannot guarantee it will work. In fact in most cases it won't.

This is the ID used within the Vagrantfile. It is only used for your internal identification.
The hostname the machine should have. This answer lists all valid characters.
IP address to use for accessing the VM. This is the IP address you will need to enter into your hosts file for every virtual hosts you create later on.
Memory to assign to VM in megabytes (only integers)
Number of CPUs to assign to VM (only integers)
Forwarded Ports
Port on Host to forward to VM. More information.

Port on VM to accept from Host. More information.

This port is automatically added to iptables

Add another port pair
Add another machine
Shared Folders

Path your files are stored on host machine, more information.

Windows users: You must use forward-slash c:/dev/vagrant/webroot or double back-slash c:\\dev\\vagrant\\webroot

Path your hosts' files are mounted on guest machine, more information.
This is the slowest option of all. More information.
NFS is highly recommended for OSX and Linux! Make sure to install the vagrant-bindfs plugin with $ vagrant plugin install vagrant-bindfs.

More information about NFS, and more information about vagrant-bindfs
Windows only, and highly recommended. More information.
If you are on Windows you need rsync installed. The simplest way is to use Cygwin and install it through there. Alternatively, you can install rsync separately and add it to your PATH. More information.
Add another shared folder
Spin up your virtual machine on Rackspace Cloud.
Spin up your virtual machine on Linode.
Spin up your virtual machine on SoftLayer.
Spin up your virtual machine on Amazon EC2.
Spin up your virtual machine on Google Compute Engine.
Spin up your virtual machine on Digital Ocean.

System Packages

Install 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 users & groups to server.

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}.


Set system locale.

Setting a locale currently only works on Debian and Ubuntu!

Per the Debian Locale wiki it is highly recommended to leave your default locale empty.
Add as many as you want to support here.


Open select ports.

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.
Add another firewall rule

Cron Jobs

Add 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.

Add another cron job

Custom Files

Information on dotfiles and custom executable bash files.


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!

Custom Bash 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-always-unprivileged, puphpet/files/exec-once, puphpet/files/exec-once-unprivileged, puphpet/files/startup-always, puphpet/files/startup-always-unprivileged, puphpet/files/startup-once and puphpet/files/startup-once-unprivileged folders.

Files are executed in alphabetical order, and filenames must end in .sh. 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 *-unprivileged are run as the default user while the other ones area run using sudo. Files within *-unprivileged are run after all other files on the same running order as "privileged" files.

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 and/or /.puphpet-stuff/exec-once-unprivileged-ran files 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 and/or /.puphpet-stuff/startup-once-unprivileged-ran files and re-run Vagrant.

Setup Nginx. An alright webserver.
Virtual Host
Separated by comma.
Location of your site's index.php file, or other landing page.
80 for normal browsing, if you choose another append it to the URL in your browser, eg: http://awesome.dev:1337
The last file should be the accessor to your PHP script or front controller.
Value in megabytes (1m = 1 megabyte). 0 = disabled
Add a vhost rewrite
Enables directory listings.
Designates location as internal-only. See nginx documentation for more details.
name value, separated by comma. Unlike Apache, each variable must have a value.
name value, separated by comma. More information.
name value, separated by comma. More information.
Add a location rewrite
Enables directory listings.
Designates location as internal-only. See nginx documentation for more details.
name value, separated by comma. Unlike Apache, each variable must have a value.
name value, separated by comma. More information.
name value, separated by comma. More information.
Add a location rewrite
Add a vhost location
Add an Nginx vhost Add an Nginx proxy upstream Add an Nginx proxy
Setup Apache. Not as hip as Nginx.

Let's Encrypt

Let’s Encrypt is a new Certificate Authority.

The domains chosen below must match up with the domains you have selected to use Let's Encrypt SSL certificates in either the Nginx or Apache tabs!

A cron job is made to automatically renew your certificate(s) once a month.

This email address will be displayed as the admin for your generated certificates

Add another domain
PHP is a toy language accidentally chosen to power some of the largest websites in the world. You probably want Ruby?
CentOS 6, Ubuntu 14.04.
CentOS 6, Debian 7, Ubuntu 14.04.
Available on all distros.
CentOS 6, Debian 7, Ubuntu 12.04.
Composer will be available as a system service:
$ composer
All settings added to a single INI file.
Make sure to define pid.

If you've chosen CentOS, Some modules come pre-installed: curl, imagick, memcached, sqlite. Don't choose these here.

If you've chosen Ubuntu 14.04 and PHP 7, some modules have been noted as coming pre-installed: mcrypt. Don't choose these here.

Modules to be installed via PEAR.
Modules to be installed via PECL.
Add FPM Pool
Make sure to define prefix and security.limit_extensions.
Add another FPM pool


Configure Ruby versions and gems.

Ruby version via RVM
Set this as system-wide default version. Don't set more than one version as default.
The best way to manage a Ruby application's gems. More information
Choosing Ruby <= 1.9.2 requires compiling. This will take time! All others have binaries available.
To install a specific version, use {gem}@{version}. eg: rails@4.1.3. For latest just use {gem}.
Add another Ruby version


Configure Python versions and packages.

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}.

eg: Django@1.6.5. For latest just use {package}.

All valid Packages list.

Add another Python version
HHVM is a new open-source virtual machine designed for executing programs written in PHP. Learn about HHVM.
Assign a password to the root user. Database will only be installed when a password is entered here.
It is highly recommended not installing Adminer on production servers.

If installed it will be available from http://{SERVER_IP_ADDRESS}/adminer.

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!

Create User
Enter {username}@{host} for a specific host. If no host is defined, eg: {username}", it will automagically be converted to {username}@localhost
Password is required for each user.
Add another user
Create Database
Optional. Make sure this file is inside the VM, or is inside a shared folder before running $ vagrant up
Add another database
Additional Grant
User must be defined in section above!
Can be *.* for all databases/tables, {database}.* for all tables in a specific database, or {database}.{table} for a specific table in a specific database.
Choose "All" or a mix of the others.
Add another grant
MariaDB is a drop-in replacement for MySQL. It is highly recommended you use MariaDB instead.
RabbitMQ is not available on Debian Wheezy. librabbitmq-dev is too old.

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

Learn about Apache Solr.