Application deployment with Ansible

zpk2ansible is a command-line utility that builds a human-readable Ansible playbook based on a Zend Package (ZPK) to deploy the application to a server. You use it when migrating to ZendPHP from Zend Server. The tool is written in Python.

This article includes references to a third-party product, Ansible. The user interface and usage of third-party products are subject to change without notice. For the latest published information about Ansible, see docs.ansible.com.

Supported operating systems

The zpk2ansible tool is supported on the following operating systems:

Requirements

  • Knowledge of Ansible is required.
  • ansible-core version 2.11 or later is required; this version includes the ansible.builtin.split filter which is used by the zpk2ansible tool.
  • Python is required to use the optional venv environment.

Set up and install zpk2ansible

Our examples installs zpk2ansible into an optional Python virtual environment.

  1. Set up a Python virtual environment to run the utility:

    $ sudo apt install python3-pip python3-venv
    $ python -m venv venv
    $ source venv/bin/activate

  2. Install the zpk2ansible utility inside the venv environment:

    $ wget https://repos.zend.com/zpk2ansible/zpk2ansible-latest.tar.gz
    $ venv/bin/pip install ./zpk2ansible-latest.tar.gz
    $ venv/bin/zpk2ansible --version

Deploy your application

  1. Create an inventory.yml file that describes the targets to which you are deploying your application. For more information, see How to build your inventory (Ansible Community Documentation).

    If the playbook contains the option hosts: all, ensure that the inventory.yml file contains only the hosts where the application will be deployed.

  2. Inspect the ZPK file:

    $ venv/bin/zpk2ansible inspect path/to/your/zpkFile.zpk

    The output for this command will include various details for the given ZPK file, dependencies, status of existing webserver vhost and PHP-FPM pool configurations, overridable parameters, and a sample build command for playbook generation. In case of an invalid ZPK file, the inspect command notifies you of what the invalid directory or file is.

    In addition to specifying the interactive mode or the chosen web server, this sample command demonstrates how you can override variables in the ZPK file. Find further information on these variables by running the following command:

    $ venv/bin/zpk2ansible build --help

  3. Build the playbook:

    $ venv/bin/zpk2ansible build path/to/your/zpkFile.zpk vhost_name

  4. Run the playbook:

    $ ansible-playbook -i inventory.yml playbook.yml

Store your ZendPHP repository credentials

To ensure that you can access the ZendPHP repository safely, store your credentials securely. To store your ZendPHP repository credentials, pass them as extra variables when executing the playbook:

$ ansible-playbook -i inventory.yml playbook.yml --extra-vars "zendphp_repo_account=ORDER_ID zendphp_repo_password=PASSWORD"

You must store your credentials only once. If the playbook is executed a second time against the same target server, the playbook uses the credentials that are stored there.

To change the stored credentials, pass new credentials as extra variables when executing the playbook.

Configure a custom web server or PHP-FPM

To meet the specific requirements of your organization, you can configure a custom web server or PHP-FPM Pool. In this case, provide a custom web server vhost (Nginx and httpd) or PHP-FPM Pool configuration templates.

After you generate the playbook, the zpk2ansible utility creates several template files in the same directory where the playbook.yml file is:

  • nginx.conf.j2 — the Nginx vhost configuration

  • httpd.conf.j2 — the httpd vhost config

  • fpm_pool.conf.j2 — the PHP-FPM pool configuration

How customization works:

  • If you customize these templates, the tool uses your configuration template files when you run the generated Ansible playbook.

  • If any of these template files are present in the playbook directory, they won't be overwritten.

  • If any of these template files are missing from the playbook directory, the zpk2ansible tool checks first for the file in the ZPK package root directory.

    • If the file is not found in the root directory, the tool uses the included default file.
If the appropriate webserver vhost configuration files, or the PHP-FPM Pool configuration files, respectively, are not present in the directory, application deployment fails.

Usage examples

How to prepare for deployment (quickstart method)

  1. Edit the inventory:

    $ nano inventory.yml

  2. Edit the playbook. For example, add your ZendPHP repo credentials or a vhost name to the playbook.

    $ nano playbook.yml

How to create a deployment from a ZPK file

You can deploy a ZPK file to different web servers. Use one of the following commands:

To create a deployment for httpd 2.2, which is the default, create the playbook using the following command:

$ venv/bin/zpk2ansible build --httpd myapp.zpk vhost_name

To create a deployment for httpd 2.4, create the playbook using the following command:

$ venv/bin/zpk2ansible build --webserver_type httpd-2.4 myapp.zpk vhost_name

To create a deployment for nginx, create the playbook using the following command:

$ venv/bin/zpk2ansible build --nginx myapp.zpk vhost_name

How to deploy with runtime playbook variables

To deploy the application with custom runtime playbook variables, use the following syntax:

$ ansible-playbook -i inventory.yml playbook.yml --extra-vars '{"VAR_NAME": "VALUE", "OTHER_VAR": "OTHER_VALUE"}'

You can override the following existing playbook variables:

  • In nginx.conf.j2 and httpd.conf.j2:

    • vhost_name

    • docroot

    • fpm_socket_path

  • In fpm_pool.conf.j2:

    • vhost_name

    • user

    • fpm_socket_path

    • web_server_user