Vagrant for PHP project

Under the impression of article 5 Easy Ways to Get Started with PHP on Vagrant, I want to share my way of using Vagrant for a PHP project.



What I wanted to achieve:

• On the developer's machine, only Vagrant and VirtualBox are installed;
• Virtual machine settings are stored in the project repository, allowing the developer to quickly deploy it, as well as flexibly adjust to the needs of the project and share these settings with team members;

These goals were achieved with the help of Chef-Solo. It turned out a kind of preparation for the creation of new projects based on it, and for the integration of existing projects into it: vagrant-php .





')

The scenario of working with such a project for a new team member is very simple:

1. You need to install Vagrant and VirtualBox , as well as several Vagrant plugins:

   $ vagrant plugin install vagrant-librarian-chef-nochef vagrant-omnibus 

2. Download the project from the repository:

    $ git clone repo path 

3. Copy the Vagrantfile and start the virtual machine:

    $ cd path $ cp .chef/Vagrantfile Vagrantfile $ vagrant up 

Everything, virtualka turned around, packages were installed, the application works!



The “vagrant-librarian-chef-nochef” plugin is intended for downloading external Chef cookbooks and managing their dependencies without installing Chef itself on a local machine. This plugin allows you not to store external cookbooks in your repository, but to load them when you first turn on the virtual machine.



The “vagrant-omnibus” plugin allows you to specify a specific version of Chef, which will be installed in a virtual machine (this allows you to use almost any image with vagrantcloud.com , and also allows you to fix the version of Chef).

What's inside?

• Ubuntu Trusty 14.04 (32 bit, current);
• Nginx (latest version of Nginx PPA);
• PHP 5.6 (from ondrej PPA), Composer;
• Memcached (from the standard Ubuntu repository);
• MySQL 5.5 (from the standard Ubuntu repository);
• PostgreSQL 9.3 (from PostgreSQL PPA).

It should be noted that, if desired, any of these components can be replaced. The concept itself is universal.

How to integrate this environment with your PHP project?

If there is an existing PHP project, then it is necessary to load the project from the repository:

 $ git clone repo path 

If you need to start a new project, you must first create a directory for it:

 $ mkdir path 

Then you need to copy the ".chef" directory to the project directory and make the necessary settings in the ".chef / nodes / 10.2.2.10.json" file (see below for the json-file structure) and ".chef / Vagrantfile".



Now it remains only to copy the file ".chef / Vagrantfile" to the root of the project and start the virtual machine:

 $ cd path $ cp .chef/Vagrantfile Vagrantfile $ vagrant up 

If you create a new project, you need to log in to the virtual machine via SSH under the application user (see below about SSH access), install the project using Composer, and then download the contents of the project from the virtual machine to the local directory:

 $ composer create-project --prefer-dist yiisoft/yii2-app-basic /home/php-app/www 

It is also advisable to add the line "/ Vagrantfile" to the project's ".gitignore" file. This will allow the developer to make local changes to the settings of the virtual machine (for example, to reduce the size of RAM), without reflecting these changes in the VCS.



After that, you should check the operability of the project in a virtual environment, and if the project is operational, then you can commit the project directory (to a new or existing repository).

Ssh access

You can access the virtual machine via SSH in two ways:

• As an administrator:

   $ vagrant ssh 

• As a user, under which the application is deployed:

   $ ssh php-app@10.2.2.10 -i '.chef/files/id_rsa' 

By default, password access is disabled ([“openssh”] [“server”] [“password_authentication”] parameter), therefore, to log in as an application user, use the keys specified in [“php-app”] [[ssh]] [ "Authorized_keys"]. This array lists the full paths to the files on the virtual machine. Since the directory ".chef" is mounted in the directory "/ tmp" of the virtual machine, the paths look like this: "/tmp/.chef/files / ...". By default, the public key is “id_rsa.pub”, the private key for which is right there under the name “id_rsa”.

Directory structure ".chef"

• files / - directory for storing files used in the recipe "php-app" (these files are available inside the virtual machine along the path "/tmp/.chef/files/");
• nodes / - directory for storing virtual machine settings;
• cookbooks / - directory for storing downloaded external cookbooks (automatically created);
• site-cookbooks / - directory for storage of internal cookbooks of the project itself;
• tmp / - temporary directory (automatically created);
• Cheffile - dependencies for internal cookbooks (needed for librarian-chef);
• Cheffile.lock - fixed versions of cookbooks (file is created automatically);
• solo.rb - configuration file for Chef-Solo, launched inside the virtual machine;
• Vagrantfile - a template file with Vagrant settings (this file will be used by other team members as a sample).

The structure of the json file with the settings of the virtual machine

The “run_list” parameter lists the recipes that will be executed when the machine is deployed and the environment is prepared. All other parameters are the settings of the corresponding cookbooks.



In the ".chef / nodes" directory there are several ready-made examples for applications based on the Yii2 framework:

• yii2_advanced.json — settings for expanding the advanced application template Yii2;
• yii2_basic.json - settings for expanding the basic template of the Yii2 application.

The environment itself is in no way tied to Yii2, but these settings can be used as an example.



Cookbook "php-app" is local (located in ".chef / site-cookbooks" and is committed to the project repository) and is designed to deploy the application on the server. It performs the following actions:

1. Creation of a separate system user for the application (parameters [“php-app”] [user ”] and [php-app”] [“group”]);
2. Creating the necessary directories (parameters ["php-app"] ["project_dir"] and ["php-app"] ["log_dir"]);
3. Creation of separate php-fpm pools for the application (parameter ["php-app"] ["php"] ["pools"]);
4. Creating virtual hosts Nginx (parameter ["php-app"] ["vhosts"]);
5. Adding entries to the local hosts file of the virtual machine (parameter [“php-app”] [“hosts”]);
6. Creating databases (parameters ["php-app"] ["mysql"] and ["php-app"] ["pgsql"]);
7. Download the project from the git-repository (if necessary, see the section on the location of the project);
8. Installing Composer and all project dependencies (parameter [“php-app”] [“composer”]);
9. Execution of arbitrary commands (parameter ["php-app"] ["init_commands"]).

This script is described in the file ".chef / site-cookbooks / php-app / recipes / default.rb" and is provided with comments. In the process of developing an application, this scenario may be supplemented by new actions.



If Composer is used in your PHP project, then in the json file you need to fill in the parameter [“php-app”] [“composer”] [“github_auth_token”], otherwise the project dependencies will not be installed due to limitations of the Github API. You can generate this token in your Github account settings.



For a complete list of cookbook settings for php-app, see the ".chef / site-cookbooks / php-app / attributes / default.rb" file.

Setting up the project directory

The location of the project directory in the virtual machine is governed by the parameter [“php-app”] [“project_dir”]. Usually, along with this parameter, you need to change the [“php-app”] [[vhosts]] [“variables”] [“root”] parameter so that the virtual host points to the correct directory.



Options for the location of the project directory:

• The project is located in the general directory (in the "/ vagrant" directory of the virtual machine, equal to the local project directory);
• The project is located outside the common directory (for example, in "/ home / php-app / www").

If the project is located in a shared directory, then the virtual machine works with the same files as the developer.



Disadvantages of this option:

• In the shared directory, all files use the same access mode on the virtual machine side (by default, “777”);
• In the shared directory, the case of file names is not taken into account (if Windows is used on the local machine);
• To create symbolic links in a shared directory, you need to start virtual machines with administrator rights for the local machine (if Windows is used on the local machine);
• If the developer uses Linux on the local machine, then the disk operations with the shared directory will be extremely slow (this problem can be solved by setting up access to the shared directory via NFS in the Vagrantfile).

The location of the project outside the common directory (for example, in "/ home / user / www") allows you to get closer to the conditions of the real server, but also has some drawbacks:

• The developer needs to take care of file synchronization between the local and virtual machine (switching between project branches will also have to be done twice - in the local project directory and inside the virtual machine);
• Local git commits will not be available in the virtual machine.

If the project is located outside the common directory, then in the json-file you need to fill in the parameter [“php-app”] [“git”] [“repository”] to load the project when preparing a virtual machine. To access the repository, the private key specified in [“php-app”] [“ssh”] [“deployment_key”] will be used.



In IDE PhpStorm / IDEA, you can configure the deployment server. In this case, changes to the local project files will automatically be uploaded to the virtual machine.



To do this, you need to add a deployment server (using the “Add” button in the “File - Settings - Deployment” menu) with the following settings (some settings depend on the settings in the json file):

• Type: SFTP
• SFTP host: 10.2.2.10
• Port: 22
• Root path: / home / php-app / www
• User name: php-app
• Auth type: Key pair (OpenSSH)
• Private key file: project_dir / .chef / files / id_rsa
• Passphrase:
• Web server root URL: demo.local
• Deployment path on server: /
• Web path on server: /

Then you need to assign the added server to the default server (using the “Use as Default” button in the “File - Settings - Deployment” menu) and set the value of the “Upload changed files to the default server” parameter to “Always” or “On explicit save action "(in the window" File - Settings - Deployment - Options ").

MySQL server setup

To configure the MySQL server, the external cookbook “mysql” is used, therefore, to change the default settings, you must use the “mysql” key in the json file. By default, the MySQL server is available for external connections via a standard port.



In the [php-app ”] [“ mysql ”] [“ root_connection ”] parameter, you must specify the access parameters for the database administrator. The administrator password is set in the [“mysql”] [“server_root_password”] ​​parameter.

The list of created databases must be specified in the ["php-app"] ["mysql"] ["databases"] key:

 { ... "php-app": [ ... "mysql": { "root_connection": { "host": "127.0.0.1", "username": "root", "password": "" }, "databases": [ { "name": "yii2advanced", "username": "root", "password": "", "encoding": "utf8", "collation": "utf8_general_ci" }, { "name": "yii2_advanced_tests", "username": "root", "password": "", "encoding": "utf8", "collation": "utf8_general_ci" } ] } ... ], ... } 

Setting up a PosgtreSQL server

To set up the PosgtreSQL server, an external cookbook “postgresql” is used, so to change the default settings, you must use the key “postgresql” in the json file. By default, the PostgreSQL server is available for external connections over a standard port.



In the ["php-app"] ["pgsql"] ["root_connection"] parameter, you must specify the access parameters for the database administrator. The administrator password is set in the [“postgresql”] [“password”] ​​[“postgres”] parameter. This password must not be empty.



The list of created databases must be specified in the ["php-app"] ["pgsql"] ["databases"] key:

 { ... "php-app": [ ... "pgsql": { "root_connection": { "host": "127.0.0.1", "username": "postgres", "password": "password" }, "databases": [ { "name": "yii2advanced", "username": "yii2advanced", "password": "", "encoding": "UTF8", "collation": "en_US.UTF-8" }, { "name": "yii2_advanced_tests", "username": "yii2advanced", "password": "", "encoding": "UTF8", "collation": "en_US.UTF-8" } ] } ... ], ... } 

Setting up debugging in PhpStorm / IDEA

To be able to debug an application running inside a virtual machine, you need to add a PHP server (using the “Add” button in the “File - Settings - PHP - Servers” menu) with the following settings:

• Name: demo.local
• Host: demo.local
• Port: 80
• Debugger: Xdebug
• Use path mappings: Enabled (project directory must match the [“php-app”] [[project_dir ”] directory)

Then you need to create a configuration with the type "PHP Web application" (via the menu item "Run - Edit configurations"), specifying the created PHP server.

Conclusion

The resulting environment turned out quite flexible, all software settings are completely transparent and customizable. Using Chef-Solo allows you to deploy a project on almost any machine (not necessarily virtual) in minutes, without requiring any additional actions from the developer.



I will be glad to hear your comments.