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?

Latest news

Get started right away. It's free!

About This Project

A little bit of history.

Annyong!

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: 192.168.56.101 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 common.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/hieradata/common.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: 192.168.56.101 puphpet.dev www.puphpet.dev

Local VM Details

Deploy your virtual machine on your local PC.

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.

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.
The hostname the machine should have.
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
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.
Add another shared folder pair
System Packages

Rackspace Server Details

Spin up your virtual machine on Rackspace Cloud.

System Packages

Linode Server Details

Spin up your virtual machine on Linode.

System Packages

SoftLayer Server Details

Spin up your virtual machine on SoftLayer.

System Packages

Amazon Server Details

Spin up your virtual machine on Amazon EC2.

System Packages

Google Server Details

Spin up your virtual machine on Google Compute Engine.

System Packages

Digital Ocean Server Details

Spin up your virtual machine on Digital Ocean.

System Packages

Ikoula Server Details

Spin up your virtual machine on Ikoula Cloud.

System Packages

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!):

Local Deployment Target
Users & Groups

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

System Packages
Locale

Locale

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.
en_GB.UTF-8 UTF-8 ×
en_US.UTF-8 UTF-8 ×
Users & Groups
Firewall Rules

Firewall

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
Locale
Cron Jobs

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
Firewall Rules
Custom Files

Custom Files

Information on dotfiles and custom executable bash files.

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!

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.

Cron Jobs
Nginx

Nginx Web Server

Setup Nginx. An alright webserver.

Information here.
Information here.
Virtual Host
Don't forget to update your computer's hosts file!
Separated by comma.
www.awesome.dev ×
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.
index.html ×
index.htm ×
index.php ×
Value in megabytes (1m = 1 megabyte). 0 = disabled
Location
More information.
More information.
$uri ×
$uri/ ×
/index.php$is_args$args ×
More information.
More information.
More information.
name value, separated by comma.
Location
More information.
More information.
$uri ×
$uri/ ×
/index.php$is_args$args ×
More information.
More information.
More information.
name value, separated by comma.
SCRIPT_FILENAME $request_filename ×
APP_ENV dev ×
Add a vhost location
Add an Nginx vhost Add an Nginx proxy upstream Add an Nginx proxy
Custom Files
Apache

Apache Web Server

Setup Apache. Not as hip as Nginx.

Nginx
PHP

PHP

Install PHP system-wide and choose modules and settings.

PHP is a toy language accidentally chosen to power some of the largest websites in the world. You probably want Ruby?

PHP 7.0 is from NIGHTLY builds. Do not use in production! Only Ubuntu 14.04 x64 is currently supported.

Pear, PECL, modules are NOT supported! Some packages requiring PHP modules may not work. Proceed at your own risk.

All settings added to a single INI file.
display_errors = On ×
error_reporting = -1 ×
session.save_path = /var/lib/php/session ×
date.timezone = UTC ×
Make sure to define pid.
error_log = /var/log/php-fpm.log ×
If you've chosen CentOS, Some modules come pre-installed: curl, imagick, memcached, sqlite. Don't choose these here.
cli ×
intl ×
mcrypt ×
Modules to be installed via PEAR.
Modules to be installed via PECL.
pecl_http ×
Add FPM Pool
Make sure to define prefix and security.limit_extensions.
prefix = www ×
user = www-user ×
group = www-data ×
listen = 127.0.0.1:9000 ×
security.limit_extensions = .php ×
Add another FPM pool

Libraries

A free account is required to use this plugin. Create your account here.

Read the Getting Started docs here.
Apache
Ruby

Ruby

Configure Ruby versions and gems.

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.

Add another Ruby version
PHP
Python

Python

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
Ruby
Node.js

Node.js

Install Node.js and add Npm packages

It's callbacks all the way down!
Python
HHVM

HHVM

Install HHVM and choose modules and settings.

HHVM is a new open-source virtual machine designed for executing programs written in PHP. Learn about HHVM.
Node.js
MySQL

MySQL

Install MySQL and create users and databases.

Assign a password to the root user. Database will only be installed when a password is entered here.

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.
ALL ×
Add another grant
HHVM
MariaDB

MariaDB

Install MariaDB and create users and databases.

MySQL
PostgreSQL

PostgreSQL

Install PostgreSQL and create users and databases.

MySQL
MongoDB

MongoDB

Install MongoDB and create users and databases.

PostgreSQL
Redis

Redis

Install Redis.

MongoDB
SQLite

SQLite

Install SQLite and create users and databases.

Redis
MailCatcher

MailCatcher

Install MailCatcher.

SQLite
Beanstalkd

Beanstalkd

Install Beanstalkd.

MailCatcher
RabbitMQ

RabbitMQ

Install RabbitMQ and create users.

Beanstalkd
Elastic Search

Solr

Install Solr.

Elastic Search
Create Archive

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!