Merge pull request #565 from cytopia/docs-processwire

Documentation: Setup ProcessWire

CHANGELOG.md

@@ -3,16 +3,18 @@
 Make sure to have a look at [UPDATING](https://github.com/cytopia/devilbox/blob/master/UPDATING.md) to see any required steps for updating
 major versions.
 
+
+
 ## [Unreleased]
 
 #### Fixed
 - Fixed various typos in documentation
-
-
-## Unreleased
-
 - Fix CI tests: They still expected a mounted mail directory instead of a Docker volume
 
+#### Added
+- Documentation: Setup ProcessWire
+
+
 
 ## Bugfix Release v1.0.1 (2019-03-24)
 
@@ -34,6 +36,7 @@ No explicit actions to be taken for updating.
 - [#536](https://github.com/cytopia/devilbox/issues/536) Added @vue/cli and @vue/cli-service-global
 
 
+
 ## Release v1.0.0 (2019-03-19)
 
 This is the first major stable release of the Devilbox.
@@ -43,6 +46,7 @@ This is the first major stable release of the Devilbox.
 - Everything from v0.15.0 has been backported
 
 
+
 ## Pre-Release v1.0.0-alpha1 (2019-03-09)
 
 #### Changed
@@ -52,6 +56,7 @@ This is the first major stable release of the Devilbox.
 - Use Official MySQL, MariaDB and Percona Docker container
 
 
+
 ## Release v0.15.0 (2019-03-09)
 
 This will be the last v0.x release.

README.md

@@ -813,6 +813,7 @@ As far as tested there are no limitations and you can use any Framework or CMS j
 <a target="_blank" title="PhalconPHP" href="https://phalconphp.com"><img width="64" style="width:64px" src="docs/img/logo_fw/phalcon.png" alt="Devilbox"/></a>
 <a target="_blank" title="PhotonCMS" href="https://photoncms.com"><img width="64" style="width:64px" src="docs/img/logo_fw/photoncms.png" alt="Devilbox"/></a>
 <a target="_blank" title="PrestaShop" href="https://www.prestashop.com/en"><img width="64" style="width:64px" src="docs/img/logo_fw/prestashop.png" alt="Devilbox"/></a>
+<a target="_blank" title="ProcessWire" href="https://processwire.com/"><img width="64" style="width:64px" src="docs/img/logo_fw/processwire.png" alt="Devilbox"/></a>
 <a target="_blank" title="Shopware" href="https://en.shopware.com"><img width="64" style="width:64px" src="docs/img/logo_fw/shopware.png" alt="Devilbox"/></a>
 <a target="_blank" title="Symfony" href="https://symfony.com"><img width="64" style="width:64px" src="docs/img/logo_fw/symfony.png" alt="Devilbox"/></a>
 <a target="_blank" title="Typo3" href="https://typo3.org"><img width="64" style="width:64px" src="docs/img/logo_fw/typo3.png" alt="Devilbox"/></a>
@@ -832,6 +833,7 @@ As far as tested there are no limitations and you can use any Framework or CMS j
 > [Setup PhalconPHP](https://devilbox.readthedocs.io/en/latest/examples/setup-phalcon.html) |
 > [Setup PhotonCMS](https://devilbox.readthedocs.io/en/latest/examples/setup-photon-cms.html) |
 > [Setup PrestaShop](https://devilbox.readthedocs.io/en/latest/examples/setup-presta-shop.html) |
+> [Setup ProcessWire](https://devilbox.readthedocs.io/en/latest/examples/setup-processwire.html) |
 > [Setup Shopware](https://devilbox.readthedocs.io/en/latest/examples/setup-shopware.html) |
 > [Setup Symfony](https://devilbox.readthedocs.io/en/latest/examples/setup-symfony.html) |
 > [Setup Typo3](https://devilbox.readthedocs.io/en/latest/examples/setup-typo3.html) |

docs/_includes/figures/examples/processwire/01-install-banner.rst

@@ -0,0 +1,4 @@
+.. figure:: /_includes/figures/examples/processwire/01-install-banner.png
+   :width: 600px
+
+   ProcessWire installation: Overview

docs/_includes/figures/examples/processwire/02-profile-choice.rst

@@ -0,0 +1,4 @@
+.. figure:: /_includes/figures/examples/processwire/02-profile-choice.png
+   :width: 600px
+
+   ProcessWire installation: Profile Choice

docs/_includes/figures/examples/processwire/03-default-profile.rst

@@ -0,0 +1,4 @@
+.. figure:: /_includes/figures/examples/processwire/03-default-profile.png
+   :width: 600px
+
+   ProcessWire installation: Choose Default Profile

docs/_includes/figures/examples/processwire/04-compat-check.rst

@@ -0,0 +1,4 @@
+.. figure:: /_includes/figures/examples/processwire/04-compat-check.png
+   :width: 600px
+
+   ProcessWire installation: Compatibility Check

docs/_includes/figures/examples/processwire/05-general-setup.rst

@@ -0,0 +1,4 @@
+.. figure:: /_includes/figures/examples/processwire/05-general-setup.png
+   :width: 600px
+
+   ProcessWire installation: General Setup

docs/_includes/figures/examples/processwire/06-admin-setup.rst

@@ -0,0 +1,4 @@
+.. figure:: /_includes/figures/examples/processwire/06-admin-setup.png
+   :width: 600px
+
+   ProcessWire installation: Admin Setup

docs/_includes/figures/examples/processwire/07-finished.rst

@@ -0,0 +1,4 @@
+.. figure:: /_includes/figures/examples/processwire/07-finished.png
+   :width: 600px
+
+   ProcessWire installation: Setup completed

docs/_includes/links/examples.rst

@@ -64,6 +64,12 @@
      Official PrestaShop Documentation <img src="https://raw.githubusercontent.com/cytopia/icons/master/11x11/ext-link.png" />
    </a>
 
+.. |ext_lnk_example_processwire_documentation| raw:: html
+
+   <a target="_blank" href="https://processwire.com/docs/start/install/new/">
+     Official ProcessWire Documentation <img src="https://raw.githubusercontent.com/cytopia/icons/master/11x11/ext-link.png" />
+   </a>
+
 .. |ext_lnk_example_shopware_documentation| raw:: html
 
    <a target="_blank" href="https://docs.shopware.com/en/shopware-5-en/first-steps/installing-shopware?category=shopware-5-en/getting-started">

docs/examples/setup-photon-cms.rst

@@ -9,7 +9,7 @@ Setup Photon CMS
 
 This example will use ``photon`` cli to install Photon CMS from within the Devilbox PHP container.
 
-After completing the below listed steps, you will have a working Laravel setup ready to be
+After completing the below listed steps, you will have a working Photon CMS setup ready to be
 served via http and https.
 
 .. seealso:: |ext_lnk_example_photon_cms|

docs/examples/setup-processwire.rst

@@ -0,0 +1,213 @@
+.. include:: /_includes/all.rst
+.. include:: /_includes/snippets/__ANNOUNCEMENTS__.rst
+
+.. _example_setup_processwire:
+
+*****************
+Setup ProcessWire
+*****************
+
+This example will use ``composer`` to install ProcessWire from within the Devilbox PHP container.
+
+.. important::
+   Using ``composer`` requires the underlying file system to support symlinks. If you
+   use **Docker Toolbox** you need to explicitly allow/enable this.
+   See below for instructions:
+
+   * Docker Toolbox and :ref:`howto_docker_toolbox_and_the_devilbox_windows_symlinks`
+
+After completing the below listed steps, you will have a working ProcessWire setup ready to be
+served via http and https.
+
+.. seealso:: |ext_lnk_example_processwire_documentation|
+
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+Overview
+========
+
+The following configuration will be used:
+
++--------------+--------------------------+-------------+------------+---------------------------------------------+
+| Project name | VirtualHost directory    | Database    | TLD_SUFFIX | Project URL                                 |
++==============+==========================+=============+============+=============================================+
+| my-pw        | /shared/httpd/my-pw      | my_pw       | loc        | http://my-pw.loc |br| https://my-pw.loc     |
++--------------+--------------------------+-------------+------------+---------------------------------------------+
+
+.. note::
+   * Inside the Devilbox PHP container, projects are always in ``/shared/httpd/``.
+   * On your host operating system, projects are by default in ``./data/www/`` inside the
+     Devilbox git directory. This path can be changed via :ref:`env_httpd_datadir`.
+
+The following Devilbox configuration is required:
+
++-----------+--------------+-----------------------------------------------------------------------------------------------------+
+| Service   | Version      | Implications                                                                                        |
++===========+==============+=====================================================================================================+
+| Webserver | Apache 2.4   | Apache is required instead of Nginx as ProcessWire provides default ``.htaccess`` files for routing |
++-----------+--------------+-----------------------------------------------------------------------------------------------------+
+| PHP       | PHP-FPM 7.2  | Chosen for this example as it is the Devilbox default version                                       |
++-----------+--------------+-----------------------------------------------------------------------------------------------------+
+| Database  | MariaDB 10.3 | Chosen for this example as it is the Devilbox default version                                       |
++-----------+--------------+-----------------------------------------------------------------------------------------------------+
+
+.. note:: If you want to use Nginx instead, you will need to adjust the vhost congfiguration accordingly to ProcessWire requirements.
+
+
+Walk through
+============
+
+It will be ready in eight simple steps:
+
+1. Enter the PHP container
+2. Create a new VirtualHost directory
+3. Install ProcessWire via ``composer``
+4. Symlink webroot directory
+5. Setup DNS record
+6. Open your browser
+7. Step through guided web installation
+
+
+1. Enter the PHP container
+--------------------------
+
+All work will be done inside the PHP container as it provides you with all required command line
+tools.
+
+Navigate to the Devilbox git directory and execute ``shell.sh`` (or ``shell.bat`` on Windows) to
+enter the running PHP container.
+
+.. code-block:: bash
+
+   host> ./shell.sh
+
+.. seealso::
+   * :ref:`enter_the_php_container`
+   * :ref:`work_inside_the_php_container`
+   * :ref:`available_tools`
+
+
+2. Create new vhost directory
+-----------------------------
+
+The vhost directory defines the name under which your project will be available. |br|
+( ``<vhost dir>.TLD_SUFFIX`` will be the final URL ).
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd $ mkdir my-pw
+
+.. seealso:: :ref:`env_tld_suffix`
+
+
+3. Install ProcessWire
+----------------------
+
+Navigate into your newly created vhost directory and install ProcessWire with ``composer``.
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd $ cd my-pw
+   devilbox@php-7.0.20 in /shared/httpd/my-pw $ composer create-project processwire/processwire
+
+How does the directory structure look after installation:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-pw $ tree -L 1
+   .
+   └── processwire
+
+   1 directory, 0 files
+
+
+4. Symlink webroot
+------------------
+
+Symlinking the actual webroot directory to ``htdocs`` is important. The web server expects every
+project's document root to be in ``<vhost dir>/htdocs/``. This is the path where it will serve
+the files. This is also the path where your frameworks entrypoint (usually ``index.php``) should
+be found.
+
+Some frameworks however provide its actual content in nested directories of unknown levels.
+This would be impossible to figure out by the web server, so you manually have to symlink it back
+to its expected path.
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-pw $ ln -s ln -s processwire htdocs
+
+How does the directory structure look after symlinking:
+
+.. code-block:: bash
+
+   devilbox@php-7.0.20 in /shared/httpd/my-pw $ tree -L 1
+   .
+   ├── processwire
+   └── htdocs -> processwire
+
+   2 directories, 0 files
+
+As you can see from the above directory structure, ``htdocs`` is available in its expected
+path and points to the frameworks entrypoint.
+
+.. important::
+   When using **Docker Toolbox**, you need to **explicitly allow** the usage of **symlinks**.
+   See below for instructions:
+
+   * Docker Toolbox and :ref:`howto_docker_toolbox_and_the_devilbox_windows_symlinks`
+
+
+5. DNS record
+-------------
+
+If you **have** Auto DNS configured already, you can skip this section, because DNS entries will
+be available automatically by the bundled DNS server.
+
+If you **don't have** Auto DNS configured, you will need to add the following line to your
+host operating systems ``/etc/hosts`` file (or ``C:\Windows\System32\drivers\etc`` on Windows):
+
+.. code-block:: bash
+   :caption: /etc/hosts
+
+   127.0.0.1 my-pw.loc
+
+.. seealso::
+
+   * :ref:`howto_add_project_hosts_entry_on_mac`
+   * :ref:`howto_add_project_hosts_entry_on_win`
+   * :ref:`setup_auto_dns`
+
+
+6. Open your browser
+--------------------
+
+Open your browser at http://my-pw.loc or https://my-pw.loc.
+
+
+7. Step through guided web installation
+---------------------------------------
+
+.. include:: /_includes/figures/examples/processwire/01-install-banner.rst
+
+.. include:: /_includes/figures/examples/processwire/02-profile-choice.rst
+
+.. include:: /_includes/figures/examples/processwire/03-default-profile.rst
+
+.. include:: /_includes/figures/examples/processwire/04-compat-check.rst
+
+.. include:: /_includes/figures/examples/processwire/05-general-setup.rst
+
+.. include:: /_includes/figures/examples/processwire/06-admin-setup.rst
+
+.. include:: /_includes/figures/examples/processwire/07-finished.rst
+
+
+Next steps
+==========
+
+.. include:: /_includes/snippets/examples/next-steps.rst

docs/examples/setup-shopware.rst

@@ -9,7 +9,7 @@ Setup Shopware
 
 This example will use ``git`` to install Shopware from within the Devilbox PHP container.
 
-After completing the below listed steps, you will have a working Laravel setup ready to be
+After completing the below listed steps, you will have a working Shopware setup ready to be
 served via http and https.
 
 .. seealso::

docs/examples/setup-typo3.rst

@@ -16,7 +16,7 @@ This example will use ``composer`` to install TYPO3 from within the Devilbox PHP
 
    * Docker Toolbox and :ref:`howto_docker_toolbox_and_the_devilbox_windows_symlinks`
 
-After completing the below listed steps, you will have a working Laravel setup ready to be
+After completing the below listed steps, you will have a working TYPO3 setup ready to be
 served via http and https.
 
 .. seealso:: |ext_lnk_example_typo3_documentation|
@@ -195,7 +195,7 @@ Open your browser at http://my-typo.loc or https://my-typo.loc.
    * Connection: Manually configured MySWQL TCP/IP connection
    * Username: root
    * Password
-   * Host: 127.0.0.1
+   * Host: mysql
    * Port: 3306
 
 2. Select database

docs/index.rst

@@ -184,6 +184,7 @@ host is ready to be served with your custom domain.
    examples/setup-phalcon
    examples/setup-photon-cms
    examples/setup-presta-shop
+   examples/setup-processwire
    examples/setup-shopware
    examples/setup-symfony
    examples/setup-typo3

docs/support/faq.rst

@@ -216,6 +216,12 @@ Does it work with PrestaShop?
 Yes, see :ref:`example_setup_presta_shop`
 
 
+Does it work with ProcessWire?
+------------------------------
+
+Yes, see :ref:`example_setup_processwire`
+
+
 Does it work with Shopware?
 ---------------------------