diff --git a/docs/advanced/custom-startup-commands.rst b/docs/advanced/custom-startup-commands.rst new file mode 100644 index 00000000..89cd52c8 --- /dev/null +++ b/docs/advanced/custom-startup-commands.rst @@ -0,0 +1,221 @@ +.. _custom_startup_commands: + +*********************** +Custom startup commands +*********************** + +You can provide custom startup commands via bash scripts to each of the PHP container. +This may be useful to specify additional software to install or additional settings to apply during +the initial startup. + +**Table of Contents** + +.. contents:: :local: + + +General +======= + +You can add custom ``bash`` scripts for each PHP version separately. Provided scripts must end +by the file extension ``.sh`` and should be executable. Anything not ending by ``.sh`` will be +ignored. + +Where +----- + +Startup scripts can be added to ``cfg/php-startup-X.Y/``. +See the directory structure for PHP startup script directories inside ``./cfg/`` directory: + +.. code-block:: bash + + host> ls -l path/to/devilbox/cfg/ | grep 'php-startup' + + drwxr-xr-x 2 cytopia cytopia 4096 Mar 5 21:53 php-startup-5.2/ + drwxr-xr-x 2 cytopia cytopia 4096 Mar 5 21:53 php-startup-5.3/ + drwxr-xr-x 2 cytopia cytopia 4096 Mar 5 21:53 php-startup-5.4/ + drwxr-xr-x 2 cytopia cytopia 4096 Mar 5 21:53 php-startup-5.5/ + drwxr-xr-x 2 cytopia cytopia 4096 Apr 3 22:04 php-startup-5.6/ + drwxr-xr-x 2 cytopia cytopia 4096 Mar 5 21:53 php-startup-7.0/ + drwxr-xr-x 2 cytopia cytopia 4096 Mar 5 21:53 php-startup-7.1/ + drwxr-xr-x 2 cytopia cytopia 4096 Mar 5 21:53 php-startup-7.2/ + drwxr-xr-x 2 cytopia cytopia 4096 Mar 5 21:53 php-startup-7.3/ + drwxr-xr-x 2 cytopia cytopia 4096 Mar 5 21:53 php-startup-7.4/ + + +Custom scripts are added by placing a file into ``cfg/php-startup-X.X/`` (where ``X.X`` stands for +your PHP version). The file must end by ``.sh`` in order to be executed by the PHP container. + +Some of the PHP startup directories contain a few example files with the file suffix ``-example``. +If you want to use them, copy these files to a new name without the ``-example`` suffix and ensure +they end by ``.sh``. + +When +---- + +The scripts will be executed by the PHP container during initial startup. Whenever you change your +scripts, ensure to restart the Devilbox. + +How +--- + +The scripts will always be executed inside the PHP container (Debian Linux) and will be run with +``root`` privileges. + + +Examples +======== + +The following examples should already exist as example files within ``cfg/php-startup-X.Y``, but +will covered here as well to show some real world examples of what can be done with startup scripts. + +Installing Microsoft ODBC driver +-------------------------------- + +This example will add Microsofts ODBC driver to PHP 7.1. These drivers are required in order to +make the PHP modules ``pdo_sqlsrv`` and ``sqlsrv`` work. The two mentioned modules are already +available in the PHP container, but are explicitly disabled via :ref:`env_file_php_modules_disable`. + +They won't work without the ODBC driver installed, which unfortunately cannot be bundled, as it +requires every user to accept a license/EULA by Microsoft. + + +.. code-block:: bash + + # Navigate to starup dir of PHP 7.1 + host> cd path/to/devilbox/cfg/php-startup-7.1 + + # Create an .sh file + host> touch ms-odbc.sh + + # Open the file in your favourite editor + host> vi ms-odbc.sh + +Paste the following into ``ms-obbc.sh`` and **ensure to accept the EULA** by changing +``ACCEPT_EULA=N`` to ``ACCEPT_EULA=Y``. + +.. code-block:: bash + :caption: ms-odbc.sh + :emphasize-lines: 18 + + !/bin/bash + # + # This script will automatically install the Microsoft ODBC driver for MsSQL + # support for PHP during startup. + # + # In order for it to work, you must read and accept their License/EULA: + # https://odbceula.blob.core.windows.net/eula17/LICENSE172.TXT + # + + + # ------------------------------------------------------------------------------------------------ + # EDIT THE VARIABLE BELOW TO ACCEPT THE EULA (If you agree to their terms) + # ------------------------------------------------------------------------------------------------ + + ### + ### Set this to "Y" (capital 'Y') if you accept the EULA. + ### + ACCEPT_EULA=N + + + + # ------------------------------------------------------------------------------------------------ + # DO NOT EDIT BELOW THIS LINE + # ------------------------------------------------------------------------------------------------ + + ### + ### Where to retrieve the deb package + ### + MSODBC_URL="https://packages.microsoft.com/debian/8/prod/pool/main/m/msodbcsql17/" + + + ### + ### Pre-flight check + ### + if [ "${ACCEPT_EULA}" != "Y" ]; then + echo "MS ODBC EULA not accepted. Aborting installation." + exit 0 + fi + + + ### + ### EULA accepted, so we can proceed + ### + + # Extract latest *.deb packate + MSODBC_DEB="$( curl -k -sS "${MSODBC_URL}" | grep -Eo 'msodbcsql[-._0-9]+?_amd64\.deb' | tail -1 )" + + # Download to temporary location + curl -k -sS "${MSODBC_URL}${MSODBC_DEB}" > "/tmp/${MSODBC_DEB}" + + # Install + ACCEPT_EULA="${ACCEPT_EULA}" dpkg -i "/tmp/${MSODBC_DEB}" + + # Remove artifacts + rm -f "/tmp/${MSODBC_DEB}" + + +.. important:: + The script will not work, if you have not accepted the EULA. + + +Installing Oracle oci8 and pdo_oci PHP modules +---------------------------------------------- + +This example will install Oracle instaclient as well as PHP modules ``pdo_oci`` and ``oci8`` in +order to use PHP to connect to Oracle. This startup script will only be provided to PHP 7.2 + + +.. code-block:: bash + + # Navigate to starup dir of PHP 7.2 + host> cd path/to/devilbox/cfg/php-startup-7.2 + + # Create an .sh file + host> touch oracle.sh + + # Open the file in your favourite editor + host> vi oracle.sh + + +Paste the following into ``oracle.sh``: + +.. code-block:: bash + :caption: oracle.sh + + #!/bin/bash + # + # https://yum.oracle.com/repo/OracleLinux/OL7/oracle/instantclient/x86_64/ + # + + # Install 'alien' to install rpm packages + apt-get update -q + DEBIAN_FRONTEND=noninteractive apt-get install -qq -y --no-install-recommends --no-install-suggests alien + + # Instantclient (basic lite) + curl -o /tmp/oracle-instantclient18.3-basiclite-18.3.0.0.0-2.x86_64.rpm https://yum.oracle.com/repo/OracleLinux/OL7/oracle/instantclient/x86_64/getPackage/oracle-instantclient18.3-basiclite-18.3.0.0.0-2.x86_64.rpm + + # Instantclient (devel) + curl -o /tmp/oracle-instantclient18.3-devel-18.3.0.0.0-2.x86_64.rpm https://yum.oracle.com/repo/OracleLinux/OL7/oracle/instantclient/x86_64/getPackage/oracle-instantclient18.3-devel-18.3.0.0.0-2.x86_64.rpm + + # Install RPMs + alien -i /tmp/oracle-instantclient18.3-basiclite-18.3.0.0.0-2.x86_64.rpm + alien -i /tmp/oracle-instantclient18.3-devel-18.3.0.0.0-2.x86_64.rpm + + # Rempve RPMs + rm -f /tmp/oracle-instantclient18.3-basiclite-18.3.0.0.0-2.x86_64.rpm + rm -f /tmp/oracle-instantclient18.3-devel-18.3.0.0.0-2.x86_64.rpm + + # Necessary symlinks + ln -s /usr/lib/oracle/18.3/client64/lib/libmql1.so /usr/lib/ + ln -s /usr/lib/oracle/18.3/client64/lib/libipc1.so /usr/lib/ + ln -s /usr/lib/oracle/18.3/client64/lib/libnnz18.so /usr/lib/ + ln -s /usr/lib/oracle/18.3/client64/lib/libons.so /usr/lib/ + ln -s /usr/lib/oracle/18.3/client64/lib/libclntshcore.so.18.1 /usr/lib/ + + # Build and install PHP extension oci8 + docker-php-ext-configure oci8 --with-oci8=instantclient + docker-php-ext-install oci8 + + # Build and install PHP extension pdo_oci + docker-php-ext-configure pdo_oci --with-pdo-oci=instantclient,/usr,18.3 + docker-php-ext-install pdo_oci diff --git a/docs/index.rst b/docs/index.rst index a78ad282..d5f3e1c3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -70,6 +70,7 @@ host is ready to be served with your custom domain. :maxdepth: 2 :numbered: + advanced/custom-startup-commands advanced/customize-php-globally advanced/customize-webserver-globally advanced/connect-to-host-os