Get started with Matomo development – Matomo Puppet Module + Vagrant

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

The Matomo Puppet module makes it very easy to start with Matomo development or to give Matomo 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 Matomo installation process.

What’s Vagrant?

Vagrant 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 = "http://files.vagrantup.com/precise64.box"

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 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 Matomo QA, we are planning to use Vagrant and Puppet to easily test Matomo 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 https://github.com/piwik/piwik-dev-environment.git 
   $ 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 Matomo Puppet Module

Using the Matomo Puppet module makes starting Matomo in a new environment a very easy process. The Matomo Puppet Module is available on Github. It’s a first working version. The module will install everything you need in order to work with Matomo. 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 Matomo development as well as an Apache vhost. Your Matomo installation will be available under “http://apache.piwik”. Don’t forget to update your local hosts file.

We really appreciate your help and feedback!

FAQ

Where are the Matomo files located?

The Matomo 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 192.168.33.10 and 192.168.33.11 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.

config.vm.boot_mode='gui'

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.