PHP Vagrant box

Auteur Twisted Bytes op 15 December 2015

Wij bij Twisted Bytes zeggen vaak dat we het leven van developers makkelijker willen maken. Dat doen we onder andere door goede servers te leveren die doen wat ze moeten doen zonder developers lastig te vallen. Maar voordat code op een server staat moet het ook gemaakt en getest worden. Dat gebeurt vaak met een lokale ontwikkelomgeving zoals een LAMP-stack of met een Vagrant box. In deze blog publiceren wij onze Vagrant box die zo goed als gelijk is aan de omgeving die je zal vinden op een van onze servers.

Ideaal om site en applicatie ontwikkeling mee te doen. En omdat het ontwikkelaars Vagrant box is, hebben we wat extra tools toegevoegd zoals xdebug, xhprof en mailcatcher.

 

Vagrant introductie

We willen niet teveel tekst besteden aan Vagrant zelf maar meer aan onze box. Over Vagrant zelf is veel op internet te vinden. Het is namelijk een populaire tool. Om te beginnen is het goed om eerst naar de site zelf te gaan: https://www.vagrantup.com/. Verder is het goed om de “getting started” en de “Why Vagrant” door te nemen.

Vagrant is een tool om een image van een virtuele machine eenvoudig in te zetten voor ontwikkel projecten. Het lijkt op een lokale installatie van een volledig werkende webserver installatie met PHP, MySQL/MariaDB en Apache. Alleen installeer je dat allemaal niet lokaal op Windows, Mac of Linux, maar wordt een virtuele machine gestart waarin die installatie aanwezig is. Dat scheelt een boel installeren en je krijgt een consistente configuratie tussen jou, je collega’s en de hosting. Een Vagrant virtuele machine wordt een Vagrant box genoemd.

Het handige van Vagrant is dat je de bestanden waar je mee werkt op je eigen computer hebt staan en via gedeelde directories tussen de Vagrant box en je eigen computer worden de bestanden in de virtuele machine gebruikt. Dat gebeurt met “synced_folders”.

Elk project heeft zijn eigen Vagrant box, dus je kan eenvoudige meerdere Vagrant boxen naast elkaar actief hebben.

Vagrant bestaat uit 2 delen: Vagrant zelf en een virtuele machine. De virtuele machine is over het algemeen VirtualBox. Beide moeten geïnstalleerd worden. Installatie van VirtualBox wordt hier uitgelegd: https://www.virtualbox.org/wiki/Downloads. Installatie van Vagrant zelf wordt hier uitgelegd: https://www.vagrantup.com/downloads.html. Onze Vagrant werkt (op dit moment) alleen met VirtualBox. Als je een andere provider nodig hebt horen we het graag.

 

Installatie & setup

Er zijn al veel Vagrant boxen te vinden. En veel zijn ook goed bruikbaar. Maar de meeste zijn algemeen en niet gelijk aan de hostingomgeving waar de site op komt te draaien. En die verschillen kunnen enorm vervelend zijn wanneer een site online geplaatst wordt. Een andere versie van PHP of een bepaalde library kan enorm veel problemen geven.

Daarom hebben we een Vagrant box gemaakt die qua software gelijk is aan onze standaard PHP hosting omgevingen. De directory structuur van de site is ook gelijk, zie onze vorige blog. Waar die directory staat is voor het gemak iets anders, maar in de praktijk heeft dat geen grote gevolgen.
Vagrant gebruiken, nadat het geinstalleerd is, is eenvoudig. Plaats een Vagrantfile in directory waar de site staat en voer het volgende commando uit: “vagrant up”. Daarna wordt de Vagrant box gedownload en opgestart.

De Vagrantfile voor onze box is de volgende:

# -*- mode: ruby -*-
# vi: set ft=ruby :

Vagrant.configure(2) do |config|
   config.vm.box = "twistedbytes/webserver"

   config.vm.network "private_network", ip: "192.168.50.100"
   # Create a forwarded port mapping which allows access to a specific port
   config.vm.network "forwarded_port", guest: 80, host: 8080, host_ip: '127.0.0.1', auto_correct: true
   config.vm.network "forwarded_port", guest: 3306, host: 3306, host_ip: '127.0.0.1', auto_correct: true
   # for mailcatcher
   config.vm.network "forwarded_port", guest: 1080, host: 1080, host_ip: '127.0.0.1', auto_correct: true

   config.vm.synced_folder "docroot",         "/data/site/docroot",   create: true, owner: 'defaultsite', group: 'defaultsite'
   config.vm.synced_folder "other/logs",      "/data/logs",           create: true, owner: 'defaultsite', group: 'defaultsite'
   config.vm.synced_folder "other/private",   "/data/private",        create: true, owner: 'defaultsite', group: 'defaultsite'

   config.vm.provision "shell", run: 'always', inline: <<SCRIPT
       /usr/local/bin/autorun.sh
       # systemctl restart mysql
SCRIPT

end

Een korte uitleg van wat hier staat:

  • config.vm.box. Dat is onze box.
  • config.vm.network. Deze staat ingesteld op een IP in het 192.168.50.X netwerk. Dit zorgt ervoor dat je lokale computer het ip 192.168.50.1 krijgt. En dat IP wordt gebruikt door xdebug om een connectie naar de IDE zoals PHPStorm of Eclipse te openen.
    • Je site is daarmee ook op dat ip adres, 192.168.50.100, bereikbaar: http://192.168.50.100/.
    • Als je meedere Vagrant boxen naast elkaar actief hebt, hou er dan rekening mee dat je het IP aanpast naar een andere nummer in de zelfde range, bijvoorbeeld 192.168.50.101 .
  • De forwarded ports. 80, 3306 en 1080. Voor poort 80 betekent dat de webserver ook op je localhost IP bereikbaar is: http://localhost:8080/.
    • De poorten 3306 en 1080 zijn voor de MariaDB server en Mailcatcher: http://localhost:1080/.
    • Als je meerdere boxen tegelijk actief hebt, worden de poorten automatisch naar een andere vertaald. Vaak in de 22XX range. In dat geval even opletten bij het opstarten.
  • De syned_folders. Die zorgen ervoor dat je lokale directories gesynced worden met directories in de Vagrant. De configuratie zoals het hier staat verwacht een docroot directory is je huidige project. Later hier meer over.
    • De 2 anders synced_folders, logs en private werken eigenlijk net andersom. Die zorgen ervoor dat de bestanden die op de server gemaakt worden in je project komen. Dat maakt het eenvoudig om de web en php logs te bekijken.
  • Als laatste het provision script. Dit wordt elke keer uitgevoerd als de box gestart wordt met “up” en “reload”. Dit voert wat scripts uit om de directory structuur van de hosting in een goede staat te houden en daarna worden Apache en PHP herstart.

 

Directory structuur, vorige blog

In een vorige blog hebben we het gehad over onze directory structuur. Daar is uitgebreid behandeld waarom we die structuur hebben en hoe die te gebruiken is. Deze Vagrant box heeft een gelijke structuur. Alleen is de directory niet in /var/www/vhost/TBXX-XXX/<sitename> geplaatst, maar in /data. Dat is gedaan om het eenvoudig te houden voor een single-purpose box.

Elke site heeft een docroot waar de webserver de bestanden zoekt. Wij zijn ervan uitgegaan (...) dat het een aparte directory is in het project. Maar als dat niet zo is, dan kun je “docroot” vervangen voor “.” of “public” of wat je ook maar gebruikt. Als je meer directories hebt, zoals een vendor directory naast de docroot directory, dan heb je 2 opties.

  1. die ook sharen, gelijk aan de docroot en die dan naar “/data/site/vendor” laten verwijzen
  2. de directory docroot noemen en je hele project directory naar de site directory laten verwijzen: ".", "/data/site"

Daarmee wordt je hele project directory in Vagrant gekoppeld aan de /data/site directory.

/data
├── logs
│   ├── php
│   │   └── php-slow.log
│   │   └── php-error.log
│   └── web
│       ├── httpd_access.log
│       └── httpd_error.log
├── private
│   ├── php-append.php
│   ├── php-prepend.php
│   ├── databases.ini
│   ├── php-sessions
│   └── php-tmp
├── site
│   └── docroot


Functionaliteit

De Vagrant box heeft als basis functie natuurlijk lokale PHP site en applicatie ontwikkeling. Maar de box zelf heeft een aantal extra functies die bij development handig zijn.

De standaard functies die aanwezig zijn:

  • PhpMyAdmin: http://localhost:8080/pma/
  • composer installatie in /usr/local/bin/composer
  • wp-cli installatie in: /usr/local/bin/wp
  • sassc installatie in: /usr/local/bin/sassc
  • standaard PHP 5.6 actief.

De extra functionaliteit werken we wat uitgebreider uit.

 

PHP5 en PHP7 switch

Omdat PHP7 net uit is hebben we PHP7 toegevoegd aan onze Vagrant box. Standaard wordt nog PHP 5.6 gebruikt, maar je kan eenvoudig switchen tussen de 2 verschillende versies met een commando. Daardoor kan getest worden of code goed werkt met PHP7.

Het commando moet als root uitgevoerd worden in de Vagrant box. Dat kan door in te loggen en vervolgens de PHP versie te switchen.
# in dezelfde directory waar ook de Vagrantfile staat:

> vagrant ssh

> sudo su # om root te worden
> /usr/local/bin/php-version-switcher.sh defaultsite 5 # om php 5 te gebruiken
> /usr/local/bin/php-version-switcher.sh defaultsite 7 # om php 7 te gebruiken

We hebben deze functie net gemaakt en is nog niet in productie op een server gebruikt, maar het is mogelijk dat ook op een server beschikbaar te krijgen.

 

Mailcatcher

Mailcatcher is een programma wat de e-mail die normaal naar een e-mail adres gestuurd zou worden op te vangen en weer te geven in de browser. Zoals het in een webmail eruit zou zien. Dit is ideaal voor test servers zodat je nooit het risico loopt om per ongeluk test e-mails naar een klant of gebruiker te sturen. Zie ook: http://mailcatcher.me/.

We hebben dit programma toegevoegd aan onze Vagrant. En op zo’n manier dat het helemaal transparant is voor de applicatie. Je kan zonder problemen e-mail sturen en in plaats dat het bericht internet op gaat wordt het afgevangen en in mailcatcher weergegeven.

Mailcatcher is bereikbaar op http://localhost:1080/ of op http://192.168.50.XX:1080/

 

Xdebug

Xdebug is de standaard methode van PHP code debuggen. Het is echter een lastig systeem om te installeren en te configureren. Daarom hebben we hem toegevoegd en geconfigureerd. De configuratie is getest met PhpStorm en Eclipse. Het is wel belangrijk dat het IP nummer van de host 192.168.50.1 is. En daarom moet de regel “config.vm.network "private_network", ip: "192.168.50.100"” in de Vagrantfile staan.

Voor de configuratie verwijzen we naar plekken waar het al goed beschreven is. De installatie bestaat uit 2 delen. Een plugin voor de browser om een cookie in het request te zetten waarop xdebug reageert door een debug sessie te beginnen en contact te maken met 192.168.50.1:9000. En de IDE moet geconfigureerd worden om te luisteren naar binnenkomende debug sessies.

 

XHprof

XHprof is een profiler van PHP code. Ook hier is de installatie wat meer werk, maar het voordeel is groot. En omdat wij het hebben toegevoegd is het heel eenvoudig geworden om te gebruiken.

Maar waarom zou je het gebruiken? Profilen helpt om de snelheid van je code inzichtelijk te maken door van elke functie bij te houden hoe lang het uitvoeren duurde en hoe vaak de functie aangeroepen wordt. Dit kan helpen om de trage delen uit de code te identificeren en op te lossen. Zo is het eenvoudig om je applicatie sneller te maken door die trage delen te verbeteren. Er is meer over te lezen op deze blog:

Je hoeft niets te configureren of te installeren zoals het in die blog genoemd wordt. Wij hebben dat al gedaan.

Het enige dat je moet doen is de php-prepend.php en php-append.php in de ~private/ directory aanpassen om de ene of de andere profile gui te gebruiken. Er zijn namelijk 2 verschillende geïnstalleerd: xhprof en xhprof.io.

Ze zijn te gebruiken op:

 

Overige functionaliteit

Naast de extra functies van de Vagrant box zijn er standaard tools te gebruiken.

PhpMyAdmin is geinstalleerd en is te gebruiken op http://localhost:8080/pma. Er kan ingelogt worden met root zonder wachtwoord. Of met de de standaard gebruiker defaultsite met defaultsite als wachtwoord. Als er met een lokale SQL client gewerkt wordt kan er connectie met de database gemaakt worden op poort localhost:3306 of 192.168.50.100:3306.

PHP zonder composer kan bijna niet meer. Daarom is composer ook aanwezig. Hiervoor moet wel ingelogt worden in de vagrant:

> vagrant ssh
Last login: Sun Nov 29 12:26:35 2015 from 10.0.2.2
Welcome to your Vagrant-built virtual machine.

Use command "sudef" te become user defaultsite, to use composer and other commandline tools

[vagrant@localhost ~]$ sudef
defaultsite@localhost /data> cd site/docroot/
defaultsite@localhost /data/site/docroot> composer install
Loading composer repositories with package information
Installing dependencies (including require-dev) from lock file
Nothing to install or update
Generating autoload files
defaultsite@localhost /data/site/docroot>

Als laatste is ook WP-cli geinstalleerd. Dit is een command line tool om standaard WordPress taken uit te voeren. Voor details: http://wp-cli.org/. Deze is net als composer te gebruiken door in de vagrant in te loggen naar de defaultsite user.

 

Tot Slot

We hopen dat met deze informatie het lokaal ontwikkelen van PHP code makkelijker wordt. Met de toevoeging van xhprof en xdebug hebben we ook 2 krachtige tools eenvoudig te gebruiken gemaakt.

We horen graag opmerkingen en eventuele verbeter mogelijkheden. Dus neem contact op bij vragen en opmerkingen!