Merge pull request #340 from cytopia/global-vhost-gen-templates

Fix #144 Be able to use global vhost-gen templates
This commit is contained in:
cytopia 2018-08-06 22:23:34 +02:00 committed by GitHub
commit e91d5eac4f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
18 changed files with 286 additions and 73 deletions

5
.gitignore vendored
View File

@ -31,6 +31,11 @@
# Ignore compose override file
docker-compose.override.yml
# Ignore custom global vhost gen templates
/cfg/vhost-gen/apache22.conf
/cfg/vhost-gen/apache24.conf
/cfg/vhost-gen/nginx.conf
# Ignore custom HTTPD configs
/cfg/apache-2.2/*.conf
/cfg/apache-2.4/*.conf

View File

@ -81,38 +81,43 @@ Find documentation and help here
#### Quick start
<table width="100%" style="width:100%; display:table;">
<thead>
<tr>
<th width="50%" style="width:33%;">Linux and MacOS</th>
<th width="50%" style="width:33%;">Windows</th>
</tr>
</thead>
<tbody style="vertical-align: bottom;">
<tr>
<td>
<pre># Get the Devilbox
$ git clone https://github.com/cytopia/devilbox</pre>
<pre># Create docker-compose environment file
$ cd devilbox
$ cp env-example .env</pre>
<pre># Edit your configuration
$ vim .env</pre>
<pre># Start all container
$ docker-compose up</pre>
</td>
<td>
1. Clone <code>https://github.com/cytopia/devilbox</code> to <code>C:\devilbox</code> with <a href="https://git-scm.com/downloads">Git for Windows</a><br/><br/>
2. Copy <code>C:\devilbox\env-example</code> to <code>C:\devilbox\.env</code><br/><br/>
3. Edit <code>C:\devilbox\.env</code><br/><br/>
4. <a href="https://devilbox.readthedocs.io/en/latest/howto/terminal/open-terminal-on-win.html">Open a terminal on Windows</a> and type:<br/><br/><br/>
<pre># Start all container
C:\devilbox> docker-compose up</pre></div>
</td>
</tr>
</tbody>
</table>
> **Documentation:**
> [Install the Devilbox](https://devilbox.readthedocs.io/en/latest/getting-started/install-the-devilbox.html) |
> [Start the Devilbox](https://devilbox.readthedocs.io/en/latest/getting-started/start-the-devilbox.html) |
> [.env file](https://devilbox.readthedocs.io/en/latest/configuration-files/env-file.html)
##### Linux and MacOS
```bash
# Get the Devilbox
$ git clone https://github.com/cytopia/devilbox
$ cd devilbox
# Create docker-compose environment file
$ cp env-example .env
# Edit your configuration
$ vim .env
# Start all containers
$ docker-compose up
```
##### Windows
1. Clone https://github.com/cytopia/devilbox to `C:\devilbox` with [Git for Windows](https://git-scm.com/download/win)
2. Copy `C:\devilbox\env-example` to `C:\devilbox\.env`
3. Adjust `C:\devilbox\.env` with your favourite editor
4. [Open terminal on Windows](https://devilbox.readthedocs.io/en/latest/howto/terminal/open-terminal-on-win.html) and type:
```bash
C:\> cd C:\devilbox
C:\devilbox> docker-compose up
```
#### Selective start
@ -271,17 +276,26 @@ You can also work directly inside the php container. Simply use the bundled scri
The `PS1` will automatically be populated with current chosen php version.
Navigate the the Devilbox directory and type the below listed command:
##### Linux and MacOS
```bash
host> ./shell.sh
devilbox@php-7.0.19 in /shared/httpd $
```
##### Windows
```bash
C:\devilbox> shell.bat
devilbox@php-7.0.19 in /shared/httpd $
```
<table width="100%" style="width:100%; display:table;">
<thead>
<tr>
<th width="50%" style="width:33%;">Linux and MacOS</th>
<th width="50%" style="width:33%;">Windows</th>
</tr>
</thead>
<tbody style="vertical-align: bottom;">
<tr>
<td>
<pre>host> ./shell.sh
devilbox@php-7.0.19 in /shared/httpd $</pre>
</td>
<td>
<pre>C:\devilbox> shell.bat
devilbox@php-7.0.19 in /shared/httpd $</pre>
</td>
</tr>
</tbody>
</table>
Your projects can be found in `/shared/httpd`. DNS records are automatically available inside the php container. Also every other service will be available on `127.0.0.1` inside the php container (tricky socat port-forwarding).

0
cfg/vhost-gen/.keepme Normal file
View File

14
cfg/vhost-gen/README.md Normal file
View File

@ -0,0 +1,14 @@
# 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.
Copy the example templates to a new file with the correct name.
| 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` |

View File

@ -206,7 +206,7 @@ services:
# Web Server
# ------------------------------------------------------------
httpd:
image: devilbox/${HTTPD_SERVER:-nginx-stable}:0.21
image: devilbox/${HTTPD_SERVER:-nginx-stable}:0.22
environment:
@ -281,6 +281,9 @@ services:
# Mount custom web server config directory
- ${DEVILBOX_PATH}/cfg/${HTTPD_SERVER}:/etc/httpd-custom.d
# Mount custom vhost-templates
- ${DEVILBOX_PATH}/cfg/vhost-gen:/etc/vhost-gen.d
# Mount logs
- ${DEVILBOX_PATH}/log/${HTTPD_SERVER}:/var/log/${HTTPD_SERVER}

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

View File

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

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/
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:

View File

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

View File

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

View File

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

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
.. _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`

View File

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

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