Documentation restructuring

This commit is contained in:
cytopia 2018-07-03 15:47:58 +02:00
parent 0121371048
commit acab8b346e
No known key found for this signature in database
GPG Key ID: 6D56EDB8695128A2
169 changed files with 2211 additions and 865 deletions

View File

@ -53,4 +53,4 @@ build:
sphinx-build -a -E -n -j auto -q -W . _build/html
autobuild:
sphinx-autobuild -E -n -j auto . _build/html
sphinx-autobuild . _build/html

View File

@ -26,17 +26,15 @@ sudo pip install sphinx_rtd_theme
#### How to build and error-check
```
cd docs/
sphinx-build -a -E -j auto -n -q . _build/html/
make build
```
#### How to build continuously
```
cd docs/
sphinx-autobuild . _build/html
make autobuild
```
#### How to view
Open you browser on http://127.0.0.1:8000
When using `make autobuild` your documentation is served at: http://127.0.0.1:8000

View File

Before

Width:  |  Height:  |  Size: 56 KiB

After

Width:  |  Height:  |  Size: 56 KiB

View File

@ -0,0 +1,2 @@
.. figure:: /_includes/figures/blogs/youtube-email-catch-all.png
:target: https://www.youtube.com/watch?v=e-U-C5WhxGY

View File

Before

Width:  |  Height:  |  Size: 56 KiB

After

Width:  |  Height:  |  Size: 56 KiB

View File

@ -0,0 +1,2 @@
.. figure:: /_includes/figures/blogs/youtube-setup-and-workflow.png
:target: https://www.youtube.com/watch?v=reyZMyt2Zzo

View File

Before

Width:  |  Height:  |  Size: 120 KiB

After

Width:  |  Height:  |  Size: 120 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/devilbox/devilbox-intranet-dash-all.png
Devilbox intranet: index dash view for all started container

View File

Before

Width:  |  Height:  |  Size: 114 KiB

After

Width:  |  Height:  |  Size: 114 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/devilbox/devilbox-intranet-dash-selective.png
Devilbox intranet: index dash view for some started container

View File

Before

Width:  |  Height:  |  Size: 135 KiB

After

Width:  |  Height:  |  Size: 135 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/devilbox/devilbox-intranet-emails.png
Devilbox intranet: email catch-all overview

View File

Before

Width:  |  Height:  |  Size: 355 KiB

After

Width:  |  Height:  |  Size: 355 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/devilbox/devilbox-intranet-index.png
Devilbox intranet: homepage

View File

Before

Width:  |  Height:  |  Size: 72 KiB

After

Width:  |  Height:  |  Size: 72 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/devilbox/devilbox-intranet-mysql-databases.png
Devilbox intranet: MySQL database overview

View File

Before

Width:  |  Height:  |  Size: 117 KiB

After

Width:  |  Height:  |  Size: 117 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/devilbox/devilbox-intranet-mysql-info.png
Devilbox intranet: MySQL info overview

View File

Before

Width:  |  Height:  |  Size: 300 KiB

After

Width:  |  Height:  |  Size: 300 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/devilbox/devilbox-intranet-php-info.png
Devilbox intranet: php info

View File

Before

Width:  |  Height:  |  Size: 56 KiB

After

Width:  |  Height:  |  Size: 56 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/devilbox/devilbox-intranet-vhosts-empty.png
Devilbox intranet: no projects created

View File

Before

Width:  |  Height:  |  Size: 50 KiB

After

Width:  |  Height:  |  Size: 50 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/devilbox/devilbox-intranet-vhosts-missing-dns.png
Devilbox intranet: misssing dns record

View File

Before

Width:  |  Height:  |  Size: 48 KiB

After

Width:  |  Height:  |  Size: 48 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/devilbox/devilbox-intranet-vhosts-missing-htdocs.png
Devilbox intranet: misssing ``htdocs`` directory

View File

Before

Width:  |  Height:  |  Size: 41 KiB

After

Width:  |  Height:  |  Size: 41 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/devilbox/devilbox-intranet-vhosts-working.png
Devilbox intranet: vhost setup successfully

View File

Before

Width:  |  Height:  |  Size: 141 KiB

After

Width:  |  Height:  |  Size: 141 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/devilbox/devilbox-intranet-vhosts.png
Devilbox intranet: available virtual hosts

View File

Before

Width:  |  Height:  |  Size: 5.1 KiB

After

Width:  |  Height:  |  Size: 5.1 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/devilbox/devilbox-project-hello-world.png
Devilbox project: hello world on ``index.php``

View File

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 12 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/devilbox/devilbox-project-missing-index.png
Devilbox project: misssing ``index.php`` or ``index.html``

View File

Before

Width:  |  Height:  |  Size: 93 KiB

After

Width:  |  Height:  |  Size: 93 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/dns/mac-network-settings.png
MacOS: network settings

View File

Before

Width:  |  Height:  |  Size: 55 KiB

After

Width:  |  Height:  |  Size: 55 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/dns/win-ethernet-properties.png
Windows: ethernet properties

View File

Before

Width:  |  Height:  |  Size: 50 KiB

After

Width:  |  Height:  |  Size: 50 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/dns/win-internet-protocol-properties.png
Windows: internet protocol properties

View File

Before

Width:  |  Height:  |  Size: 62 KiB

After

Width:  |  Height:  |  Size: 62 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/dns/win-network-connections.png
Windows: network connections

View File

Before

Width:  |  Height:  |  Size: 96 KiB

After

Width:  |  Height:  |  Size: 96 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/https/chrome-advanced-settings.png
Click on ``Manage certificates``

View File

Before

Width:  |  Height:  |  Size: 20 KiB

After

Width:  |  Height:  |  Size: 20 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/https/chrome-manage-certificates.png
Click on ``IMPORT`` in the AUTHORITIES tab

View File

Before

Width:  |  Height:  |  Size: 39 KiB

After

Width:  |  Height:  |  Size: 39 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/https/chrome-set-trust.png
Tell Chrome to trust this CA

View File

Before

Width:  |  Height:  |  Size: 28 KiB

After

Width:  |  Height:  |  Size: 28 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/https/chrome-settings.png
Click on ``Advanced``

View File

Before

Width:  |  Height:  |  Size: 51 KiB

After

Width:  |  Height:  |  Size: 51 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/https/file-manager-import-ca.png
**Note**: your file manager might look different

View File

Before

Width:  |  Height:  |  Size: 76 KiB

After

Width:  |  Height:  |  Size: 76 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/https/firefox-certificate-manager.png
Click on ``Import`` in the Authorities tab

View File

Before

Width:  |  Height:  |  Size: 58 KiB

After

Width:  |  Height:  |  Size: 58 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/https/firefox-preferences.png
Click on ``Privacy & Security`` in the left menu bar

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/https/firefox-privacy-and-security.png
Click on ``View Certificates``

View File

Before

Width:  |  Height:  |  Size: 59 KiB

After

Width:  |  Height:  |  Size: 59 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/https/firefox-set-trust.png
Tell Firefox to trust this CA

View File

Before

Width:  |  Height:  |  Size: 4.9 KiB

After

Width:  |  Height:  |  Size: 4.9 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/https/https-ssl-address-bar.png
Valid HTTPS will automatically be available for all projects

Binary file not shown.

After

Width:  |  Height:  |  Size: 119 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/terminal/docker-toolbox-terminal-mac-quickstart-launchpad.png
Copyright docs.docker.com

Binary file not shown.

After

Width:  |  Height:  |  Size: 21 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/terminal/docker-toolbox-terminal-win-quickstart-shortcut.png
Copyright docs.docker.com

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.6 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/terminal/docker-toolbox-terminal-win-quickstart-terminal.png
Copyright docs.docker.com

View File

Before

Width:  |  Height:  |  Size: 118 KiB

After

Width:  |  Height:  |  Size: 118 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/xdebug/phpstorm-dbgp-proxy.png
PHPStorm settings: DBGp Proxy

View File

Before

Width:  |  Height:  |  Size: 199 KiB

After

Width:  |  Height:  |  Size: 199 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/xdebug/phpstorm-path-mapping.png
PHPStorm settings: path mapping

View File

Before

Width:  |  Height:  |  Size: 189 KiB

After

Width:  |  Height:  |  Size: 189 KiB

View File

@ -0,0 +1,3 @@
.. figure:: /_includes/figures/xdebug/phpstorm-settings.png
PHPStorm settings: Xdebug

View File

@ -0,0 +1,5 @@
.. |img_logo_lin| image:: https://raw.githubusercontent.com/cytopia/icons/master/64x64/linux.png
.. |img_logo_mac| image:: https://raw.githubusercontent.com/cytopia/icons/master/64x64/mac.png
.. |img_logo_win| image:: https://raw.githubusercontent.com/cytopia/icons/master/64x64/windows.png
.. |img_banner| image:: /img/banner.png

View File

@ -0,0 +1,157 @@
..
============================================================
Docker
============================================================
.. |ext_lnk_install_docker| raw:: html
<a target="_blank" href="https://docs.docker.com/install/">
Install Docker <img src="/_static/img/icons/ext-link.svg" />
</a>
.. |ext_link_docker_machine| raw:: html
<a target="_blank" href="https://docs.docker.com/machine/overview/">
Docker Machine <img src="/_static/img/icons/ext-link.svg" />
</a>
..
============================================================
Docker for Linux
============================================================
.. |ext_lnk_install_docker_centos| raw:: html
<a target="_blank" href="https://docs.docker.com/install/linux/docker-ce/centos/">
Get Docker CE for CentOS <img src="/_static/img/icons/ext-link.svg" />
</a>
.. |ext_lnk_install_docker_debian| raw:: html
<a target="_blank" href="https://docs.docker.com/install/linux/docker-ce/debian/">
Get Docker CE for Debian <img src="/_static/img/icons/ext-link.svg" />
</a>
.. |ext_lnk_install_docker_fedora| raw:: html
<a target="_blank" href="https://docs.docker.com/install/linux/docker-ce/fedora/">
Get Docker CE for Fedora <img src="/_static/img/icons/ext-link.svg" />
</a>
.. |ext_lnk_install_docker_ubuntu| raw:: html
<a target="_blank" href="https://docs.docker.com/install/linux/docker-ce/ubuntu/">
Get Docker CE for Ubuntu <img src="/_static/img/icons/ext-link.svg" />
</a>
.. |ext_lnk_install_docker_linux_post_steps| raw:: html
<a target="_blank" href="https://docs.docker.com/install/linux/linux-postinstall/">
Post-installation steps for Linux <img src="/_static/img/icons/ext-link.svg" />
</a>
..
============================================================
Docker for Mac
============================================================
.. |ext_lnk_install_docker_mac| raw:: html
<a target="_blank" href="https://docs.docker.com/docker-for-mac/install/">
Install Docker for Mac <img src="/_static/img/icons/ext-link.svg" />
</a>
.. |ext_lnk_install_docker_mac_get_started| raw:: html
<a target="_blank" href="https://docs.docker.com/docker-for-mac/">
Get started with Docker for Mac <img src="/_static/img/icons/ext-link.svg" />
</a>
.. |ext_lnk_install_docker_toolbox_mac| raw:: html
<a target="_blank" href="https://docs.docker.com/toolbox/toolbox_install_mac/">
Install Docker Toolbox on macOS <img src="/_static/img/icons/ext-link.svg" />
</a>
.. |ext_lnk_install_docker_toolbox_mac_native_vs_toolbox| raw:: html
<a target="_blank" href="https://docs.docker.com/docker-for-mac/docker-toolbox/">
Docker for Mac vs. Docker Toolbox <img src="/_static/img/icons/ext-link.svg" />
</a>
.. |ext_lnk_install_docker_toolbox_mac_shared_directory| raw:: html
<a target="_blank" href="https://docs.docker.com/toolbox/toolbox_install_mac/#optional-add-shared-directories">
Docker Toolbox on Mac: add shared directories <img src="/_static/img/icons/ext-link.svg" />
</a>
..
============================================================
Docker for Windows
============================================================
.. |ext_lnk_install_docker_win| raw:: html
<a target="_blank" href="https://docs.docker.com/docker-for-windows/install/">
Install Docker for Windows <img src="/_static/img/icons/ext-link.svg" />
</a>
.. |ext_lnk_install_docker_win_get_started| raw:: html
<a target="_blank" href="https://docs.docker.com/docker-for-windows/">
Get started with Docker for Windows <img src="/_static/img/icons/ext-link.svg" />
</a>
.. |ext_lnk_install_docker_toolbox_win| raw:: html
<a target="_blank" href="https://docs.docker.com/toolbox/toolbox_install_windows/">
Install Docker Toolbox on Windows <img src="/_static/img/icons/ext-link.svg" />
</a>
.. |ext_lnk_install_docker_toolbox_win_shared_directory| raw:: html
<a target="_blank" href="https://docs.docker.com/toolbox/toolbox_install_windows/#optional-add-shared-directories">
Docker Toolbox on Windows: add shared directories <img src="/_static/img/icons/ext-link.svg" />
</a>
..
============================================================
Docker Compose
============================================================
.. |ext_lnk_install_docker_compose| raw:: html
<a target="_blank" href="https://docs.docker.com/compose/install/">
Install Docker Compose <img src="/_static/img/icons/ext-link.svg" />
</a>
.. |ext_lnk_docker_cmpose_cmd_reference| raw:: html
<a target="_blank" href="https://docs.docker.com/compose/reference/">
Compose command-line reference <img src="/_static/img/icons/ext-link.svg" />
</a>
.. |ext_lnk_docker_cmpose_env_file| raw:: html
<a target="_blank" href="https://docs.docker.com/compose/env-file/">
Declare default environment variables in file <img src="/_static/img/icons/ext-link.svg" />
</a>
..
============================================================
Misc
============================================================
.. -------------------- uid --------------------
.. |ext_lnk_uid| raw:: html
<a target="_blank" href="https://en.wikipedia.org/wiki/User_identifier">
Wikipedia: uid <img src="/_static/img/icons/ext-link.svg" />
</a>

View File

@ -1,3 +1,7 @@
/************************************************************
* MENU
***********************************************************/
/* overwrite logo dimensions */
.wy-side-nav-search>a img.logo,
.wy-side-nav-search .wy-dropdown>a img.logo {
@ -9,6 +13,21 @@
background-color: #343131;
}
/* sidebar category headlines */
.wy-menu-vertical header, .wy-menu-vertical p.caption {
margin-top: 25px;
margin-bottom: 15px;
padding: 0 1.518em;
padding-top:10px;
border-top: 1px solid #9b9b9b;
font-size: 100%;
}
/************************************************************
* Code blocks
***********************************************************/
/* Disable annoying scrollbar in code-blocks */
.codeblock,
pre.literal-block,

49
docs/_static/devilbox.css vendored Normal file
View File

@ -0,0 +1,49 @@
/************************************************************
* MENU
***********************************************************/
/* overwrite logo dimensions */
.wy-side-nav-search>a img.logo,
.wy-side-nav-search .wy-dropdown>a img.logo {
width: 128px;
}
/* overwrite top-left serach div */
.wy-side-nav-search {
background-color: #343131;
}
/* sidebar category headlines */
.wy-menu-vertical header, .wy-menu-vertical p.caption {
margin-top: 25px;
margin-bottom: 15px;
padding: 0 1.518em;
padding-top:10px;
border-top: 1px solid #9b9b9b;
/*font-size: 14px;*/
}
/************************************************************
* Code blocks
***********************************************************/
/* Disable annoying scrollbar in code-blocks */
.codeblock,
pre.literal-block,
.rst-content .literal-block,
.rst-content pre.literal-block,
.rst-content div[class^='highlight'],
div[class^='highlight'] {
overflow: hidden !important;
}
/* bg color for code windows */
.highlight {
background-color: #ffffff !important;
}
/*
div.rtd-pro.rtd-pro-footer {
display: none;
}
*/

Binary file not shown.

Before

Width:  |  Height:  |  Size: 154 KiB

1
docs/_static/img/icons/ext-link.svg vendored Normal file
View File

@ -0,0 +1 @@
<svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' preserveAspectRatio='xMidYMid' width='11' height='11' viewBox='0 0 11 11'> <path fill='%23008eff' fill-rule='evenodd' d='M10.500,6.000 C10.224,6.000 10.000,5.776 10.000,5.500 L10.000,1.707 L3.354,8.353 L2.646,7.646 L9.293,1.000 L5.500,1.000 C5.224,1.000 5.000,0.776 5.000,0.499 C5.000,0.223 5.224,-0.000 5.500,-0.000 L10.500,-0.000 C10.776,-0.000 11.000,0.223 11.000,0.499 L11.000,5.500 C11.000,5.776 10.776,6.000 10.500,6.000 ZM10.000,1.000 L10.000,1.000 L10.000,1.000 L10.000,1.000 ZM1.000,9.999 L8.000,9.999 L8.000,9.000 L8.000,8.000 L8.000,7.000 L9.000,7.000 L9.000,8.000 L9.000,9.000 L9.000,9.999 L9.000,11.000 L8.000,11.000 L-0.000,11.000 L-0.000,9.999 L-0.000,3.999 L-0.000,2.999 L1.000,2.999 L4.000,2.999 L4.000,3.999 L1.000,3.999 L1.000,9.999 Z' class='cls-1' /> </svg>

After

Width:  |  Height:  |  Size: 862 B

View File

@ -1,8 +1,8 @@
.. _tutorial_adding_sub_domains:
.. _add_sub_domains:
******************
Adding Sub domains
******************
***************
Add sub domains
***************
This tutorial gives you a brief overview how to serve your project under one subdomain via
the project directory name as well as how to serve one project with multiple subdomains with
@ -59,7 +59,7 @@ default generation process via templates. Those templates can be added to each p
you the option to customize the virtual host of this specific project.
.. note::
:ref:`custom_vhost`
:ref:`customize_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.
@ -82,7 +82,7 @@ you the option to customize the virtual host of this specific project.
**See also:**
* :ref:`tutorial_work_inside_the_php_container`
* :ref:`work_inside_the_php_container`
* :ref:`available_tools`
@ -218,7 +218,7 @@ See here how to do that for Linux, MacOS or Windows:
:ref:`getting_started_create_your_first_project_dns_entry`
This however is not really convenient. If you have basically infinite sub domains (via catch-all),
you should consider using Auto-DNS instead: :ref:`global_configuration_auto_dns`.
you should consider using Auto-DNS instead: :ref:`setup_auto_dns`.
Step 2: Adjust apache22.yml
"""""""""""""""""""""""""""
@ -388,7 +388,7 @@ See here how to do that for Linux, MacOS or Windows:
:ref:`getting_started_create_your_first_project_dns_entry`
This however is not really convenient. If you have basically infinite sub domains (via catch-all),
you should consider using Auto-DNS instead: :ref:`global_configuration_auto_dns`.
you should consider using Auto-DNS instead: :ref:`setup_auto_dns`.
Step 2: Adjust nginx.yml

View File

@ -1,8 +1,8 @@
.. _communicating_with_external_hosts:
.. _connect_to_external_hosts:
*********************************
Communicating with external hosts
*********************************
*************************
Connect to external hosts
*************************
This tutorial shows you how to connect the Devilbox to running Docker container outside the
Devilbox network, i.e. Docker container you have started separately.
@ -158,7 +158,7 @@ The CNAME ``docker.for.win.host.internal`` will be resolved to an IP address dur
Auto DNS
--------
If you also turned on :ref:`global_configuration_auto_dns` these extra hosts will then also be available
If you also turned on :ref:`setup_auto_dns` these extra hosts will then also be available
to your host operating system as well.
@ -167,4 +167,4 @@ Further reading
.. seealso::
* :ref:`env_extra_hosts`
* :ref:`global_configuration_auto_dns`
* :ref:`setup_auto_dns`

View File

@ -1,8 +1,8 @@
.. _custom_vhost:
.. _customize_virtual_host:
***********************************
Customized virtual host (vhost-gen)
***********************************
**********************************
Customize virtual host (vhost-gen)
**********************************
**Table of Contents**
@ -412,4 +412,4 @@ Further readings
.. seealso::
Have a look at the following examples which involve customizing vhost-gen templates:
* :ref:`tutorial_adding_sub_domains`
* :ref:`add_sub_domains`

View File

@ -21,7 +21,7 @@ from recommonmark.parser import CommonMarkParser
# -- Project information -----------------------------------------------------
project = u'devilbox'
project = u'Devilbox'
copyright = u'2018, cytopia'
author = u'cytopia'
@ -75,11 +75,20 @@ language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path .
exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']
exclude_patterns = [
u'_build/*',
u'_includes/*',
u'Thumbs.db',
u'.DS_Store'
]
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
rst_epilog = """
.. |psf| replace:: Devilbox
"""
# -- Options for Link check -------------------------------------------------
@ -124,7 +133,7 @@ html_theme_options = {
'logo_only': False,
'display_version': True,
'prev_next_buttons_location': 'bottom',
#'style_external_links': False,
#'style_external_links': True,
#'vcs_pageview_mode': '',
# Toc options
'collapse_navigation': False,
@ -150,7 +159,12 @@ html_static_path = ['_static']
# html_sidebars = {}
def setup(app):
app.add_stylesheet('css/custom.css')
'''Include custom css file'''
app.add_stylesheet('css/devilbox.css')
# If true, “Created using Sphinx” is shown in the HTML footer. Default is True.
html_show_sphinx = False
# -- Options for HTMLHelp output ---------------------------------------------
@ -183,8 +197,13 @@ latex_elements = {
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'devilbox.tex', u'devilbox Documentation',
u'cytopia', 'manual'),
(
master_doc,
'devilbox.tex',
u'Devilbox Documentation',
u'cytopia',
'manual'
),
]
@ -193,8 +212,13 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'devilbox', u'devilbox Documentation',
[author], 1)
(
master_doc,
'devilbox',
u'Devilbox Documentation',
[author],
1
)
]
@ -204,7 +228,13 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'devilbox', u'devilbox Documentation',
author, 'devilbox', 'One line description of project.',
'Miscellaneous'),
(
master_doc,
'devilbox',
u'Devilbox Documentation',
author,
'devilbox',
'A modern dockerized LAMP and MEAN stack alternative to XAMPP',
'Miscellaneous'
),
]

View File

@ -13,7 +13,7 @@ custom configurations.
.. important::
You could actually also create virtual hosts here, but it is recommended to use the
Devilbox Auto-vhost generation feature. If you want to custimize your current virtual hosts
have a look at :ref:`custom_vhost`.
have a look at :ref:`customize_virtual_host`.
**Table of Contents**

View File

@ -7,7 +7,7 @@ bashrc.sh
Each PHP container is using bash as its default shell. If you do not like the way it is currently
configured, you can add your own configuration files to overwrite settings.
.. seealso:: :ref:`tutorial_work_inside_the_php_container`
.. seealso:: :ref:`work_inside_the_php_container`
**Table of Contents**

View File

@ -5,9 +5,12 @@
*********
All docker-compose configuration is done inside the ``.env`` file which simply defines key-value
variables parsed to docker-compose.yml.
pairs evaluated by docker-compose.yml.
.. note::
If this file does not exist at the root of your Devilbox git directory, then copy ``env-example``
to ``.env`` to initially create it with sane defaults.
.. seealso::
what is the `.env <https://docs.docker.com/compose/env-file/>`_ file?
.. note::
@ -311,7 +314,7 @@ A few examples for adding extra hosts:
This resembles the feature of `Docker Compose: extra_hosts <https://docs.docker.com/compose/compose-file/#external_links>`_ to add external links.
.. seealso:: :ref:`communicating_with_external_hosts`
.. seealso:: :ref:`connect_to_external_hosts`
.. _env_new_uid:
@ -449,7 +452,7 @@ hostname.
* ``DEVILBOX_UI_SSL_CN=localhost,*.localhost,devilbox,*.devilbox``
* ``DEVILBOX_UI_SSL_CN=intranet.example.com``
.. seealso:: :ref:`configuration_https_ssl`
.. seealso:: :ref:`setup_valid_https`
.. _env_devilbox_ui_protect:
@ -989,7 +992,7 @@ Open the command prompt and type the following:
TCP 0.0.0.0:1875 0.0.0.0:0 LISTENING
.. warning::
:ref:`docker_toolbox`
:ref:`howto_docker_toolbox_and_the_devilbox`
When using Docker Toobox ensure that ports are exposed to all interfaces.
See :ref:`env_local_listen_addr`
@ -1109,7 +1112,7 @@ to something else if ``53`` is already in use on your host operating system.
on port ``53`` which would result in a failure when this BIND server is starting.
You only need to set BIND to port ``53`` when you want to use the ``Auto-DNS`` feautre of the
Devilbox. When doing so, read this article with care: :ref:`global_configuration_auto_dns`.
Devilbox. When doing so, read this article with care: :ref:`setup_auto_dns`.
Container settings
@ -1196,7 +1199,7 @@ This will then output ``development``.
.. note::
Add as many custom environment variables as you require.
.. seealso:: :ref:`tutorial_custom_environment_variables`
.. seealso:: :ref:`add_custom_environment_variables`
Web server
@ -1373,11 +1376,11 @@ changing the server name or adding locations to other assets.
.. seealso::
**Customize your virtual host**
When you want to find out more how to actually customize each virtual host to its own need,
read up more on :ref:`custom_vhost`.
read up more on :ref:`customize_virtual_host`.
**Tutorials**
Also have a look at this tutorial which is a walk-through showing you how to modify
a virtual host and make it serve all files for multiple sub domains (server names):
:ref:`tutorial_adding_sub_domains`
:ref:`add_sub_domains`
MySQL

View File

@ -10,7 +10,7 @@ MySQL version.
.. important::
When using :ref:`docker_toolbox` on Windows, ``*.cnf`` files must have read-only file
When using :ref:`howto_docker_toolbox_and_the_devilbox` on Windows, ``*.cnf`` files must have read-only file
permissions, otherwise they are not sourced by the MySQL server.
Make sure to ``chmod 0444 *.cnf`` after adding your values.

View File

@ -13,7 +13,7 @@ supplying custom configurations.
.. important::
You could actually also create virtual hosts here, but it is recommended to use the
Devilbox Auto-vhost generation feature. If you want to custimize your current virtual hosts
have a look at :ref:`custom_vhost`.
have a look at :ref:`customize_virtual_host`.
**Table of Contents**

View File

@ -1,158 +0,0 @@
.. _project_configuration_dns_records:
***********
DNS records
***********
Project DNS records are required, because each project is using its own virtual host with its own
unique server name.
The server name is constructed by a ``<project-directory>`` and the :ref:`env_tld_suffix` and
requires the same DNS record to be present in order to access it.
.. seealso::
This section gives you an overview about how to create separate DNS records for each project.
It has to be done for each project, however if you want to automate the process, refer
to :ref:`global_configuration_auto_dns`.
**Table of Contents**
.. contents:: :local:
Examples
========
In order to better illustrate the process, we are going to use two projects as an example.
See the following table for project directories and TLD_SUFFIX.
+-------------------+------------+--------------------------+-----------------------+
| Project directory | TLD_SUFFIX | Project URL | Required DNS name |
+===================+============+==========================+=======================+
| project-1 | ``loc`` | http://project-1.loc | ``project-1.loc`` |
+-------------------+------------+--------------------------+-----------------------+
| www.project-1 | ``loc`` | http://www.project-1.loc | ``www.project-1.loc`` |
+-------------------+------------+--------------------------+-----------------------+
.. note::
When you have created the above two projects, you can check the vhost page on the
Devilbox intranet. It will tell you exactly what DNS record to add.
.. image:: /_static/img/devilbox-vhosts-dns.png
.. important:: The IP address ``127.0.0.1`` is different for :ref:`docker_toolbox`
Creating DNS records
====================
When creating DNS records for your host operating system, there are two distinctions to be made.
If you use Native Docker (the default and recommended Docker), you can always use ``127.0.0.1``
as your IP address for the DNS record. If however your use Docker Toolbox, you first need to
find out the IP address of the Docker Toolbox virtual machine.
.. seealso:: :ref:`docker_toolbox`
Native Docker
-------------
Linux
^^^^^
Use your favorite editor and open ``/etc/hosts`` with root privileges. The following example
uses vim to add the two example DNS records.
.. code-block:: bash
host> sudo vim /etc/hosts
127.0.0.1 project-1.loc
127.0.0.1 www.project-1.loc
MacOS
^^^^^
Use your favorite editor and open ``/etc/hosts`` with root privileges. The following example
uses vim to add the two example DNS records.
.. code-block:: bash
host> sudo vim /etc/hosts
127.0.0.1 project-1.loc
127.0.0.1 www.project-1.loc
Windows
^^^^^^^
On Windows you need to open ``C:\Windows\System32\drivers\etc`` with administrative privileges
and add the following two lines:
.. code-block:: bash
127.0.0.1 project-1.loc
127.0.0.1 www.project-1.loc
Docker Toolbox
--------------
When using Docker Toolbox the Devilbox runs inside a virtual machine and therefore the webserver
port (80) is not exposed to your host operating system. So your DNS record must point to the
virtual machine instead of your host system.
1. Find out the IP address the virtual machine is running on
2. Add a DNS entry to your host operating system for this IP address.
For the sake of this example, lets assume the virtual machine is running on ``192.16.0.1``
MacOS
^^^^^
Use your favorite editor and open ``/etc/hosts`` with root privileges. The following example
uses vim to add the two example DNS records.
.. code-block:: bash
host> sudo vim /etc/hosts
192.16.0.1 project-1.loc
192.16.0.1 www.project-1.loc
Windows
^^^^^^^
On Windows you need to open ``C:\Windows\System32\drivers\etc`` with administrative privileges
and add the following two lines:
.. code-block:: bash
192.16.0.1 project-1.loc
192.16.0.1 www.project-1.loc
Verify
======
After settings the DNS records, you can use the ``ping`` command to verify if everything works.
.. code-block:: bash
host> ping -c1 project-1.loc
PING project-1.loc (127.0.0.1) 56(84) bytes of data.
64 bytes from localhost (127.0.0.1): icmp_seq=1 ttl=64 time=0.066 ms
.. code-block:: bash
host> ping -c1 www.project-1.loc
PING www.project-1.loc (127.0.0.1) 56(84) bytes of data.
64 bytes from localhost (127.0.0.1): icmp_seq=1 ttl=64 time=0.066 ms

76
docs/devilbox-purpose.rst Normal file
View File

@ -0,0 +1,76 @@
****************
Devilbox purpose
****************
The Devilbox aims to provide you a universal zero-configuration LAMP and MEAN development
environment for any purpose which is setup in less than 5 minutes.
Its main intention is to support an unlimited number of projects for any framework or cms
and be portable accross all major operating systems, as well as providing any available php version
with whatever module you require.
To be portable, customizable and as leight weight as possible, the choice fell on a Dockerized
setup.
Why did I built this?
=====================
In one of my previous jobs I had to maintain around 30 different PHP projects. Many of them
utilized different versions and configuration, thus I had to switch between my local MacOS and
various Linux VMs on a frequent base in order to fullfill the current requirement.
Setting up new vhosts, local DNS entries, self-signed https certificates, installing other PHP
versions, ensuring I had all modules and lots of other initial configuration was always a pain to
me, so I decided to automate this.
Automation is key
=================
A few month after releasing it on Github I hit another problem: Tickets regarding outdated versions
as well as new major version requests accumulated and I spent a lot of time keeping up with
updating and creating Docker images and making them available.
That was the point when I decided to create a fully automated and generalized build infrastructure
for all custom Docker images.
The outcome was this:
* Docker images are generated and verified with Ansible
* Docker images have extensive CI tests
* Docker images are automatically built, tested and updated every night and pushed on success
Issues with Docker encountered
==============================
One of the major issues I have encountered with Docker is the syncronization of file and
directory permissions between local and Docker mounted directories.
This is due to the fact that the process of PHP or the web server usually run with a different
``uid`` and ``gid`` as the local user starting the Docker container. Whenever a new file is created
from inside the container, it will happen with the ``uid`` of the process running inside the
container, thus making it incompatible with your local user.
This problem has been finally addressed with the Devilbox and you can read up on it in much more
detail here: :ref:`syncronize_container_permissions`.
Today's state
=============
Honestly speaking, in the time I spent to build the Devilbox, I could have configured every
possible VM by now, but I would have missed the fun. I learned a lot and in the end it made my
work much more pleasent.
Tomorrow's state
================
I use the Devilbox on a daily base and together with other developers we find more and more edge
cases that are being resolved. As technology also advanced quickly, the Devilbox needs to keep up
with as well. Next major milestones will be to modularize it for easier customization of currently
not available Container, hardening for production usage and workflows for deployments in a CI/CD
landscape.

View File

@ -51,7 +51,7 @@ It will be ready in eight simple steps:
host> ./shell.sh
.. seealso:: :ref:`tutorial_work_inside_the_php_container`
.. seealso:: :ref:`work_inside_the_php_container`
2. Create new vhost directory
@ -124,7 +124,7 @@ It will be ready in eight simple steps:
7. DNS record
-------------
If you do not have :ref:`global_configuration_auto_dns` configured, you will need to add the
If you do not have :ref:`setup_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):
@ -134,8 +134,10 @@ following line to your host operating systems ``/etc/hosts`` file
127.0.0.1 my-cake.loc
.. seealso::
For in-depth info about adding DNS records on Linux, Windows or MacOS see:
:ref:`project_configuration_dns_records` or :ref:`global_configuration_auto_dns`.
* :ref:`howto_add_project_dns_entry_on_mac`
* :ref:`howto_add_project_dns_entry_on_win`
* :ref:`setup_auto_dns`
8. Open your browser

View File

@ -50,7 +50,7 @@ It will be ready in eight simple steps:
host> ./shell.sh
.. seealso:: :ref:`tutorial_work_inside_the_php_container`
.. seealso:: :ref:`work_inside_the_php_container`
2. Create new vhost directory
@ -129,7 +129,7 @@ It will be ready in eight simple steps:
7. DNS record
-------------
If you do not have :ref:`global_configuration_auto_dns` configured, you will need to add the
If you do not have :ref:`setup_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):
@ -139,8 +139,10 @@ following line to your host operating systems ``/etc/hosts`` file
127.0.0.1 my-ci.loc
.. seealso::
For in-depth info about adding DNS records on Linux, Windows or MacOS see:
:ref:`project_configuration_dns_records` or :ref:`global_configuration_auto_dns`.
* :ref:`howto_add_project_dns_entry_on_mac`
* :ref:`howto_add_project_dns_entry_on_win`
* :ref:`setup_auto_dns`
8. Open your browser

View File

@ -49,7 +49,7 @@ It will be ready in six simple steps:
host> ./shell.sh
.. seealso:: :ref:`tutorial_work_inside_the_php_container`
.. seealso:: :ref:`work_inside_the_php_container`
2. Create new vhost directory
@ -80,7 +80,7 @@ It will be ready in six simple steps:
5. DNS record
-------------
If you do not have :ref:`global_configuration_auto_dns` configured, you will need to add the
If you do not have :ref:`setup_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):
@ -90,8 +90,10 @@ following line to your host operating systems ``/etc/hosts`` file
127.0.0.1 my-drupal.loc
.. seealso::
For in-depth info about adding DNS records on Linux, Windows or MacOS see:
:ref:`project_configuration_dns_records` or :ref:`global_configuration_auto_dns`.
* :ref:`howto_add_project_dns_entry_on_mac`
* :ref:`howto_add_project_dns_entry_on_win`
* :ref:`setup_auto_dns`
6. Open your browser

View File

@ -49,7 +49,7 @@ It will be ready in six simple steps:
host> ./shell.sh
.. seealso:: :ref:`tutorial_work_inside_the_php_container`
.. seealso:: :ref:`work_inside_the_php_container`
2. Create new vhost directory
@ -82,7 +82,7 @@ It will be ready in six simple steps:
5. DNS record
-------------
If you do not have :ref:`global_configuration_auto_dns` configured, you will need to add the
If you do not have :ref:`setup_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):
@ -92,8 +92,10 @@ following line to your host operating systems ``/etc/hosts`` file
127.0.0.1 my-joomla.loc
.. seealso::
For in-depth info about adding DNS records on Linux, Windows or MacOS see:
:ref:`project_configuration_dns_records` or :ref:`global_configuration_auto_dns`.
* :ref:`howto_add_project_dns_entry_on_mac`
* :ref:`howto_add_project_dns_entry_on_win`
* :ref:`setup_auto_dns`
6. Open your browser

View File

@ -49,7 +49,7 @@ It will be ready in six simple steps:
host> ./shell.sh
.. seealso:: :ref:`tutorial_work_inside_the_php_container`
.. seealso:: :ref:`work_inside_the_php_container`
2. Create new vhost directory
@ -80,7 +80,7 @@ It will be ready in six simple steps:
5. DNS record
-------------
If you do not have :ref:`global_configuration_auto_dns` configured, you will need to add the
If you do not have :ref:`setup_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):
@ -90,8 +90,10 @@ following line to your host operating systems ``/etc/hosts`` file
127.0.0.1 my-laravel.loc
.. seealso::
For in-depth info about adding DNS records on Linux, Windows or MacOS see:
:ref:`project_configuration_dns_records` or :ref:`global_configuration_auto_dns`.
* :ref:`howto_add_project_dns_entry_on_mac`
* :ref:`howto_add_project_dns_entry_on_win`
* :ref:`setup_auto_dns`
6. Open your browser

View File

@ -49,7 +49,7 @@ It will be ready in six simple steps:
host> ./shell.sh
.. seealso:: :ref:`tutorial_work_inside_the_php_container`
.. seealso:: :ref:`work_inside_the_php_container`
2. Create new vhost directory
@ -80,7 +80,7 @@ It will be ready in six simple steps:
5. DNS record
-------------
If you do not have :ref:`global_configuration_auto_dns` configured, you will need to add the
If you do not have :ref:`setup_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):
@ -90,8 +90,10 @@ following line to your host operating systems ``/etc/hosts`` file
127.0.0.1 my-phalcon.loc
.. seealso::
For in-depth info about adding DNS records on Linux, Windows or MacOS see:
:ref:`project_configuration_dns_records` or :ref:`global_configuration_auto_dns`.
* :ref:`howto_add_project_dns_entry_on_mac`
* :ref:`howto_add_project_dns_entry_on_win`
* :ref:`setup_auto_dns`
6. Open your browser

View File

@ -51,7 +51,7 @@ It will be ready in six simple steps:
host> ./shell.sh
.. seealso:: :ref:`tutorial_work_inside_the_php_container`
.. seealso:: :ref:`work_inside_the_php_container`
2. Create new vhost directory
@ -90,7 +90,7 @@ itself beforehand.
5. DNS record
-------------
If you do not have :ref:`global_configuration_auto_dns` configured, you will need to add the
If you do not have :ref:`setup_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):
@ -100,8 +100,10 @@ following line to your host operating systems ``/etc/hosts`` file
127.0.0.1 my-photon.loc
.. seealso::
For in-depth info about adding DNS records on Linux, Windows or MacOS see:
:ref:`project_configuration_dns_records` or :ref:`global_configuration_auto_dns`.
* :ref:`howto_add_project_dns_entry_on_mac`
* :ref:`howto_add_project_dns_entry_on_win`
* :ref:`setup_auto_dns`
6. Open your browser

Some files were not shown because too many files have changed in this diff Show More