Documentation for vhost-gen templates

This commit is contained in:
cytopia 2018-08-06 21:42:03 +02:00
parent a1c6510131
commit 35546e7fa1
No known key found for this signature in database
GPG Key ID: 6D56EDB8695128A2
11 changed files with 212 additions and 34 deletions

View File

@ -1,5 +1,6 @@
# Global vhost-gen configurations # 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. In order for template files to be picked up by the web server they must have the correct name.

View File

@ -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 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. 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:: .. 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** **Table of Contents**

View File

@ -15,9 +15,11 @@ custom configurations.
Devilbox Auto-vhost generation feature. If you want to custimize your current virtual hosts Devilbox Auto-vhost generation feature. If you want to custimize your current virtual hosts
have a look at: have a look at:
* :ref:`customize_specific_virtual_host` * vhost-gen: :ref:`vhost_gen_virtual_host_templates`
.. * vhost-gen: :ref:`vhost_gen_customize_all_virtual_hosts_globally`
* :ref:`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** **Table of Contents**

View File

@ -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/ 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 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 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 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 host> cd path/to/devilbox
# Copy templates to your project directory # 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: 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, When you want to find out more how to actually customize each virtual host to its own need,
read up more on: read up more on:
* :ref:`customize_specific_virtual_host` * vhost-gen: :ref:`vhost_gen_virtual_host_templates`
* :ref:`example_add_sub_domains` * vhost-gen: :ref:`vhost_gen_customize_all_virtual_hosts_globally`
.. * vhost-gen: :ref:`vhost_gen_customize_specific_virtual_host`
* :ref:`customize_all_virtual_hosts_globally` * vhost-gen: :ref:`vhost_gen_example_add_sub_domains`
.. _env_httpd_timeout_to_php_fpm: .. _env_httpd_timeout_to_php_fpm:

View File

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

View File

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

View File

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

View File

@ -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

View File

@ -1,6 +1,6 @@
.. include:: /_includes/all.rst .. include:: /_includes/all.rst
.. _customize_specific_virtual_host: .. _vhost_gen_customize_specific_virtual_host:
******************************* *******************************
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 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. ``cfg/vhost-gen/``.
.. seealso:: https://github.com/devilbox/vhost-gen/tree/master/etc/templates.
How does it work 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 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 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. 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, 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`` | | 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`` | | Project name | ``project-1`` |
+-------------------------------+-------------------------------------------------------+ +-------------------------------+-------------------------------------------------------+
@ -121,7 +119,7 @@ Then you can copy the templates.
.. code-block:: bash .. 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:: .. note::
You actually only need to copy the template of your chosen webserver (either Apache 2.2, You actually only need to copy the template of your chosen webserver (either Apache 2.2,
@ -414,4 +412,5 @@ Further readings
.. seealso:: .. seealso::
Have a look at the following examples which involve customizing vhost-gen templates: 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`

View File

@ -1,6 +1,6 @@
.. include:: /_includes/all.rst .. include:: /_includes/all.rst
.. _example_add_sub_domains: .. _vhost_gen_example_add_sub_domains:
************************ ************************
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` :ref:`customize_all_virtual_hosts_globally` and :ref:`customize_specific_virtual_host`
.. note:: .. 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``. Ensure you have read and understand how to customize your virtual host with ``vhost-gen``.
:ref:`env_httpd_template_dir` :ref:`env_httpd_template_dir`
Ensure you know what this variable does inside your ``.env`` file. 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 host> mkdir ./data/www/project-1/.devilbox
# Copy vhost-gen templates # 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 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 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``) specified in ``.env`` via ``HTTPD_TEMPLATE_DIR``)
2. Ensure the vhost-gen yaml files are valid (No tab characters) 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 3. When templates are edited, the Devilbox is either restarted or the project directory is renamed

View File

@ -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