Today, we’re announcing the Piwik-Puppet module including a Vagrant configuration for Piwik!
This article is written for technical people, free software enthusiasts, bleeding edge geeks, and the Piwik Hacking Community, and anyone who likes to play with awesome, powerful, modern free software technologies!

The Piwik Puppet module makes it very easy to start with Piwik development or to give Piwik a try in your local environment. By entering only one command a whole virtual machine will be created and configured for you. Afterwards, you can proceed with the very simple Piwik installation process.

What’s Vagrant?

VagrantVagrant makes it possible to have lightweight, reproducible, and portable virtual machines. Such a virtual machine is described in plain text, see this example. For example there are options to configure your network, username, shared folders and more. The most important option is the so called “box url”. The box url describes which base box should be booted when starting the VM.

config.vm.box_url = ""

Once you started this box in Vagrant, your virtual machine will run Ubuntu Precise 64Bit. Now we need to configure and add softwares (webserver, php, mysql, piwik), for which we will use Puppet.

Read this page for more detailed information about Vagrant. A list of all options is available here.

What’s Puppet?

puppet labsPuppet makes sure that all required packages are installed, needed users and files are present, services are running and that all vhosts are configured. The configuration is done in plain text and easy to read:

package { 'curl': ensure => latest } 

This simple example makes sure that always the latest version of curl is installed.

Read this page for more detailed information about Puppet.

Combination of Vagrant/Puppet

As part of Piwik QA, we are planning to use Vagrant and Puppet to easily test Piwik on several platforms and php versions. This is achieved by combining different Vagrant with different Puppet configurations. For example we can pick a Cent OS box instead of an Ubuntu box in combination with our Puppet configuration. Currently, a Ubuntu Precise64 and Precise32 box is available.

Try it!

  1. Install Vagrant + VirtualBox. Both are available for Windows, Linux and Mac OS X.
  2. For Virtual Box to work, you may have to ‘Enable Virtualization’ in your BIOS.
  3. Clone the piwik-dev-environment repositoryfrom Github and update all submodules.
    $ git clone 
    $ cd piwik-dev-environment 
    $ git submodule init 
    $ git submodule update
  4. Execute the command “vagrant up” within the “vagrant/precise64” folder
    $ cd vagrant/precise64 
    $ vagrant up 

    It’ll take some time when executing this command the first time. It’ll download the Precise base box once and install all required packages afterwards.

  5. That’s it: your Virtual Machine is started with everything pre-configured ๐Ÿ™‚

Once your VM is up you can execute the following commands, among others, from your “vagrant/precise64” directory:

$ vagrant ssh 

Vagrant will automatically drop you into a fully functional terminal shell of the previously created VM. Of course you can also connect directly via ssh, putty or something similar.

$ vagrant suspend

This will save the current running state of your virtual machine and then stop it. To resume working again at some other time, simply execute “vagrant resume“.

$ vagrant destroy

Enter this command once you no longer need the VM. It’ll literally delete all traces of the virtual environment off the disk. This saves you disk space. Once you need the VM again, simply execute “vagrant up” again. The cost is that you must wait for a full rebuild when you “vagrant up” again.

The Piwik Puppet Module

Using the Piwik Puppet module makes starting Piwik in a new environment a very easy process. The Piwik Puppet Module is available on Github. It’s a first working version. The module will install everything you need in order to work with Piwik. For example PHP, MySQL, Apache and/or Nginx, Subversion, Git, PHP QA tools like PHPUnit as well as advanced command line tools like Percona Toolkit to perform a variety of MySQL tasks. You’ll find more information in the README.

Simple Example

 class { 'piwik': } 
 piwik::apache { 'apache.piwik': }

This will setup everything you need for Piwik development as well as an Apache vhost. Your Piwik installation will be available under “http://apache.piwik”. Don’t forget to update your local hosts file.

We really appreciate your help and feedback!


Where are the Piwik files located?

The Piwik files are located within the virtual machine. The path is “/var/www/piwik”.

Should the developer install an IDE?

Yes, the developer should install an IDE on his local machine. Most IDE’s do already support SSH, for example PHPStorm. PHPStorm fetches all files from the virtual machine and once you make changes and save a file it automatically copies the changes back to the virtual machine.

Is it possible to use shared folders?

Yes, it is possible. You just have to update your Vagrantfile. Have a look here for more information.

What’s the IP Address of the virtual machine?

The IP Address of the Ubuntu Precise 64-bit box is and for 32-bit box.

What’s the default database username and password?

By default a MySQL user named “piwik” will be created. The password for this user as well as for the root user is “secure”. You can change both the username and password in your local yaml configuration, see step 3 of installation.

Is there a graphical access to the virtual machine?

There is no graphical access to the virtual machine by default. However, you can easily update graphical access by adding the “boot_mode” option to your Vagrantfile, see here.


Where do I get more information about Puppet/Vagrant?

There’s a good blog post about Vagrant Virtualised Dev Environments. I also recommend that you read Getting Started with Vagrant.

Thomas Steur

Thomas is a Lead developer for Piwik. He created and maintains our Piwik Mobile app used by dozens of thousands users every week. Thomas has a passion for making Piwik mobile better and improving the Piwik platform by providing simple APIs and clean code.

Any questions?

Many answers and more information about Piwik You can find here:

We are social

Follow us: