Add doc for project startup scripts

docs/autostart/autostarting-nodejs-apps.rst

@@ -8,15 +8,16 @@ Autostarting NodeJS Apps
 ************************
 
 
-You can have all of your NodeJS applications spin up automtically as soon as you ``docker-compose up``.
-This can be achieved by makeing use of |ext_lnk_tool_pm2| (Node.js Process Manager) and the
+You can have all of your NodeJS applications spin up automatically as soon as you ``docker-compose up``.
+This can be achieved by making use of |ext_lnk_tool_pm2| (Node.js Process Manager) and the
 autostart feature.
 
 .. seealso::
    **Read more about how to add scripts for autostart commands:**
 
    * :ref:`custom_scripts_per_php_version` (individually for different PHP versions)
    * :ref:`custom_scripts_globally` (equal for all PHP versions)
+   * :ref:`custom_scripts_per_project` (stored in project directory)
 
 
 **Table of Contents**
@@ -58,7 +59,7 @@ Pre-built
 =========
 
 Instead of writing multiple scripts for multiple applications, you can also make use of the
-pre-shipped script that allows you to start unlimitted NodeJS applications via |ext_lnk_tool_pm2|.
+pre-shipped script that allows you to start unlimited NodeJS applications via |ext_lnk_tool_pm2|.
 
 The following script is provided in ``autostart/run-node-js-projects.sh-example`` and needs to be
 copied to a file ending by ``.sh``
@@ -70,7 +71,7 @@ copied to a file ending by ``.sh``
    host> cp run-node-js-projects.sh-example run-node-js-projects.sh
 
 
-In that newly created file, you can simply add the full paths (path inside the Docker containre)
+In that newly created file, you can simply add the full paths (path inside the Docker container)
 of your Javascript files that need to be started. There is already one example which is not
 commented. Change this to your path and add as many lines as you have projects to startup.
 

docs/autostart/custom-scripts-globally.rst

@@ -13,11 +13,15 @@ the initial startup.
 
 .. seealso::
    * :ref:`custom_scripts_per_php_version` (individually for different PHP versions)
+   * :ref:`custom_scripts_per_project` (stored in project directory)
    * :ref:`autostarting_nodejs_apps`
 
 
 .. note::
-   Global scripts are always executed **after** per PHP version scripts.
+   Scripts are executed in the following order:
+   1. per PHP version scripts
+   2. global scripts
+   3. per project scripts
 
 
 **Table of Contents**
@@ -76,6 +80,12 @@ The scripts will always be executed inside the PHP container (Debian Linux) and
 ``root`` privileges. It is however possible to drop privileges within the script to have them
 executed as a normal user.
 
+Environment Variables
+---------------------
+
+The following environment variables will be available to your script:
+   * All variables that have been set in your ``.env`` file
+
 
 Examples
 ========

docs/autostart/custom-scripts-per-php-version.rst

@@ -13,11 +13,15 @@ the initial startup.
 
 .. seealso::
    * :ref:`custom_scripts_globally` (equal for all PHP versions)
+   * :ref:`custom_scripts_per_project` (stored in project directory)
    * :ref:`autostarting_nodejs_apps`
 
 
 .. note::
-   Per PHP version scripts are always executed **before** global scripts.
+   Scripts are executed in the following order:
+   1. per PHP version scripts
+   2. global scripts
+   3. per project scripts
 
 
 **Table of Contents**
@@ -81,14 +85,20 @@ The scripts will always be executed inside the PHP container (Debian Linux) and
 ``root`` privileges. It is however possible to drop privileges within the script to have them
 executed as a normal user.
 
+Environment Variables
+---------------------
+
+The following environment variables will be available to your script:
+   * All variables that have been set in your ``.env`` file
+
 
 Examples
 ========
 
 Installing Microsoft ODBC driver
 --------------------------------
 
-This example will add Microsofts ODBC driver to PHP 7.1. These drivers are required in order to
+This example will add Microsoft's 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`.
 
@@ -98,7 +108,7 @@ requires every user to accept a license/EULA by Microsoft.
 
 .. code-block:: bash
 
-   # Navigate to starup dir of PHP 7.1
+   # Navigate to startup dir of PHP 7.1
    host> cd path/to/devilbox/cfg/php-startup-7.1
 
    # Create an .sh file
@@ -107,7 +117,7 @@ requires every user to accept a license/EULA by Microsoft.
    # 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
+Paste the following into ``ms-odbc.sh`` and **ensure to accept the EULA** by changing
 ``ACCEPT_EULA=N`` to ``ACCEPT_EULA=Y``.
 
 .. code-block:: bash
@@ -158,7 +168,7 @@ Paste the following into ``ms-obbc.sh`` and **ensure to accept the EULA** by cha
    ### EULA accepted, so we can proceed
    ###
 
-   # Extract latest *.deb packate
+   # Extract latest *.deb package
    MSODBC_DEB="$( curl -k -sS "${MSODBC_URL}" | grep -Eo 'msodbcsql[-._0-9]+?_amd64\.deb' | tail -1 )"
 
    # Download to temporary location

docs/autostart/custom-scripts-per-project.rst

@@ -0,0 +1,98 @@
+.. include:: /_includes/snippets/__ANNOUNCEMENTS__.rst
+
+.. _custom_scripts_per_project:
+
+******************************
+Custom scripts per PHP version
+******************************
+
+You can provide custom startup commands via bash scripts to each of the PHP container individually.
+This may be useful to specify additional software to install or additional settings to apply during
+the initial startup.
+
+
+.. seealso::
+   * :ref:`custom_scripts_per_php_version` (individually for different PHP versions)
+   * :ref:`custom_scripts_globally` (equal for all PHP versions)
+   * :ref:`autostarting_nodejs_apps`
+
+
+.. note::
+   Scripts are executed in the following order:
+   1. per PHP version scripts
+   2. global scripts
+   3. per project scripts
+
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+General
+=======
+
+.. important::
+   Provided scripts must end by the file extension ``.sh`` and should be executable.
+   Anything not ending by ``.sh`` will be ignored.
+
+.. important::
+   Provided scripts will be executed by the ``root`` user within the PHP container.
+
+
+Where
+-----
+
+In your project folder, you will need to create a folder called ``.devilbox/autostart``
+in which you can add custom shell scripts.
+
+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. It is however possible to drop privileges within the script to have them
+executed as a normal user.
+
+Environment Variables
+---------------------
+
+The following environment variables will be available to your script:
+   * ``DEVILBOX_PROJECT_NAME``: The name of your project folder
+   * ``DEVILBOX_PROJECT_DIR``: The full path to your project folder (e.g. "/shared/httpd/$DEVILBOX_PROJECT_NAME")
+   * ``DEVILBOX_PROJECT_DOCROOT``: the full path to your web root (e.g. "$DEVILBOX_PROJECT_DIR/htdocs")
+   * All other variables that have been set in your ``.env`` file
+
+
+Examples
+========
+
+Setting up a cron job
+---------------------
+
+Most CMS platforms and other website applications require or suggest to run a cron job from the
+command line to perform e.g. long-running, repetitive or scheduled tasks.
+
+With the helper function ``cron_add()`` it is easy to specify such a cron job:
+
+
+.. code-block:: bash
+
+    #!/usr/bin/env bash
+
+    cron_add "* * * * * "$(which php)" "${DEVILBOX_PROJECT_DOCROOT}/cron.php" some arguments >/dev/null 2>&1"
+
+
+
+Running commands as devilbox user
+---------------------------------
+
+As mentioned above, all scripts are run by the ``root`` user. If you do need something to be executed as the
+normal user ``devilbox``, you can simply ``su -l devilbox -c "command"`` inside the shell script.
+
+For further details see :ref:`custom_scripts_globally`'s example section.