ExternalVendorCode/devilbox
1
0
Fork 0
mirror of https://github.com/cytopia/devilbox.git synced 2025-04-08 11:34:14 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Add autostart and reverse proxy documentation

Browse Source
This commit is contained in:
cytopia 2018-12-31 13:14:29 +01:00
parent 782a7c05be
commit 83eb20d138
No known key found for this signature in database
GPG Key ID: 6D56EDB8695128A2
15 changed files with 1792 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
docs/_includes/links/blogs.rst
View File

@ -21,3 +21,15 @@
<a target="_blank" href="https://docs.joomla.org/GSOC_2017">
Google Summer of Code 2017 <img src="https://raw.githubusercontent.com/cytopia/icons/master/11x11/ext-link.png" />
</a>
.. |ext_lnk_blog_drupalcamp_ghent_2018_slides| raw:: html
<a target="_blank" href="https://docs.google.com/presentation/d/1MvSwPlFL3TozWBtwpfNUTKVOvTbYzRY6GBQ9v2VS_GA/edit#slide=id.g45ef3f2bc6_2_54">
Drupalcamp Ghent 2018: Slides <img src="https://raw.githubusercontent.com/cytopia/icons/master/11x11/ext-link.png" />
</a>
.. |ext_lnk_blog_drupalcamp_ghent_2018_presentation| raw:: html
<a target="_blank" href="https://www.youtube.com/watch?v=88Sr0aNvVm0">
Drupalcamp Ghent 2018: Presentation <img src="https://raw.githubusercontent.com/cytopia/icons/master/11x11/ext-link.png" />
</a>

6
docs/_includes/links/tools.rst
View File

@ -189,6 +189,12 @@
Photon CMS cli <img src="https://raw.githubusercontent.com/cytopia/icons/master/11x11/ext-link.png" />
</a>
.. |ext_lnk_tool_pm2| raw:: html
<a target="_blank" href="https://github.com/Unitech/pm2">
pm2 <img src="https://raw.githubusercontent.com/cytopia/icons/master/11x11/ext-link.png" />
</a>
.. |ext_lnk_tool_sass| raw:: html
<a target="_blank" href="https://sass-lang.com">

99
docs/autostart/autostarting-nodejs-apps.rst Normal file
View File

@ -0,0 +1,99 @@
.. include:: /_includes/all.rst
.. _autostarting_nodejs_apps:
************************
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
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)
**Table of Contents**
.. contents:: :local:
Self-built
==========
Simply add a script ending by ``.sh`` to the ``autostart/`` directory that will accomplish this.
The following example will make use of |ext_lnk_tool_pm2| to spin up your NodeJS application.
Assumption
----------
* Path to your NodeJS project (within the Docker container): ``/shared/httpd/my-node/src``
* Name of the JS file to startup: ``index.js``
The script
----------
Add the following script to ``autostart/``
.. code-block:: bash
:caption: autostart/myscript.sh
su -c "cd /shared/httpd/my-node/src; pm2 start index.js" -l devilbox
* The whole command is wrapped into ``su`` to ensure the application will be started as the user ``devilbox``.
* ``cd`` tells it to you enter the directory where ``index.js`` can be found
* And finally |ext_lnk_tool_pm2| will take care about starting up your javascript file.
Once the Devilbox is running, you can enter the PHP container and verify with ``pm2 list`` that
everything is running as expected.
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|.
The following script is provided in ``autostart/run-node-js-projects.sh-example`` and needs to be
copied to a file ending by ``.sh``
.. code-block:: bash
host> cd /path/to/devilbox
host> cd autostart
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)
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.
.. literalinclude:: ../../autostart/run-node-js-projects.sh
:caption: autostart/run-node-js-projects.sh
:language: bash
:emphasize-lines: 16
Reverse proxy NodeJS
====================
If you also want to know how to reverse proxy your NodeJS service and have it available via the web
server including HTTPS support have a look at the following links:
.. seealso::
* :ref:`reverse_proxy_with_https`
* :ref:`example_setup_reverse_proxy_nodejs`
Imagine you have started an application within the PHP container that creates a listening port
(e.g.: NodeJS). This will now only listen on the PHP container and you would have to adjust
the docker-compose.yml definition in order to have that port available outside to your host OS.
Alternatively, there is a simple way to reverse proxy it to the already running web server and even
make use of the already available HTTPS feature.

98
docs/autostart/custom-scripts-globally.rst Normal file
View File

@ -0,0 +1,98 @@
.. _custom_scripts_globally:
***********************
Custom scripts globally
***********************
You can provide custom startup commands via bash scripts that are executed by all PHP container.
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:`autostarting_nodejs_apps`
.. note::
Global scripts are always executed **after** per PHP version scripts.
**Table of Contents**
.. contents:: :local:
General
=======
You can add shell scripts that are executed for all PHP container equally.
.. 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
-----
Startup scripts can be added to ``autostart/``.
.. code-block:: bash
:emphasize-lines: 3
host> ls -l path/to/devilbox/
drwxr-xr-x 2 cytopia cytopia 4096 Mar 5 21:53 autostart/
drwxr-xr-x 2 cytopia cytopia 4096 Mar 5 21:53 backups/
drwxr-xr-x 2 cytopia cytopia 4096 Mar 5 21:53 bash/
drwxr-xr-x 2 cytopia cytopia 4096 Mar 5 21:53 ca/
drwxr-xr-x 2 cytopia cytopia 4096 Mar 5 21:53 cfg/
drwxr-xr-x 2 cytopia cytopia 4096 Mar 5 21:53 compose/
drwxr-xr-x 2 cytopia cytopia 4096 Mar 5 21:53 data/
drwxr-xr-x 2 cytopia cytopia 4096 Mar 5 21:53 docs/
drwxr-xr-x 2 cytopia cytopia 4096 Mar 5 21:53 mail/
drwxr-xr-x 2 cytopia cytopia 4096 Mar 5 21:53 mod/
Custom scripts are added by placing a file into ``autostart/``. The file must end by ``.sh`` in
order to be executed by the PHP container.
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.
Examples
========
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``
inside the shell script.
The following example will install ``grunt`` and start a NodeJS application as the devilbox user
for whatever PHP container has been started.
.. code-block:: bash
:caption: autostart/myscript.sh
# Install grunt as devilbox user
su -c "npm install grunt" -l devilbox
# Start a NodeJS application with pm2 as devilbox user
su -c "cd /shared/httpd/my-node/src/; pm2 start index.js" -l devilbox

107
docs/advanced/custom-startup-commands.rst → docs/autostart/custom-scripts-per-php-version.rst
View File

@ -1,13 +1,23 @@
.. _custom_startup_commands:
.. _custom_scripts_per_php_version:
***********************
Custom startup commands
***********************
******************************
Custom scripts per PHP version
******************************
You can provide custom startup commands via bash scripts to each of the PHP container.
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_globally` (equal for all PHP versions)
* :ref:`autostarting_nodejs_apps`
.. note::
Per PHP version scripts are always executed **before** global scripts.
**Table of Contents**
.. contents:: :local:
@ -16,9 +26,15 @@ the initial startup.
General
=======
You can add custom ``bash`` scripts for each PHP version separately. Provided scripts must end
by the file extension ``.sh`` and should be executable. Anything not ending by ``.sh`` will be
ignored.
You can add custom shell scripts for each PHP version separately.
.. 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
-----
@ -59,15 +75,13 @@ How
---
The scripts will always be executed inside the PHP container (Debian Linux) and will be run with
``root`` privileges.
``root`` privileges. It is however possible to drop privileges within the script to have them
executed as a normal user.
Examples
========
The following examples should already exist as example files within ``cfg/php-startup-X.Y``, but
will covered here as well to show some real world examples of what can be done with startup scripts.
Installing Microsoft ODBC driver
--------------------------------
@ -94,7 +108,7 @@ Paste the following into ``ms-obbc.sh`` and **ensure to accept the EULA** by cha
``ACCEPT_EULA=N`` to ``ACCEPT_EULA=Y``.
.. code-block:: bash
:caption: ms-odbc.sh
:caption: cfg/php-startup-7.1/install-ms-odbc.sh
:emphasize-lines: 18
!/bin/bash
@ -158,64 +172,21 @@ Paste the following into ``ms-obbc.sh`` and **ensure to accept the EULA** by cha
The script will not work, if you have not accepted the EULA.
Installing Oracle oci8 and pdo_oci PHP modules
----------------------------------------------
Running commands as devilbox user
---------------------------------
This example will install Oracle instaclient as well as PHP modules ``pdo_oci`` and ``oci8`` in
order to use PHP to connect to Oracle. This startup script will only be provided to PHP 7.2
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``
inside the shell script.
The following example will install ``grunt`` and start a NodeJS application as the devilbox user
for the PHP 7.1 Docker container only.
.. code-block:: bash
:caption: cfg/php-startup-7.1/myscript.sh
# Navigate to starup dir of PHP 7.2
host> cd path/to/devilbox/cfg/php-startup-7.2
# Install grunt as devilbox user
su -c "npm install grunt" -l devilbox
# Create an .sh file
host> touch oracle.sh
# Open the file in your favourite editor
host> vi oracle.sh
Paste the following into ``oracle.sh``:
.. code-block:: bash
:caption: oracle.sh
#!/bin/bash
#
# https://yum.oracle.com/repo/OracleLinux/OL7/oracle/instantclient/x86_64/
#
# Install 'alien' to install rpm packages
apt-get update -q
DEBIAN_FRONTEND=noninteractive apt-get install -qq -y --no-install-recommends --no-install-suggests alien
# Instantclient (basic lite)
curl -o /tmp/oracle-instantclient18.3-basiclite-18.3.0.0.0-2.x86_64.rpm https://yum.oracle.com/repo/OracleLinux/OL7/oracle/instantclient/x86_64/getPackage/oracle-instantclient18.3-basiclite-18.3.0.0.0-2.x86_64.rpm
# Instantclient (devel)
curl -o /tmp/oracle-instantclient18.3-devel-18.3.0.0.0-2.x86_64.rpm https://yum.oracle.com/repo/OracleLinux/OL7/oracle/instantclient/x86_64/getPackage/oracle-instantclient18.3-devel-18.3.0.0.0-2.x86_64.rpm
# Install RPMs
alien -i /tmp/oracle-instantclient18.3-basiclite-18.3.0.0.0-2.x86_64.rpm
alien -i /tmp/oracle-instantclient18.3-devel-18.3.0.0.0-2.x86_64.rpm
# Rempve RPMs
rm -f /tmp/oracle-instantclient18.3-basiclite-18.3.0.0.0-2.x86_64.rpm
rm -f /tmp/oracle-instantclient18.3-devel-18.3.0.0.0-2.x86_64.rpm
# Necessary symlinks
ln -s /usr/lib/oracle/18.3/client64/lib/libmql1.so /usr/lib/
ln -s /usr/lib/oracle/18.3/client64/lib/libipc1.so /usr/lib/
ln -s /usr/lib/oracle/18.3/client64/lib/libnnz18.so /usr/lib/
ln -s /usr/lib/oracle/18.3/client64/lib/libons.so /usr/lib/
ln -s /usr/lib/oracle/18.3/client64/lib/libclntshcore.so.18.1 /usr/lib/
# Build and install PHP extension oci8
docker-php-ext-configure oci8 --with-oci8=instantclient
docker-php-ext-install oci8
# Build and install PHP extension pdo_oci
docker-php-ext-configure pdo_oci --with-pdo-oci=instantclient,/usr,18.3
docker-php-ext-install pdo_oci
# Start a NodeJS application with pm2 as devilbox user
su -c "cd /shared/httpd/my-node/src/; pm2 start index.js" -l devilbox

440
docs/examples/setup-reverse-proxy-nodejs.rst Normal file
View File

@ -0,0 +1,440 @@
.. include:: /_includes/all.rst
.. _example_setup_reverse_proxy_nodejs:
**************************
Setup reverse proxy NodeJS
**************************
This example will walk you through creating a NodeJS hello world application, which is started
automatically on ``docker-compose up`` via |ext_lnk_tool_pm2|, will be proxied to the web server and can be reached via valid HTTPS.
.. note::
It is also possible to attach a leight-weight NodeJS container to the Devilbox instead of running
this in the PHP container. See here for details: :ref:`reverse_proxy_with_custom_docker`
**Table of Contents**
.. contents:: :local:
Overview
========
The following configuration will be used:
+--------------+--------------------------+-------------+------------+---------------------------------------------+
| Project name | VirtualHost directory | Database | TLD_SUFFIX | Project URL |
+==============+==========================+=============+============+=============================================+
| my-node | /shared/httpd/my-node | - | loc | http://my-node.loc |br| https://my-node.loc |
+--------------+--------------------------+-------------+------------+---------------------------------------------+
Additionally we will set the listening port of the NodeJS appliation to ``4000`` inside the PHP container.
We also want NodeJS running regardless of which PHP container will bestarted (global autostart).
.. 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`.
Walk through
============
It will be ready in nine simple steps:
1. Enter the PHP container
2. Create a new VirtualHost directory
3. Create NodeJS hello world application
4. Create *virtual* docroot directory
5. Add reverse proxy vhost-gen config files
6. Create autostart script
7. Setup DNS record
8. Restart the Devilbox
9. Visit http://my-node.loc in your browser
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-node
.. seealso:: :ref:`env_tld_suffix`
3. Create NodeJS application
----------------------------
.. code-block:: bash
# Navigate to your project directory
devilbox@php-7.0.20 in /shared/httpd $ cd my-node
# Create a directory which will hold the source code
devilbox@php-7.0.20 in /shared/httpd/my-node $ mkdir src
# Create the index.js file with your favourite editor
devilbox@php-7.0.20 in /shared/httpd/my-node/src $ vi index.js
.. code-block:: javascript
:caption: index.js
// Load the http module to create an http server.
var http = require('http');
// Configure our HTTP server to respond with Hello World to all requests.
var server = http.createServer(function (request, response) {
response.writeHead(200, {"Content-Type": "text/plain"});
response.end("Hello World\n");
});
// Listen on port 3000
server.listen(3000);
4. Create *virtual* docroot directory
-------------------------------------
Every project for the Devilbox requires a ``htdocs`` directory present inside the project dir.
For a reverse proxy this is not of any use, but rather only for the Intranet vhost page to stop
complaining about the missing ``htdocs`` directory. So that's why this is only a *virtual* directory
which will not hold any data.
.. code-block:: bash
# Navigate to your project directory
devilbox@php-7.0.20 in /shared/httpd $ cd my-node
# Create the docroot directory
devilbox@php-7.0.20 in /shared/httpd/my-node $ mkdir htdocs
.. seealso:: :ref:`env_httpd_docroot_dir`
5. Add reverse proxy vhost-gen config files
-------------------------------------------
5.1 Create vhost-gen template directory
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Before we can copy the vhost-gen templates, we must create the ``.devilbox`` template directory
inside the project directory.
.. code-block:: bash
# Navigate to your project directory
devilbox@php-7.0.20 in /shared/httpd $ cd my-node
# Create the .devilbox template directory
devilbox@php-7.0.20 in /shared/httpd/my-node $ mkdir .devilbox
.. seealso:: :ref:`env_httpd_template_dir`
5.2 Copy vhost-gen templates
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Now we can copy and adjust the vhost-gen reverse proxy files for Apache 2.2, Apache 2.4 and Nginx.
The reverse vhost-gen templates are available in ``cfg/vhost-gen``:
.. code-block:: bash
:emphasize-lines: 4,6,8
host> tree -L 1 cfg/vhost-gen/
cfg/vhost-gen/
├── apache22.yml-example-rproxy
├── apache22.yml-example-vhost
├── apache24.yml-example-rproxy
├── apache24.yml-example-vhost
├── nginx.yml-example-rproxy
├── nginx.yml-example-vhost
└── README.md
0 directories, 7 files
For this example we will copy all ``*-example-rproxy`` files into ``/shared/httpd/my-node/.devilbox``
to ensure this will work with all web servers.
.. code-block:: bash
host> cd /path/to/devilbox
host> cp cfg/vhost-gen/apache22.yml-example-rproxy data/www/my-node/.devilbox/apache22.yml
host> cp cfg/vhost-gen/apache24.yml-example-rproxy data/www/my-node/.devilbox/apache24.yml
host> cp cfg/vhost-gen/nginx.yml-example-rproxy data/www/my-node/.devilbox/nginx.yml
5.3 Adjust ports
^^^^^^^^^^^^^^^^
By default, all vhost-gen templates will forward requests to port ``8000`` into the PHP container.
Our current example however uses port ``4000``, so we must change that accordingly for all three
templates.
5.3.1 Adjust Apache 2.2 template
""""""""""""""""""""""""""""""""
Open the ``apache22.yml`` vhost-gen template in your project:
.. code-block:: bash
host> cd /path/to/devilbox
host> vi data/www/my-node/.devilbox/apache22.yml
Find the two lines with ``ProxyPass`` and ``ProxyPassReverse`` and change the port from ``8000``
to ``4000``
.. code-block:: yaml
:caption: data/www/my-node/.devilbox/apache22.yml
:emphasize-lines: 16,17
# ... more lines above ... #
###
### Basic vHost skeleton
###
vhost: |
<VirtualHost __DEFAULT_VHOST__:__PORT__>
ServerName __VHOST_NAME__
CustomLog "__ACCESS_LOG__" combined
ErrorLog "__ERROR_LOG__"
# Reverse Proxy definition (Ensure to adjust the port, currently '8000')
ProxyRequests On
ProxyPreserveHost On
ProxyPass / http://php:4000/
ProxyPassReverse / http://php:4000/
# ... more lines below ... #
5.3.2 Adjust Apache 2.4 template
""""""""""""""""""""""""""""""""
Open the ``apache24.yml`` vhost-gen template in your project:
.. code-block:: bash
host> cd /path/to/devilbox
host> vi data/www/my-node/.devilbox/apache24.yml
Find the two lines with ``ProxyPass`` and ``ProxyPassReverse`` and change the port from ``8000``
to ``4000``
.. code-block:: yaml
:caption: data/www/my-node/.devilbox/apache24.yml
:emphasize-lines: 16,17
# ... more lines above ... #
###
### Basic vHost skeleton
###
vhost: |
<VirtualHost __DEFAULT_VHOST__:__PORT__>
ServerName __VHOST_NAME__
CustomLog "__ACCESS_LOG__" combined
ErrorLog "__ERROR_LOG__"
# Reverse Proxy definition (Ensure to adjust the port, currently '8000')
ProxyRequests On
ProxyPreserveHost On
ProxyPass / http://php:4000/
ProxyPassReverse / http://php:4000/
# ... more lines below ... #
5.3.3 Adjust Nginx template
"""""""""""""""""""""""""""
Open the ``nginx.yml`` vhost-gen template in your project:
.. code-block:: bash
host> cd /path/to/devilbox
host> vi data/www/my-node/.devilbox/nginx.yml
Find the lines with ``proxy_pass`` and change the port from ``8000`` to ``4000``
.. code-block:: yaml
:caption: data/www/my-node/.devilbox/nginx.yml
:emphasize-lines: 18
# ... more lines above ... #
###
### Basic vHost skeleton
###
vhost: |
server {
listen __PORT____DEFAULT_VHOST__;
server_name __VHOST_NAME__;
access_log "__ACCESS_LOG__" combined;
error_log "__ERROR_LOG__" warn;
# Reverse Proxy definition (Ensure to adjust the port, currently '8000')
location / {
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_pass http://php:4000;
}
# ... more lines below ... #
6. Create autostart script
--------------------------
For NodeJS applications, the Devilbox already bundles an autostart template which you can use
and simply just add the path of your NodeJS application. This template does nothing by default
as its file name does not end by ``.sh``. So let's have a look at the template from ``autostart/run-node-js-projects.sh-example``.
The location where you will have to add your path is highlighted:
.. literalinclude:: ../../autostart/run-node-js-projects.sh-example
:caption: autostart/run-node-js-projects.sh-example
:language: bash
:emphasize-lines: 15
So in order to proceed copy this file inside the ``autostart/`` directory of the Devilbox git directory
to a new file ending by ``.sh``
.. code-block:: bash
host> cd /path/to/devilbox
# Navigate to the autostart directory
host> cd autostart
# Copy the template
host> cp run-node-js-projects.sh-example run-node-js-projects.sh
# Adjust the template and add your path:
host> vi run-node-js-projects.sh
.. code-block:: bash
:caption: autostart/run-node-js-projects.sh
:emphasize-lines: 7
# ... more lines above ... #
# Add the full paths of your Nodejs projects startup files into this array
# Each project separated by a newline and enclosed in double quotes. (No commas!)
# Paths are internal paths inside the PHP container.
NODE_PROJECTS=(
"/shared/httpd/my-node/js/index.js"
)
# ... more lines below ... #
.. 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`
7. 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-node.loc
.. seealso::
* :ref:`howto_add_project_hosts_entry_on_mac`
* :ref:`howto_add_project_hosts_entry_on_win`
* :ref:`setup_auto_dns`
8. Restart the Devilbox
-----------------------
Now for those changes to take affect, you will have to restart the Devilbox.
.. code-block:: bash
host> cd /path/to/devilbox
# Stop the Devilbox
host> docker-compose down
host> docker-compose rm -f
# Start the Devilbox
host> docker-compose up -d php httpd bind
9. Open your browser
--------------------
All set now, you can visit http://my-node.loc or https://my-node.loc in your browser.
The NodeJS application has been started up automatically and the reverse proxy will direct all
requests to it.
.. seealso:: :ref:`setup_valid_https`
Managing NodeJS
===============
If you have never worked with |ext_lnk_tool_pm2|, I suggest to visit their website and get familiar
with the available commands. A quick guide is below:
.. code-block:: bash
# Navigate to Devilbox git directory
host> cd /path/to/devilbox
# Enter the PHP container
host> ./shell.sh
# List your running NodeJS apps
devilbox@php-7.0.20 in /shared/httpd $ pm2 list
┌──────────┬────┬─────────┬──────┬──────┬────────┬─────────┬────────┬─────┬───────────┬──────────┬──────────┐
│ App name │ id │ version │ mode │ pid │ status │ restart │ uptime │ cpu │ mem │ user │ watching │
├──────────┼────┼─────────┼──────┼──────┼────────┼─────────┼────────┼─────┼───────────┼──────────┼──────────┤
│ index │ 0 │ N/A │ fork │ 1906 │ online │ 0 │ 42h │ 0% │ 39.7 MB │ devilbox │ disabled │
└──────────┴────┴─────────┴──────┴──────┴────────┴─────────┴────────┴─────┴───────────┴──────────┴──────────┘

428
docs/examples/setup-reverse-proxy-sphinx-docs.rst Normal file
View File

@ -0,0 +1,428 @@
.. include:: /_includes/all.rst
.. _example_setup_reverse_proxy_sphinx_docs:
*******************************
Setup reverse proxy Sphinx docs
*******************************
This example will walk you through creating a Sphinx documentation, which is started
automatically on ``docker-compose up``, will be proxied to the web server and can be reached via valid HTTPS.
.. note::
It is also possible to attach a leight-weight Python container to the Devilbox instead of running
this in the PHP container. See here for details: :ref:`reverse_proxy_with_custom_docker`
**Table of Contents**
.. contents:: :local:
Overview
========
The following configuration will be used:
+--------------+--------------------------+-------------+------------+-------------------------------------------------+
| Project name | VirtualHost directory | Database | TLD_SUFFIX | Project URL |
+==============+==========================+=============+============+=================================================+
| my-sphinx | /shared/httpd/my-sphinx | - | loc | http://my-sphinx.loc |br| https://my-sphinx.loc |
+--------------+--------------------------+-------------+------------+-------------------------------------------------+
Additionally we will set the listening port of the Sphinx appliation to ``4000`` inside the PHP container.
We also want Sphinx running and autostarted only in the PHP 7.2 container (local autostart) and
have all its required Python packages installed during ``docker-compose up``.
.. 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`.
Walk through
============
It will be ready in nine simple steps:
1. Enter the PHP container
2. Create a new VirtualHost directory
3. Create basic Sphinx project
4. Create *virtual* docroot directory
5. Add reverse proxy vhost-gen config files
6. Create autostart script
7. Setup DNS record
8. Restart the Devilbox
9. Visit http://my-sphinx.loc in your browser
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-sphinx
.. seealso:: :ref:`env_tld_suffix`
3. Create basic Sphinx project
------------------------------
.. code-block:: bash
# Navigate to your project directory
devilbox@php-7.0.20 in /shared/httpd $ cd my-sphinx
# Create a directory which will hold the documentation source code
devilbox@php-7.0.20 in /shared/httpd/my-sphinx $ mkdir doc
Create a basic Sphinx configuration file:
.. code-block:: python
:caption: /shared/httpd/my-sphinx/doc/conf.py
source_suffix = '.rst'
master_doc = 'index'
html_theme = 'default'
exclude_patterns = [
u'_build/*'
]
Create the table of contents file:
.. code-block:: rst
:caption: /shared/httpd/my-sphinx/doc/index.rst
.. :hidden:
*******
My Docs
*******
Description
.. toctree::
:maxdepth: 2
page1
Create the first page ``page1``:
.. code-block:: rst
:caption: /shared/httpd/my-sphinx/doc/page1.rst
******
Page 1
******
Hello world
4. Create *virtual* docroot directory
-------------------------------------
Every project for the Devilbox requires a ``htdocs`` directory present inside the project dir.
For a reverse proxy this is not of any use, but rather only for the Intranet vhost page to stop
complaining about the missing ``htdocs`` directory. So that's why this is only a *virtual* directory
which will not hold any data.
.. code-block:: bash
# Navigate to your project directory
devilbox@php-7.0.20 in /shared/httpd $ cd my-sphinx
# Create the docroot directory
devilbox@php-7.0.20 in /shared/httpd/my-sphinx $ mkdir htdocs
.. seealso:: :ref:`env_httpd_docroot_dir`
5. Add reverse proxy vhost-gen config files
-------------------------------------------
5.1 Create vhost-gen template directory
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Before we can copy the vhost-gen templates, we must create the ``.devilbox`` template directory
inside the project directory.
.. code-block:: bash
# Navigate to your project directory
devilbox@php-7.0.20 in /shared/httpd $ cd my-sphinx
# Create the .devilbox template directory
devilbox@php-7.0.20 in /shared/httpd/my-sphinx $ mkdir .devilbox
.. seealso:: :ref:`env_httpd_template_dir`
5.2 Copy vhost-gen templates
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Now we can copy and adjust the vhost-gen reverse proxy files for Apache 2.2, Apache 2.4 and Nginx.
The reverse vhost-gen templates are available in ``cfg/vhost-gen``:
.. code-block:: bash
:emphasize-lines: 4,6,8
host> tree -L 1 cfg/vhost-gen/
cfg/vhost-gen/
├── apache22.yml-example-rproxy
├── apache22.yml-example-vhost
├── apache24.yml-example-rproxy
├── apache24.yml-example-vhost
├── nginx.yml-example-rproxy
├── nginx.yml-example-vhost
└── README.md
0 directories, 7 files
For this example we will copy all ``*-example-rproxy`` files into ``/shared/httpd/my-sphinx/.devilbox``
to ensure this will work with all web servers.
.. code-block:: bash
host> cd /path/to/devilbox
host> cp cfg/vhost-gen/apache22.yml-example-rproxy data/www/my-sphinx/.devilbox/apache22.yml
host> cp cfg/vhost-gen/apache24.yml-example-rproxy data/www/my-sphinx/.devilbox/apache24.yml
host> cp cfg/vhost-gen/nginx.yml-example-rproxy data/www/my-sphinx/.devilbox/nginx.yml
5.3 Adjust ports
^^^^^^^^^^^^^^^^
By default, all vhost-gen templates will forward requests to port ``8000`` into the PHP container.
Our current example however uses port ``4000``, so we must change that accordingly for all three
templates.
5.3.1 Adjust Apache 2.2 template
""""""""""""""""""""""""""""""""
Open the ``apache22.yml`` vhost-gen template in your project:
.. code-block:: bash
host> cd /path/to/devilbox
host> vi data/www/my-sphinx/.devilbox/apache22.yml
Find the two lines with ``ProxyPass`` and ``ProxyPassReverse`` and change the port from ``8000``
to ``4000``
.. code-block:: yaml
:caption: data/www/my-sphinx/.devilbox/apache22.yml
:emphasize-lines: 16,17
# ... more lines above ... #
###
### Basic vHost skeleton
###
vhost: |
<VirtualHost __DEFAULT_VHOST__:__PORT__>
ServerName __VHOST_NAME__
CustomLog "__ACCESS_LOG__" combined
ErrorLog "__ERROR_LOG__"
# Reverse Proxy definition (Ensure to adjust the port, currently '8000')
ProxyRequests On
ProxyPreserveHost On
ProxyPass / http://php:4000/
ProxyPassReverse / http://php:4000/
# ... more lines below ... #
5.3.2 Adjust Apache 2.4 template
""""""""""""""""""""""""""""""""
Open the ``apache24.yml`` vhost-gen template in your project:
.. code-block:: bash
host> cd /path/to/devilbox
host> vi data/www/my-sphinx/.devilbox/apache24.yml
Find the two lines with ``ProxyPass`` and ``ProxyPassReverse`` and change the port from ``8000``
to ``4000``
.. code-block:: yaml
:caption: data/www/my-sphinx/.devilbox/apache24.yml
:emphasize-lines: 16,17
# ... more lines above ... #
###
### Basic vHost skeleton
###
vhost: |
<VirtualHost __DEFAULT_VHOST__:__PORT__>
ServerName __VHOST_NAME__
CustomLog "__ACCESS_LOG__" combined
ErrorLog "__ERROR_LOG__"
# Reverse Proxy definition (Ensure to adjust the port, currently '8000')
ProxyRequests On
ProxyPreserveHost On
ProxyPass / http://php:4000/
ProxyPassReverse / http://php:4000/
# ... more lines below ... #
5.3.3 Adjust Nginx template
"""""""""""""""""""""""""""
Open the ``nginx.yml`` vhost-gen template in your project:
.. code-block:: bash
host> cd /path/to/devilbox
host> vi data/www/my-sphinx/.devilbox/nginx.yml
Find the lines with ``proxy_pass`` and change the port from ``8000`` to ``4000``
.. code-block:: yaml
:caption: data/www/my-sphinx/.devilbox/nginx.yml
:emphasize-lines: 18
# ... more lines above ... #
###
### Basic vHost skeleton
###
vhost: |
server {
listen __PORT____DEFAULT_VHOST__;
server_name __VHOST_NAME__;
access_log "__ACCESS_LOG__" combined;
error_log "__ERROR_LOG__" warn;
# Reverse Proxy definition (Ensure to adjust the port, currently '8000')
location / {
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_pass http://php:4000;
}
# ... more lines below ... #
6. Create autostart script
--------------------------
Remember, we only wanted to have our Sphinx application run on the PHP 7.2 container, so we will create
a autostart script only for that container.
Navigate to ``cfg/php-startup-7.2/`` in the Devilbox git directory and create a new shell script
ending by ``.sh``
.. code-block:: bash
# Navigate to the Devilbox git directory
host> cd /path/to/devilbox
# Nagivate to startup directory for PHP 7.2 and create the script
host> cd cfg/php-startup-7.2/
host> vi my-sphinx.sh
.. code-block:: bash
:caption: cfg/php-startup-7.2/my-sphinx.sh
#!/usr/bin/env bash
# Install required Python modules as root user
pip install sphinx sphinx-autobuild
# Autostart Sphinx by devilbox user on Port 4000 and sent it to backgroun with '&'
sh -c "cd /shared/httpd/my-sphinx; sphinx-autobuild . _build/html -p 4000 -H 0.0.0.0" -l devilbox &
.. 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`
7. 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-node.loc
.. seealso::
* :ref:`howto_add_project_hosts_entry_on_mac`
* :ref:`howto_add_project_hosts_entry_on_win`
* :ref:`setup_auto_dns`
8. Restart the Devilbox
-----------------------
Now for those changes to take affect, you will have to restart the Devilbox.
.. code-block:: bash
host> cd /path/to/devilbox
# Stop the Devilbox
host> docker-compose down
host> docker-compose rm -f
# Start the Devilbox
host> docker-compose up -d php httpd bind
9. Open your browser
--------------------
All set now, you can visit http://my-sphinx.loc or https://my-sphinx.loc in your browser.
The Sphinx application has been started up automatically and the reverse proxy will direct all
requests to it.
.. seealso:: :ref:`setup_valid_https`

2
docs/getting-started/directory-overview.rst
View File

@ -35,6 +35,8 @@ You can verifiy that the path is actually ``./data/www/`` by checking your ``.en
HOST_PATH_HTTPD_DATADIR=./data/www
.. _getting_started_directory_overview_project_directory:
Project directory
=================

27
docs/index.rst
View File

@ -70,7 +70,6 @@ host is ready to be served with your custom domain.
:maxdepth: 2
:numbered:
advanced/custom-startup-commands
advanced/customize-php-globally
advanced/customize-webserver-globally
advanced/connect-to-host-os
@ -81,6 +80,15 @@ host is ready to be served with your custom domain.
advanced/overwrite-existing-docker-image
.. toctree::
:caption: Autostart commands
:maxdepth: 2
autostart/custom-scripts-per-php-version
autostart/custom-scripts-globally
autostart/autostarting-nodejs-apps
.. toctree::
:caption: vhost-gen
:maxdepth: 2
@ -88,8 +96,18 @@ host is ready to be served with your custom domain.
vhost-gen/virtual-host-templates
vhost-gen/customize-all-virtual-hosts-globally
vhost-gen/customize-specific-virtual-host
vhost-gen/virtual-host-vs-reverse-proxy
vhost-gen/example-add-subdomains
.. toctree::
:caption: reverse-proxy
:maxdepth: 2
reverse-proxy/reverse-proxy-with-https
reverse-proxy/reverse-proxy-for-custom-docker
.. toctree::
:caption: Enable custom container
:maxdepth: 2
@ -164,6 +182,13 @@ host is ready to be served with your custom domain.
examples/setup-zend
examples/setup-other-frameworks
.. toctree::
:maxdepth: 2
:caption: Examples - reverse proxy
examples/setup-reverse-proxy-nodejs
examples/setup-reverse-proxy-sphinx-docs
.. toctree::
:caption: Readings

2
docs/readings/available-tools.rst
View File

@ -74,6 +74,8 @@ The PHP container is your workhorse and these are your tools:
+----------------------+---------------------------------------+
| ``photon`` | |ext_lnk_tool_photon| |
+----------------------+---------------------------------------+
| ``pm2`` | |ext_lnk_tool_pm2| |
+----------------------+---------------------------------------+
| ``redis*`` | Various Redis client tools |
+----------------------+---------------------------------------+
| ``sass`` | |ext_lnk_tool_sass| |

263
docs/reverse-proxy/reverse-proxy-for-custom-docker.rst Normal file
View File

@ -0,0 +1,263 @@
.. include:: /_includes/all.rst
.. _reverse_proxy_with_custom_docker:
*******************************
Reverse Proxy for custom Docker
*******************************
Imagine you have added a custom service container to the Devilbox which has a project that
is available via http on a very specific port in that container.
You do not want to expose this port to the host system, but rather want to make it available
via the bundled web server and also be able to see it on the Devilbox intranet vhost section.
Additionally you want the project to make use of the same DNS naming scheme and also have HTTPS
for it.
You can easily achieve this by setting up a reverse proxy for it.
.. seealso:: :ref:`add_your_own_docker_image`
**Table of Contents**
.. contents:: :local:
Walkthrough
===========
Assumption
----------
Let's imagine you have added a custom Python Docker image to the Devilbox which starts up a Django
application listening on port ``3000``.
* :ref:`env_TLD_SUFFIX`: ``loc``
* Desired DNS name: ``my-pthon.loc``
* :ref:`env_httpd_datadir` on the host: ``./data/www``
* :ref:`env_httpd_template_dir`: ``.devilbox``
* Listening port: ``3000``
* Listening host: ``python`` (hostname of the Python container)
Create *virtual* directory
--------------------------
In order to create a reverse proxy for that custom container, you must add a *virtual* project
directory without any data in it. This directory is purely for the purpose of determining the
DNS name and for having the vhost-gen configuration in.
Navigate to the :ref:`env_httpd_datadir` directory and create your project
.. code-block:: bash
host> cd /path/to/devilbox
host> cd /path/to/devilbox/data/www
# Create the project directory
host> mkdir my-python
# Create the htdocs directory (to have a valid project for the Intranet page)
host> mkdir my-python/htdocs
# Create the vhost-gen directory (to be apply to apply custom templates)
host> mkdir my-python/.devilbox
This part is now sufficient to have the project visible on the Devilbox intranet.
Copy vhost-gen templates
------------------------
The reverse vhost-gen templates are available in ``cfg/vhost-gen``:
.. code-block:: bash
:emphasize-lines: 4,6,8
host> tree -L 1 cfg/vhost-gen/
cfg/vhost-gen/
├── apache22.yml-example-rproxy
├── apache22.yml-example-vhost
├── apache24.yml-example-rproxy
├── apache24.yml-example-vhost
├── nginx.yml-example-rproxy
├── nginx.yml-example-vhost
└── README.md
0 directories, 7 files
For this example we will copy all ``*-example-rproxy`` files into ``/shared/httpd/my-python/.devilbox``
to ensure this will work with all web servers.
.. code-block:: bash
host> cd /path/to/devilbox
host> cp cfg/vhost-gen/apache22.yml-example-rproxy data/www/my-python/.devilbox/apache22.yml
host> cp cfg/vhost-gen/apache24.yml-example-rproxy data/www/my-python/.devilbox/apache24.yml
host> cp cfg/vhost-gen/nginx.yml-example-rproxy data/www/my-python/.devilbox/nginx.yml
Adjust port
-----------
By default, all vhost-gen templates will forward requests to port ``8000`` into the PHP container.
Our current example however uses port ``3000`` and host ``python``, so we must change that accordingly for all three
templates.
Adjust Apache 2.2 template
^^^^^^^^^^^^^^^^^^^^^^^^^^
Open the ``apache22.yml`` vhost-gen template in your project:
.. code-block:: bash
host> cd /path/to/devilbox
host> vi data/www/my-python/.devilbox/apache22.yml
Find the two lines with ``ProxyPass`` and ``ProxyPassReverse`` and change the port from ``8000``
to ``3000`` and host ``php`` to ``python``:
.. code-block:: yaml
:caption: data/www/my-python/.devilbox/apache22.yml
:emphasize-lines: 16,17
# ... more lines above ... #
###
### Basic vHost skeleton
###
vhost: |
<VirtualHost __DEFAULT_VHOST__:__PORT__>
ServerName __VHOST_NAME__
CustomLog "__ACCESS_LOG__" combined
ErrorLog "__ERROR_LOG__"
# Reverse Proxy definition (Ensure to adjust the port, currently '8000')
ProxyRequests On
ProxyPreserveHost On
ProxyPass / http://python:3000/
ProxyPassReverse / http://python:3000/
# ... more lines below ... #
Adjust Apache 2.4 template
^^^^^^^^^^^^^^^^^^^^^^^^^^
Open the ``apache24.yml`` vhost-gen template in your project:
.. code-block:: bash
host> cd /path/to/devilbox
host> vi data/www/my-python/.devilbox/apache24.yml
Find the two lines with ``ProxyPass`` and ``ProxyPassReverse`` and change the port from ``8000``
to ``3000`` and host ``php`` to ``python``:
.. code-block:: yaml
:caption: data/www/my-python/.devilbox/apache24.yml
:emphasize-lines: 16,17
# ... more lines above ... #
###
### Basic vHost skeleton
###
vhost: |
<VirtualHost __DEFAULT_VHOST__:__PORT__>
ServerName __VHOST_NAME__
CustomLog "__ACCESS_LOG__" combined
ErrorLog "__ERROR_LOG__"
# Reverse Proxy definition (Ensure to adjust the port, currently '8000')
ProxyRequests On
ProxyPreserveHost On
ProxyPass / http://python:3000/
ProxyPassReverse / http://python:3000/
# ... more lines below ... #
Adjust Nginx template
^^^^^^^^^^^^^^^^^^^^^
Open the ``nginx.yml`` vhost-gen template in your project:
.. code-block:: bash
host> cd /path/to/devilbox
host> vi data/www/my-python/.devilbox/nginx.yml
Find the line with ``proxy_pass`` and change the port from ``8000``
to ``3000`` and host ``php`` to ``python``:
.. code-block:: yaml
:caption: data/www/my-python/.devilbox/nginx.yml
:emphasize-lines: 18
# ... more lines above ... #
###
### Basic vHost skeleton
###
vhost: |
server {
listen __PORT____DEFAULT_VHOST__;
server_name __VHOST_NAME__;
access_log "__ACCESS_LOG__" combined;
error_log "__ERROR_LOG__" warn;
# Reverse Proxy definition (Ensure to adjust the port, currently '8000')
location / {
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_pass http://python:3000;
}
# ... more lines below ... #
Restart the Devilbox
--------------------
Now for the changes to take affect, simply restart the Devilbox (or start if not yet running):
.. code-block:: bash
host> cd /path/to/devilbox
# Stop the Devilbox
host> docker-compose stop
host> docker-compose rm -f
# Start the Devilbox (Your Python container and the PHP and HTTPD container only)
host> docker-compose up -d php httpd bind python
Visit your project
------------------
That's it, your service application will now be available via:
* http://my-python.loc
It will also be available on HTTPS. This is by default and automatically:
* https://my-python.loc
.. seealso:: :ref:`setup_valid_https`
And is even shown as a project in the Devilbox intranet:
* http://localhost/vhosts.php
* https://localhost/vhosts.php

250
docs/reverse-proxy/reverse-proxy-with-https.rst Normal file
View File

@ -0,0 +1,250 @@
.. include:: /_includes/all.rst
.. _reverse_proxy_with_https:
************************
Reverse Proxy with HTTPS
************************
Imagine you have started an application within the PHP container that creates a listening port
(e.g.: NodeJS). This will now only listen on the PHP container and you would have to adjust
the docker-compose.yml definition in order to have that port available outside to your host OS.
Alternatively, there is a simple way to reverse proxy it to the already running web server and even
make use of the available HTTPS feature.
.. seealso::
**Read more about how to autostart applications:**
* :ref:`custom_scripts_per_php_version` (individually for different PHP versions)
* :ref:`custom_scripts_globally` (equal for all PHP versions)
**Table of Contents**
.. contents:: :local:
Walkthrough
===========
Assumption
----------
Let's imagine you have started an application in the PHP container with the following settings:
* :ref:`env_TLD_SUFFIX`: ``loc``
* :ref:`getting_started_directory_overview_project_directory` inside PHP container: ``/shared/httpd/my-app``
* :ref:`env_httpd_datadir` on the host: ``./data/www``
* :ref:`env_httpd_template_dir`: ``.devilbox``
* Listening port: ``8081``
* Listening host: ``php`` (any of the PHP container)
* Resulting vhost name: ``my-app.loc``
Copy vhost-gen templates
------------------------
The reverse vhost-gen templates are available in ``cfg/vhost-gen``:
.. code-block:: bash
:emphasize-lines: 4,6,8
host> tree -L 1 cfg/vhost-gen/
cfg/vhost-gen/
├── apache22.yml-example-rproxy
├── apache22.yml-example-vhost
├── apache24.yml-example-rproxy
├── apache24.yml-example-vhost
├── nginx.yml-example-rproxy
├── nginx.yml-example-vhost
└── README.md
0 directories, 7 files
For this example we will copy all ``*-example-rproxy`` files into ``/shared/httpd/my-app/.devilbox``
to ensure this will work with all web servers.
.. code-block:: bash
host> cd /path/to/devilbox
host> cp cfg/vhost-gen/apache22.yml-example-rproxy data/www/my-app/.devilbox/apache22.yml
host> cp cfg/vhost-gen/apache24.yml-example-rproxy data/www/my-app/.devilbox/apache24.yml
host> cp cfg/vhost-gen/nginx.yml-example-rproxy data/www/my-app/.devilbox/nginx.yml
Adjust port
-----------
By default, all vhost-gen templates will forward requests to port ``8000`` into the PHP container.
Our current example however uses port ``8081``, so we must change that accordingly for all three
templates.
Adjust Apache 2.2 template
^^^^^^^^^^^^^^^^^^^^^^^^^^
Open the ``apache22.yml`` vhost-gen template in your project:
.. code-block:: bash
host> cd /path/to/devilbox
host> vi data/www/my-app/.devilbox/apache22.yml
Find the two lines with ``ProxyPass`` and ``ProxyPassReverse`` and change the port from ``8000``
to ``8081``
.. code-block:: yaml
:caption: data/www/my-app/.devilbox/apache22.yml
:emphasize-lines: 16,17
# ... more lines above ... #
###
### Basic vHost skeleton
###
vhost: |
<VirtualHost __DEFAULT_VHOST__:__PORT__>
ServerName __VHOST_NAME__
CustomLog "__ACCESS_LOG__" combined
ErrorLog "__ERROR_LOG__"
# Reverse Proxy definition (Ensure to adjust the port, currently '8000')
ProxyRequests On
ProxyPreserveHost On
ProxyPass / http://php:8081/
ProxyPassReverse / http://php:8081/
# ... more lines below ... #
Adjust Apache 2.4 template
^^^^^^^^^^^^^^^^^^^^^^^^^^
Open the ``apache24.yml`` vhost-gen template in your project:
.. code-block:: bash
host> cd /path/to/devilbox
host> vi data/www/my-app/.devilbox/apache24.yml
Find the two lines with ``ProxyPass`` and ``ProxyPassReverse`` and change the port from ``8000``
to ``8081``
.. code-block:: yaml
:caption: data/www/my-app/.devilbox/apache24.yml
:emphasize-lines: 16,17
# ... more lines above ... #
###
### Basic vHost skeleton
###
vhost: |
<VirtualHost __DEFAULT_VHOST__:__PORT__>
ServerName __VHOST_NAME__
CustomLog "__ACCESS_LOG__" combined
ErrorLog "__ERROR_LOG__"
# Reverse Proxy definition (Ensure to adjust the port, currently '8000')
ProxyRequests On
ProxyPreserveHost On
ProxyPass / http://php:8081/
ProxyPassReverse / http://php:8081/
# ... more lines below ... #
Adjust Nginx template
^^^^^^^^^^^^^^^^^^^^^
Open the ``nginx.yml`` vhost-gen template in your project:
.. code-block:: bash
host> cd /path/to/devilbox
host> vi data/www/my-app/.devilbox/nginx.yml
Find the lines with ``proxy_pass`` and change the port from ``8000`` to ``8081``
.. code-block:: yaml
:caption: data/www/my-app/.devilbox/nginx.yml
:emphasize-lines: 18
# ... more lines above ... #
###
### Basic vHost skeleton
###
vhost: |
server {
listen __PORT____DEFAULT_VHOST__;
server_name __VHOST_NAME__;
access_log "__ACCESS_LOG__" combined;
error_log "__ERROR_LOG__" warn;
# Reverse Proxy definition (Ensure to adjust the port, currently '8000')
location / {
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_pass http://php:8081;
}
# ... more lines below ... #
Restart the Devilbox
--------------------
Now for the changes to take affect, simply restart the Devilbox (or start if not yet running):
.. code-block:: bash
host> cd /path/to/devilbox
# Stop the Devilbox
host> docker-compose stop
host> docker-compose rm -f
# Start the Devilbox (PHP and HTTPD container only)
host> docker-compose up -d php httpd bind
Start your application
----------------------
Enter the PHP container and start your application which creates the listening port in port ``8081``.
.. seealso::
This can also be automated to happen automatically during ``docker-compose up`` via:
* :ref:`custom_scripts_per_php_version` (individually for different PHP versions)
* :ref:`custom_scripts_globally` (equal for all PHP versions)
* Example: :ref:`autostarting_nodejs_apps`
Visit your project
------------------
That's it, your service application will now be available via:
* http://my-app.loc
It will also be available on HTTPS. This is by default and automatically:
* https://my-app.loc
.. seealso:: :ref:`setup_valid_https`
And is even shown as a project in the Devilbox intranet:
* http://localhost/vhosts.php
* https://localhost/vhosts.php

17
docs/support/blogs-videos-and-use-cases.rst
View File

@ -6,6 +6,11 @@
Blogs, Videos and Use-cases
***************************
**Table of Contents**
.. contents:: :local:
Official videos
===============
@ -16,6 +21,18 @@ even if the intranet UI has changed a bit.
.. include:: /_includes/figures/blogs/youtube-email-catch-all.rst
Conferences
===========
DrupalCamp Ghent 2018
---------------------
Simple local development with Devilbox:
* |ext_lnk_blog_drupalcamp_ghent_2018_presentation|
* |ext_lnk_blog_drupalcamp_ghent_2018_slides|
Blog posts
==========

58
docs/vhost-gen/virtual-host-templates.rst
View File

@ -33,7 +33,18 @@ By default, vhost-gen templates are located within the Devilbox root directory u
The templates file names are suffixed with ``-example-<type>`` and are absolutely identical to what is
shipped inside each Devilbox web server Docker container.
.. note::
Also note that nginx stable and nginx mainline share the same template as their configuration
syntax is identical.
Normal virtual host
^^^^^^^^^^^^^^^^^^^
All template files ending by ``-example-vhost`` can be used to customize a normal file serving
virtual host.
.. code-block:: bash
:emphasize-lines: 5,7,9
host> tree -L 1 cfg/vhost-gen/
@ -48,9 +59,27 @@ shipped inside each Devilbox web server Docker container.
0 directories, 7 files
.. note::
Also note that nginx stable and nginx mainline share the same template as their configuration
syntax is identical.
Reverse proxy
^^^^^^^^^^^^^
All template files ending by ``-example-rproxy`` can be used to create a reverse proxy for your
project.
.. code-block:: bash
:emphasize-lines: 4,6,8
host> tree -L 1 cfg/vhost-gen/
cfg/vhost-gen/
├── apache22.yml-example-rproxy
├── apache22.yml-example-vhost
├── apache24.yml-example-rproxy
├── apache24.yml-example-vhost
├── nginx.yml-example-rproxy
├── nginx.yml-example-vhost
└── README.md
0 directories, 7 files
Template sections
-----------------
@ -81,7 +110,7 @@ Apache 2.2 template
-------------------
.. literalinclude:: ../../cfg/vhost-gen/apache22.yml-example-vhost
:caption: apache22.yml
:caption: apache22.yml-example-vhost
:language: yaml
@ -89,7 +118,7 @@ Apache 2.4 template
-------------------
.. literalinclude:: ../../cfg/vhost-gen/apache24.yml-example-vhost
:caption: apache24.yml
:caption: apache24.yml-example-vhost
:language: yaml
@ -97,7 +126,7 @@ Nginx template
--------------
.. literalinclude:: ../../cfg/vhost-gen/nginx.yml-example-vhost
:caption: nginx.yml
:caption: nginx.yml-example-vhost
:language: yaml
@ -107,25 +136,36 @@ Reverse proxy Templates
These templates can be used to change a normal vhost into a reverse proxy project. This might be
useful if you use NodeJs applications for example.
.. important:: Do not apply those templates globally. They are intended to be used on a per project base.
.. note::
In order to use the Reverse Proxy templates you will only need to adjust the listening port,
everything else will work as already defined. So you simply need to copy those files into
your project directory. Lines that need to be changed are marked below. The currently set default
listening port is ``8000``.
Apache 2.2 template
-------------------
.. literalinclude:: ../../cfg/vhost-gen/apache22.yml-example-rproxy
:caption: apache22.yml
:caption: apache22.yml-example-rproxy
:language: yaml
:emphasize-lines: 51,52
Apache 2.4 template
-------------------
.. literalinclude:: ../../cfg/vhost-gen/apache24.yml-example-rproxy
:caption: apache24.yml
:caption: apache24.yml-example-rproxy
:language: yaml
:emphasize-lines: 51,52
Nginx template
--------------
.. literalinclude:: ../../cfg/vhost-gen/nginx.yml-example-rproxy
:caption: nginx.yml
:caption: nginx.yml-example-rproxy
:language: yaml
:emphasize-lines: 53

61
docs/vhost-gen/virtual-host-vs-reverse-proxy.rst Normal file
View File

@ -0,0 +1,61 @@
.. _vhost_gen_virtual_host_vs_reverse_proxy:
*****************************
Virtual host vs Reverse Proxy
*****************************
.. note::
Ensure you have read :ref:`vhost_gen_virtual_host_templates`
**Table of Contents**
.. contents:: :local:
Motivation
==========
By default, all virtual hosts will simply serve files located in your document root directory within
your project directory. Sometimes however your *project* is already its own server that will serve
requests through a listening network port. (e.g. a running NodeJS application).
This listening port will however only be available inside the PHP container (or any other container)
you have added to the Devilbox and the webserver is not aware of this.
For this kind of project you will want to create a reverse proxy which simply forwards the requests
incoming to the webserver to your application (either to the PHP container to a specific port or
to any other container you have attached).
Benefits
========
By using the already available web server to reverse proxy requests to your service you will be
able to have all the current features for you application such as:
* Have it displayed in the intranet page
* Have standardized domain names
* Have valid HTTPS
Creating a reverse proxy
========================
Creating a reverse proxy is as simply as copying the ``vhost-gen`` templates to your project
directory.
In order to make your life simple there are a few generic docs that get you started and let you
know more about the theory behind it:
.. seealso::
* :ref:`reverse_proxy_with_https`
* :ref:`reverse_proxy_with_custom_docker`
If this is too generic you can also have a look at two specific examples to setup fully automated
Reverse Proxies including autostarting your application on ``docker-compose up``.
.. seealso::
* :ref:`example_setup_reverse_proxy_nodejs`
* :ref:`example_setup_reverse_proxy_sphinx_docs`