Documentation for vhost-gen templates

cfg/vhost-gen/README.md

@@ -1,5 +1,6 @@
 # Global vhost-gen configurations
 
+Enabling templates in this directory will change the webserver vhost configuration globally for all projects which do not have their own specific vhost-gen template in place.
 
 In order for template files to be picked up by the web server they must have the correct name.
 

docs/advanced/customize-webserver-globally.rst

@@ -6,15 +6,14 @@ Web server settings can be applied globally, which will affect the web server be
 but not the vhost configuration. Configuration can be done for each version separetely, which means
 each web server can have its own profile of customized settings.
 
-..
-   In order to customize the vhosts, have a look at the following links:
-   * :ref:`customize_specific_virtual_host`
-   * :ref:`customize_all_virtual_hosts_globally`
-
 .. seealso::
-   In order to customize a specific vhosts, have a look at the following link:
+   In order to customize the vhosts, have a look at the following links:
+
+   * vhost-gen: :ref:`vhost_gen_virtual_host_templates`
+   * vhost-gen: :ref:`vhost_gen_customize_all_virtual_hosts_globally`
+   * vhost-gen: :ref:`vhost_gen_customize_specific_virtual_host`
+   * vhost-gen: :ref:`vhost_gen_example_add_sub_domains`
 
-   * :ref:`customize_specific_virtual_host`
 
 **Table of Contents**
 

docs/configuration-files/apache-conf.rst

@@ -15,9 +15,11 @@ custom configurations.
    Devilbox Auto-vhost generation feature. If you want to custimize your current virtual hosts
    have a look at:
 
-   * :ref:`customize_specific_virtual_host`
-..
-   * :ref:`customize_all_virtual_hosts_globally`
+   * vhost-gen: :ref:`vhost_gen_virtual_host_templates`
+   * vhost-gen: :ref:`vhost_gen_customize_all_virtual_hosts_globally`
+   * vhost-gen: :ref:`vhost_gen_customize_specific_virtual_host`
+   * vhost-gen: :ref:`vhost_gen_example_add_sub_domains`
+
 
 **Table of Contents**
 

docs/configuration-files/env-file.rst

@@ -1349,7 +1349,7 @@ you will have to create a directory by whatever name you chose for that variable
    drwxr-xr-x 2 cytopia cytopia 4096 Mar 12 23:05 htdocs/
 
 Now you need to copy the ``vhost-gen`` templates into the ``.devilbox`` directory. The templates
-are available in the Devilbox git directory under ``templates/vhost-gen/``.
+are available in the Devilbox git directory under ``cfg/vhost-gen/``.
 
 By copying those files into your project template directory, nothing will change, these are the
 default templates that will create the virtual host exactly the same way as if they were not
@@ -1362,7 +1362,7 @@ present.
    host> cd path/to/devilbox
 
    # Copy templates to your project directory
-   host> cp templates/vhost-gen/* data/www/my-first-project/.devilbox/
+   host> cp cfg/vhost-gen/*.yml data/www/my-first-project/.devilbox/
 
 
 Let's have a look how the directory is actually built up:
@@ -1396,10 +1396,11 @@ changing the server name or adding locations to other assets.
      When you want to find out more how to actually customize each virtual host to its own need,
      read up more on:
 
-     * :ref:`customize_specific_virtual_host`
-     * :ref:`example_add_sub_domains`
-..
-     * :ref:`customize_all_virtual_hosts_globally`
+   * vhost-gen: :ref:`vhost_gen_virtual_host_templates`
+   * vhost-gen: :ref:`vhost_gen_customize_all_virtual_hosts_globally`
+   * vhost-gen: :ref:`vhost_gen_customize_specific_virtual_host`
+   * vhost-gen: :ref:`vhost_gen_example_add_sub_domains`
+
 
 .. _env_httpd_timeout_to_php_fpm:
 

docs/configuration-files/nginx-conf.rst

@@ -15,9 +15,11 @@ supplying custom configurations.
    Devilbox Auto-vhost generation feature. If you want to custimize your current virtual hosts
    have a look at:
 
-   * :ref:`customize_specific_virtual_host`
-..
-   * :ref:`customize_all_virtual_hosts_globally`
+   * vhost-gen: :ref:`vhost_gen_virtual_host_templates`
+   * vhost-gen: :ref:`vhost_gen_customize_all_virtual_hosts_globally`
+   * vhost-gen: :ref:`vhost_gen_customize_specific_virtual_host`
+   * vhost-gen: :ref:`vhost_gen_example_add_sub_domains`
+
 
 **Table of Contents**
 

docs/index.rst

@@ -85,10 +85,10 @@ host is ready to be served with your custom domain.
    :maxdepth: 2
    :numbered:
 
+   vhost-gen/virtual-host-templates
+   vhost-gen/customize-all-virtual-hosts-globally
    vhost-gen/customize-specific-virtual-host
    vhost-gen/example-add-subdomains
-..
-   vhost-gen/customize-all-virtual-hosts-globally
 
 
 .. toctree::

docs/maintenance/update-the-devilbox.rst

@@ -85,7 +85,7 @@ Keep ``vhost-gen`` templates in sync
 .. important::
    Whenever you check out a different version, make sure that the vhost-gen templates that have
    been copied to any virtual hosts are up-to-date with the templates provided in
-   ``templates/vhost-gen/``.
+   ``cfg/vhost-gen/``.
 
 
 Recreate container

docs/vhost-gen/customize-all-virtual-hosts-globally.rst

@@ -0,0 +1,73 @@
+.. _vhost_gen_customize_all_virtual_hosts_globally:
+
+************************************
+Customize all virtual hosts globally
+************************************
+
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+Prerequisite
+============
+
+Ensure you have read and understood how vhost-gen templates work and where to find them
+
+.. seealso:: :ref:`vhost_gen_virtual_host_templates`
+
+
+Apply templates globally to all vhosts
+======================================
+
+
+When applying those templates, you do it globally for all projects. The only exception is
+if you have already a specific vhost template for a project in place.
+
+.. seealso:: :ref:`vhost_gen_customize_specific_virtual_host`
+
+
+In order for template files to be picked up by the web server they must be copied to their correct
+filename.
+
++----------------+--------------------------+------------------+
+| Web server     | Example template         | Template name    |
++================+==========================+==================+
+| Apache 2.2     | ``apache22.yml-example`` | ``apache22.yml`` |
++----------------+--------------------------+------------------+
+| Apache 2.4     | ``apache24.yml-example`` | ``apache24.yml`` |
++----------------+--------------------------+------------------+
+| Nginx stable   | ``nginx.yml-example``    | ``nginx.yml``    |
++----------------+--------------------------+------------------+
+| Nginx mainline | ``nginx.yml-example``    | ``nginx.yml``    |
++----------------+--------------------------+------------------+
+
+.. note::
+   If you simply copy the files to their corresponding template file name, nothing will change
+   as those templates reflect the same values the web servers are using.
+
+
+Apache 2.2
+----------
+
+1. Navigate to ``cfg/vhost-gen/`` inside the Devilbox directory
+2. Copy ``apache22.yml-example`` to ``apache22.yml`` and restart the Devilbox
+3. Whenever you adjust ``apache22.yml``, you need to restart the Devilbox
+
+
+Apache 2.4
+----------
+
+1. Navigate to ``cfg/vhost-gen/`` inside the Devilbox directory
+2. Copy ``apache24.yml-example`` to ``apache24.yml`` and restart the Devilbox
+3. Whenever you adjust ``apache24.yml``, you need to restart the Devilbox
+
+
+Nginx stable and Nginx mainline
+-------------------------------
+
+1. Navigate to ``cfg/vhost-gen/`` inside the Devilbox directory
+2. Copy ``nginx.yml-example`` to ``nginx.yml`` and restart the Devilbox
+3. Whenever you adjust ``nginx.yml``, you need to restart the Devilbox
+

docs/vhost-gen/customize-specific-virtual-host.rst

@@ -1,6 +1,6 @@
 .. include:: /_includes/all.rst
 
-.. _customize_specific_virtual_host:
+.. _vhost_gen_customize_specific_virtual_host:
 
 *******************************
 Customize specific virtual host
@@ -37,9 +37,7 @@ Where do I find templates
 -------------------------
 
 The latest version of vhost-gen templates are shipped in the Devilbox git directory under
-``templates/vhost-gen``. You can however also download them directly from its own git directory.
-
-.. seealso:: https://github.com/devilbox/vhost-gen/tree/master/etc/templates.
+``cfg/vhost-gen/``.
 
 
 How does it work
@@ -47,7 +45,7 @@ How does it work
 
 By default new virtual hosts are automatically generated and enabled by vhost-gen and watcherp
 using the vanilla templates which are glued into the webserver Docker images. The used templates
-are exactly the same as what you will find in ``templates/vhost-gen``.
+are exactly the same as what you will find in ``cfg/vhost-gen/``.
 
 This ensures to have equal and sane default virtual host for all of your projects.
 If you want to have a different virtual host configuration for a specific project of yours,
@@ -72,7 +70,7 @@ Let's assume the following default values and one project named ``project-1``:
 +===============================+=======================================================+
 | Devilbox path                 | ``/home/user/devilbox``                               |
 +-------------------------------+-------------------------------------------------------+
-| Templates to copy from        | ``/home/user/devilbox/templates/vhost-gen``           |
+| Templates to copy from        | ``/home/user/devilbox/cfg/vhost-gen``                 |
 +-------------------------------+-------------------------------------------------------+
 | Project name                  | ``project-1``                                         |
 +-------------------------------+-------------------------------------------------------+
@@ -121,7 +119,7 @@ Then you can copy the templates.
 
 .. code-block:: bash
 
-   host> cp templates/vhost-gen/* ./data/www/project-1/.devilbox
+   host> cp cfg/vhost-gen/*.yml-example ./data/www/project-1/.devilbox
 
 .. note::
    You actually only need to copy the template of your chosen webserver (either Apache 2.2,
@@ -414,4 +412,5 @@ Further readings
 .. seealso::
    Have a look at the following examples which involve customizing vhost-gen templates:
 
-   * :ref:`example_add_sub_domains`
+   * :ref:`vhost_gen_virtual_host_templates`
+   * :ref:`vhost_gen_example_add_sub_domains`

docs/vhost-gen/example-add-subdomains.rst

@@ -1,6 +1,6 @@
 .. include:: /_includes/all.rst
 
-.. _example_add_sub_domains:
+.. _vhost_gen_example_add_sub_domains:
 
 ************************
 Example: add sub domains
@@ -121,7 +121,11 @@ you the option to customize the virtual host of this specific project.
    :ref:`customize_all_virtual_hosts_globally` and :ref:`customize_specific_virtual_host`
 
 .. note::
-   :ref:`customize_specific_virtual_host`
+   :ref:`vhost_gen_virtual_host_templates`
+     Ensure you have read and understand how to customize virtual hosts globally with ``vhost-gen``.
+   :ref:`vhost_gen_customize_all_virtual_hosts_globally`
+     Ensure you have read and understand how to customize virtual hosts globally with ``vhost-gen``.
+   :ref:`vhost_gen_customize_specific_virtual_host`
      Ensure you have read and understand how to customize your virtual host with ``vhost-gen``.
    :ref:`env_httpd_template_dir`
      Ensure you know what this variable does inside your ``.env`` file.
@@ -178,7 +182,7 @@ Ensure that the default ``vhost-gen`` templates have been copied to your project
    host> mkdir ./data/www/project-1/.devilbox
 
    # Copy vhost-gen templates
-   host> cp templates/vhost-gen/* ./data/www/project-1/.devilbox
+   host> cp cfg/vhost-gen/*.yml ./data/www/project-1/.devilbox
 
 By having done all prerequisite, your project should be available under http://my-project-1.loc
 
@@ -566,7 +570,7 @@ your new vhost-gen template has been read and the changes have applied.
 Checklist
 ---------
 
-1. Template files are copied from ``templates/vhost-gen/*`` to your project template dir (as
+1. Template files are copied from ``cfg/vhost-gen/*`` to your project template dir (as
    specified in ``.env`` via ``HTTPD_TEMPLATE_DIR``)
 2. Ensure the vhost-gen yaml files are valid (No tab characters)
 3. When templates are edited, the Devilbox is either restarted or the project directory is renamed

docs/vhost-gen/virtual-host-templates.rst

@@ -0,0 +1,97 @@
+.. include:: /_includes/all.rst
+
+.. _vhost_gen_virtual_host_templates:
+
+**********************
+Virtual host templates
+**********************
+
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+Overview
+========
+
+What is it?
+-----------
+
+vhost-gen templates are yaml files which contain a general definition for a virtual host definition.
+Those templates contain placeholders in the form of ``__<NAME>__`` which will be replaced by
+settings applied to the Devilbox.
+
+
+.. seealso:: |ext_lnk_project_vhost_gen|
+
+
+Template files
+--------------
+
+By default, vhost-gen templates are located within the Devilbox root directory under ``cfg/vhost-gen/``.
+The templates file names are suffixed with ``-example`` and are absolutely identical to what is
+shipped inside each Devilbox web server Docker container.
+
+.. code-block:: bash
+
+   host> tree -L 1 cfg/vhost-gen/
+
+   cfg/vhost-gen/
+   ├── apache22.yml-example
+   ├── apache24.yml-example
+   ├── nginx.yml-example
+   └── README.md
+
+   0 directories, 4 files
+
+.. note::
+   Also note that nginx stable and nginx mainline share the same template as their configuration
+   syntax is identical.
+
+Template sections
+-----------------
+
+All vhost-gen templates consist of three sections:
+
++----------------+----------------+
+| Section        | Description    |
++================+================+
+| ``vhost``      | |vhost|        |
++----------------+----------------+
+| ``vhost_type`` | |vhost_type|   |
++----------------+----------------+
+| ``features``   | |features|     |
++----------------+----------------+
+
+.. |vhost| replace:: This is the part that is actually rendered into the vhost configuration. All other |br| sections will be inserted into this one.
+.. |vhost_type| replace:: The vhost type determines the type of vhost: reverse proxy or document root based |br| vhost. The Devilbox currently does not support reverse proxy vhost.
+.. |features| replace:: The feature section contains many sub-sections that are replaced into the ``vhost`` |br| section before final rendering.
+
+
+Templates
+=========
+
+Apache 2.2 template
+-------------------
+
+.. literalinclude:: ../../cfg/vhost-gen/apache22.yml-example
+   :caption: apache22.yml
+   :language: yaml
+
+
+Apache 2.4 template
+-------------------
+
+.. literalinclude:: ../../cfg/vhost-gen/apache24.yml-example
+   :caption: apache24.yml
+   :language: yaml
+
+
+Nginx template
+--------------
+
+.. literalinclude:: ../../cfg/vhost-gen/nginx.yml-example
+   :caption: nginx.yml
+   :language: yaml
+