From 211e5c1bddcecc6abea933299289ed9a430f2238 Mon Sep 17 00:00:00 2001 From: Beth Dean Date: Thu, 17 Oct 2019 14:04:54 -0700 Subject: [PATCH] Add tutorial for PHP install & config (#869) * Add tutorial for PHP install & config * Add php-fpm configuration detail to php tutorial * Change bundle name to httpd * Remove httpd references from php tutorial * Fix typos, change instructions to active verbs --- source/tutorials/php.rst | 198 ++++++++++++++++++ .../wordpress/web-server-install.rst | 8 +- 2 files changed, 202 insertions(+), 4 deletions(-) create mode 100644 source/tutorials/php.rst diff --git a/source/tutorials/php.rst b/source/tutorials/php.rst new file mode 100644 index 00000000..eaf91f14 --- /dev/null +++ b/source/tutorials/php.rst @@ -0,0 +1,198 @@ +.. _php: + +PHP and PHP-FPM +*************** + +This tutorial describes how to configure and use PHP and PHP-FPM on |CL-ATTR|. Although we specifically address PHP this tutorial can serve as a general guide for working with applications in the |CL| :ref:`stateless` environment. + +.. contents:: + :local: + :depth: 1 + +Overview +******** + +`PHP (PHP:Hypertext Preprocessor)`_ is an Open Source general-purpose scripting language that is popular with web-developers who leverage its ability to create dynamically generated web pages. `PHP-FPM (FastCGI Process Manager)`_ is a PHP FastCGI implementation that controls process management, workers, and logging for PHP. The two applications work in conjunction but each has its own configuration. + + + +Prerequisites +************* + +* :ref:`Install ` |CL| on your host system +* Use :command:`swupd` to install the :file:`php-basic` bundle. + + .. code-block:: bash + + sudo swupd bundle-add php-basic + +.. note:: + + PHP does not require a web server for operation. Refer to :ref:`web-server-install` for instructions on setting up a :abbr:`LAMP (Linux, Apache\*, MySQL, PHP)` server, or use :command:`swupd` to install :file:`nginx` or similar if you need a web server. + + +Configure PHP +************* + +.. important:: + + This section does not cover configuring the PHP-FPM service. There is a difference between the two configurations. This section is only looking at the PHP configuration directives, not those of PHP-FPM. + + +By default PHP looks for configuration settings in the :file:`php.ini` file, which resides in the :file:`usr/share/defaults/php/` path. Because |CL| is designed to be a :ref:`stateless` operating system, you must create an optional configuration file to override the default values. Every time :command:`swupd` updates the system it will overwrite changes to the :file:`/usr/share/defaults` file structure. To save your configuration options through updates, you must create a PHP configuration file in a location that will not be overwritten. The recommended location is within the :file:`/etc` file structure. For PHP we will create a :file:`/etc/php.d` directory for all PHP config files. + +Create a :file:`php.ini`. + +.. code-block:: bash + + sudo mkdir -p /etc/php.d + sudo touch /etc/php.d/my-php.ini + +This file can be edited with any of your specific configuration requirements, and will not be overwritten when :command:`swupd` performs an update. The `PHP configuration file`_ documentation has complete detail about what you can set in this file. + +Verify the location of the PHP configuration files with the :command:`php --ini` command: + +.. code-block:: bash + + php --ini + +You should see output like this + +.. code-block:: console + + Configuration File (php.ini) Path: /usr/share/defaults/php/ + Loaded Configuration File: /usr/share/defaults/php/php.ini + Scan for additional .ini files in: /etc/php.d + Additional .ini files parsed: + + +This output indicates that PHP will read the php.ini file from :file:`/usr/share/defaults/php` and will then load any further configuration from :file:`.ini` files in :file:`/etc/php.d/`. We use the :file:`my-php.ini` file in :file:`/etc/php.d` for our specific needs, and allow the defaults to be read from :file:`/usr/share/defaults/php/`. Note that the :file:`my-php.ini` file has not been parsed yet -- this is because the file has no content at this point, and is disregarded. + + +Install PHP extensions +********************** + +PHP extensions are compiled libraries designed to enable specific functions in your PHP code. |CL| provides PHP extensions in the :file:`php-extras` bundle. Install the bundle with swupd: + +.. code-block:: bash + + sudo swupd bundle-add php-extras + +Find the list of extensions included in the `php-extras`_ bundle on the |CL| `Store`_. + + +Enable PHP extensions +********************* + +To enable an installed extension we need to add it to the :file:`php.ini` for the composer to use it. + +Create the :file:`my-php.ini` file, with the directive to load the php-imagick extension + +.. code-block:: bash + + sudo echo "extension=imagick.so" >> /etc/php.d/my-php.ini + + +No further detail is required to load the extension, but you must restart the php-fpm service for PHP to pick up the modification to the :file:`/etc/php.d/my-php.ini` file. + +.. code-block:: bash + + sudo systemctl restart php-fpm + +Verify that the imagick extension has been loaded by searching through the runtime list of loaded PHP Modules. + +.. code-block:: bash + + php -m | grep imagick + + +.. note:: + + To enable an extension, you must install it, add it to the :file:`my-php.ini` file, and restart the :file:`php-fpm` service. However, some extensions may have configuration options, which will be documented by the extension maintainer. Add the options you need to the :file:`/etc/php.d/my-php.ini` file as described in the extension's documentation. Be sure to restart :file:`php-fpm` after changing the file. + +Configure PHP-FPM +***************** + +The PHP-FPM configuration file is separate from the :file:`php.ini` file used by PHP. |CL| installs the default :file:`php-fpm.conf` file in :file:`/usr/share/defaults/php` and this file will be overwritten with its default values during each software update. However, PHP-FPM requires that the configuration file exist in that location, and by design will not read configuration options from a different path. + +One solution to changing PHP-FPM configuration options in |CL| is to manually override the php-fpm.service unit in systemd to pass an explicit location to a custom :file:`php-fpm.conf` file. + +#. Copy the :file:`/usr/share/defaults/php/php-fpm.conf` file to the :file:`/etc/php.d` + + .. code-block:: bash + + sudo cp /usr/share/defaults/php/php-fpm.conf /etc/php.d/php-fpm.conf + +#. Make changes to the :file:`php-fpm.conf` file as needed. The `FPM documentation`_ has detail on the configuration options available to PHP-FPM. + + +#. Edit the systemd service unit file + + .. code-block:: bash + + sudo systemctl edit --full php-fpm.service + + This will open the php-fpm.service file for systemd in your editor. Change the :command:`ExecStart` configuration to add the :command:`--fpm-config` option to point to the custom location. + + .. code-block:: bash + + sudo systemctl edit --full php-fpm.service + + .. code-block:: console + + [Unit] + Description=The PHP FastCGI Process Manager + After=syslog.target network.target + + [Service] + Type=notify + PIDFile=/run/php-fpm.pid + ExecStart=/usr/sbin/php-fpm --nodaemonize --fpm-config /etc/php.d/php-fpm.conf + ExecReload=/bin/kill -USR2 $MAINPID + PrivateTmp=true + + [Install] + WantedBy=multi-user.target + +#. Restart the service + + .. code-block:: bash + + sudo systemctl restart php-fpm.service + +#. Verify that the new path has been picked up + + .. code-block:: bash + + sudo systemctl status php-fpm.service + + You should see the new path in the output + + .. code-block:: console + + ● php-fpm.service - The PHP FastCGI Process Manager + Loaded: loaded (/etc/systemd/system/php-fpm.service; enabled; vendor preset: disabled) + Active: active (running) since Thu 2019-10-17 13:19:34 PDT; 8min ago + Main PID: 14452 (php-fpm) + Status: "Processes active: 0, idle: 0, Requests: 0, slow: 0, Traffic: 0req/sec" + Tasks: 1 + Memory: 11.1M + CGroup: /system.slice/php-fpm.service + └─14452 php-fpm: master process (/etc/php.d/php-fpm.conf) + + + + + + +.. _PHP (PHP:Hypertext Preprocessor): https://www.php.net/ + +.. _PHP-FPM (FastCGI Process Manager): https://php-fpm.org/ + +.. _php-extras: https://clearlinux.org/software/bundle/php-extras + +.. _Store: https://clearlinux.org/software/ + +.. _PHP configuration file: https://www.php.net/manual/en/configuration.file.php + +.. _FPM documentation: https://www.php.net/manual/en/install.fpm.configuration.php diff --git a/source/tutorials/wordpress/web-server-install.rst b/source/tutorials/wordpress/web-server-install.rst index bd5de10b..c120e143 100644 --- a/source/tutorials/wordpress/web-server-install.rst +++ b/source/tutorials/wordpress/web-server-install.rst @@ -25,10 +25,10 @@ Apache is an open source HTTP web server application that can run on several operating systems, including |CL|. Go to the `Apache HTTP Server Project`_ for more information. -Install the web-server-basic bundle -=================================== +Install the httpd bundle +======================== -The **web-server-basic** bundle contains the packages needed to install the +The **httpd** bundle contains the packages needed to install the Apache software bundle on |CL|. .. note:: @@ -44,7 +44,7 @@ Apache software bundle on |CL|. .. code-block:: bash - sudo swupd bundle-add web-server-basic + sudo swupd bundle-add httpd #. To start the Apache service, enter the following commands: