diff --git a/.gitignore b/.gitignore index afab0a11..2e353da2 100644 --- a/.gitignore +++ b/.gitignore @@ -82,7 +82,6 @@ docker-compose.override.yml # Ignore documentation sphinx build /docs/_build/ /docs/make.bat -/docs/Makefile *.rst.todo # Keep folders diff --git a/.travis.yml b/.travis.yml index 2306f4ad..f279fdcf 100644 --- a/.travis.yml +++ b/.travis.yml @@ -185,7 +185,9 @@ before_script: script: - if [ "${S1}" = "DOCUMENTATION" ]; then cd docs/; - sphinx-build -a -W -E -j auto -n -v . _build/html/; + make build; + make linkcheck; + make linkcheck2; else .tests/test_single.sh . "${S1}" "${V1}" "${S2}" "${V2}"; fi diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..e29ffb07 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,58 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = devilbox +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + @echo + @echo "Devilbox additional commands:" + @echo " build Build and test documentation" + @echo " autobuild Continuously run and build (http://127.0.0.1:8000)" + +.PHONY: help Makefile test build autobuild + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + + +# +# Devilbox additions +# +# +# Used Sphinx options: +# -------------------- +# +# -a: Always write all output files. The default is to only write output files +# for new and changed source files. +# +# -E: Don’t use a saved environment (the structure caching all cross-references), +# but rebuild it completely. +# +# -n: Run in nit-picky mode. Currently, this generates warnings for all +# missing references. See the config value nitpick_ignore for a way to +# exclude some references as “known missing”. +# +# -q: Do not output anything on standard output, only write warnings and errors +# to standard error. +# +# -W: Turn warnings into errors. This means that the build stops at the first +# warning and sphinx-build exits with exit status 1. + + +linkcheck2: + ./linkcheck.sh -r 10 -t 10 -e rst _includes/ + +build: + sphinx-build -a -E -n -j auto -q -W . _build/html + +autobuild: + sphinx-autobuild . _build/html diff --git a/docs/README.md b/docs/README.md index bcfa62fa..1ea5e303 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 diff --git a/docs/_includes/all.rst b/docs/_includes/all.rst new file mode 100644 index 00000000..dd5767c9 --- /dev/null +++ b/docs/_includes/all.rst @@ -0,0 +1,38 @@ +.. + ============================================================ + HTML + ============================================================ + +.. include:: /_includes/html/defaults.rst + + + +.. + ============================================================ + Images + ============================================================ + +.. include:: /_includes/images/external.rst + + + +.. + ============================================================ + Links + ============================================================ + +.. include:: /_includes/links/apps.rst +.. include:: /_includes/links/blogs.rst +.. include:: /_includes/links/dns.rst +.. include:: /_includes/links/documentation.rst +.. include:: /_includes/links/docker.rst +.. include:: /_includes/links/docker-compose.rst +.. include:: /_includes/links/docker-images.rst +.. include:: /_includes/links/examples.rst +.. include:: /_includes/links/git.rst +.. include:: /_includes/links/prerequistes.rst +.. include:: /_includes/links/ssh.rst +.. include:: /_includes/links/ssl.rst +.. include:: /_includes/links/tools.rst +.. include:: /_includes/links/uid.rst +.. include:: /_includes/links/xdebug.rst diff --git a/docs/_static/img/youtube-email-catch-all.png b/docs/_includes/figures/blogs/youtube-email-catch-all.png similarity index 100% rename from docs/_static/img/youtube-email-catch-all.png rename to docs/_includes/figures/blogs/youtube-email-catch-all.png diff --git a/docs/_includes/figures/blogs/youtube-email-catch-all.rst b/docs/_includes/figures/blogs/youtube-email-catch-all.rst new file mode 100644 index 00000000..a954e592 --- /dev/null +++ b/docs/_includes/figures/blogs/youtube-email-catch-all.rst @@ -0,0 +1,2 @@ +.. figure:: /_includes/figures/blogs/youtube-email-catch-all.png + :target: https://www.youtube.com/watch?v=e-U-C5WhxGY diff --git a/docs/_static/img/youtube-setup-and-workflow.png b/docs/_includes/figures/blogs/youtube-setup-and-workflow.png similarity index 100% rename from docs/_static/img/youtube-setup-and-workflow.png rename to docs/_includes/figures/blogs/youtube-setup-and-workflow.png diff --git a/docs/_includes/figures/blogs/youtube-setup-and-workflow.rst b/docs/_includes/figures/blogs/youtube-setup-and-workflow.rst new file mode 100644 index 00000000..dbd4b994 --- /dev/null +++ b/docs/_includes/figures/blogs/youtube-setup-and-workflow.rst @@ -0,0 +1,2 @@ +.. figure:: /_includes/figures/blogs/youtube-setup-and-workflow.png + :target: https://www.youtube.com/watch?v=reyZMyt2Zzo diff --git a/docs/_static/img/devilbox-dash-full.png b/docs/_includes/figures/devilbox/devilbox-intranet-dash-all.png similarity index 100% rename from docs/_static/img/devilbox-dash-full.png rename to docs/_includes/figures/devilbox/devilbox-intranet-dash-all.png diff --git a/docs/_includes/figures/devilbox/devilbox-intranet-dash-all.rst b/docs/_includes/figures/devilbox/devilbox-intranet-dash-all.rst new file mode 100644 index 00000000..8c133dbb --- /dev/null +++ b/docs/_includes/figures/devilbox/devilbox-intranet-dash-all.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/devilbox/devilbox-intranet-dash-all.png + + Devilbox intranet: index dash view for all started container diff --git a/docs/_static/img/devilbox-dash-selective.png b/docs/_includes/figures/devilbox/devilbox-intranet-dash-selective.png similarity index 100% rename from docs/_static/img/devilbox-dash-selective.png rename to docs/_includes/figures/devilbox/devilbox-intranet-dash-selective.png diff --git a/docs/_includes/figures/devilbox/devilbox-intranet-dash-selective.rst b/docs/_includes/figures/devilbox/devilbox-intranet-dash-selective.rst new file mode 100644 index 00000000..2676691c --- /dev/null +++ b/docs/_includes/figures/devilbox/devilbox-intranet-dash-selective.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/devilbox/devilbox-intranet-dash-selective.png + + Devilbox intranet: index dash view for some started container diff --git a/docs/_static/img/devilbox-emails.png b/docs/_includes/figures/devilbox/devilbox-intranet-emails.png similarity index 100% rename from docs/_static/img/devilbox-emails.png rename to docs/_includes/figures/devilbox/devilbox-intranet-emails.png diff --git a/docs/_includes/figures/devilbox/devilbox-intranet-emails.rst b/docs/_includes/figures/devilbox/devilbox-intranet-emails.rst new file mode 100644 index 00000000..3d9e28ab --- /dev/null +++ b/docs/_includes/figures/devilbox/devilbox-intranet-emails.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/devilbox/devilbox-intranet-emails.png + + Devilbox intranet: email catch-all overview diff --git a/docs/_static/img/devilbox-index.png b/docs/_includes/figures/devilbox/devilbox-intranet-index.png similarity index 100% rename from docs/_static/img/devilbox-index.png rename to docs/_includes/figures/devilbox/devilbox-intranet-index.png diff --git a/docs/_includes/figures/devilbox/devilbox-intranet-index.rst b/docs/_includes/figures/devilbox/devilbox-intranet-index.rst new file mode 100644 index 00000000..8de25c7a --- /dev/null +++ b/docs/_includes/figures/devilbox/devilbox-intranet-index.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/devilbox/devilbox-intranet-index.png + + Devilbox intranet: homepage diff --git a/docs/_static/img/devilbox-database.png b/docs/_includes/figures/devilbox/devilbox-intranet-mysql-databases.png similarity index 100% rename from docs/_static/img/devilbox-database.png rename to docs/_includes/figures/devilbox/devilbox-intranet-mysql-databases.png diff --git a/docs/_includes/figures/devilbox/devilbox-intranet-mysql-databases.rst b/docs/_includes/figures/devilbox/devilbox-intranet-mysql-databases.rst new file mode 100644 index 00000000..1a58cee5 --- /dev/null +++ b/docs/_includes/figures/devilbox/devilbox-intranet-mysql-databases.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/devilbox/devilbox-intranet-mysql-databases.png + + Devilbox intranet: MySQL database overview diff --git a/docs/_static/img/devilbox-info-mysql.png b/docs/_includes/figures/devilbox/devilbox-intranet-mysql-info.png similarity index 100% rename from docs/_static/img/devilbox-info-mysql.png rename to docs/_includes/figures/devilbox/devilbox-intranet-mysql-info.png diff --git a/docs/_includes/figures/devilbox/devilbox-intranet-mysql-info.rst b/docs/_includes/figures/devilbox/devilbox-intranet-mysql-info.rst new file mode 100644 index 00000000..8a3a54f1 --- /dev/null +++ b/docs/_includes/figures/devilbox/devilbox-intranet-mysql-info.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/devilbox/devilbox-intranet-mysql-info.png + + Devilbox intranet: MySQL info overview diff --git a/docs/_static/img/devilbox-info-php.png b/docs/_includes/figures/devilbox/devilbox-intranet-php-info.png similarity index 100% rename from docs/_static/img/devilbox-info-php.png rename to docs/_includes/figures/devilbox/devilbox-intranet-php-info.png diff --git a/docs/_includes/figures/devilbox/devilbox-intranet-php-info.rst b/docs/_includes/figures/devilbox/devilbox-intranet-php-info.rst new file mode 100644 index 00000000..747533dd --- /dev/null +++ b/docs/_includes/figures/devilbox/devilbox-intranet-php-info.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/devilbox/devilbox-intranet-php-info.png + + Devilbox intranet: php info diff --git a/docs/_static/img/devilbox-vhosts-empty.png b/docs/_includes/figures/devilbox/devilbox-intranet-vhosts-empty.png similarity index 100% rename from docs/_static/img/devilbox-vhosts-empty.png rename to docs/_includes/figures/devilbox/devilbox-intranet-vhosts-empty.png diff --git a/docs/_includes/figures/devilbox/devilbox-intranet-vhosts-empty.rst b/docs/_includes/figures/devilbox/devilbox-intranet-vhosts-empty.rst new file mode 100644 index 00000000..8150e67d --- /dev/null +++ b/docs/_includes/figures/devilbox/devilbox-intranet-vhosts-empty.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/devilbox/devilbox-intranet-vhosts-empty.png + + Devilbox intranet: no projects created diff --git a/docs/_static/img/devilbox-vhosts-dns.png b/docs/_includes/figures/devilbox/devilbox-intranet-vhosts-missing-dns.png similarity index 100% rename from docs/_static/img/devilbox-vhosts-dns.png rename to docs/_includes/figures/devilbox/devilbox-intranet-vhosts-missing-dns.png diff --git a/docs/_includes/figures/devilbox/devilbox-intranet-vhosts-missing-dns.rst b/docs/_includes/figures/devilbox/devilbox-intranet-vhosts-missing-dns.rst new file mode 100644 index 00000000..34286005 --- /dev/null +++ b/docs/_includes/figures/devilbox/devilbox-intranet-vhosts-missing-dns.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/devilbox/devilbox-intranet-vhosts-missing-dns.png + + Devilbox intranet: misssing dns record diff --git a/docs/_static/img/devilbox-vhosts-directory.png b/docs/_includes/figures/devilbox/devilbox-intranet-vhosts-missing-htdocs.png similarity index 100% rename from docs/_static/img/devilbox-vhosts-directory.png rename to docs/_includes/figures/devilbox/devilbox-intranet-vhosts-missing-htdocs.png diff --git a/docs/_includes/figures/devilbox/devilbox-intranet-vhosts-missing-htdocs.rst b/docs/_includes/figures/devilbox/devilbox-intranet-vhosts-missing-htdocs.rst new file mode 100644 index 00000000..f6e8f757 --- /dev/null +++ b/docs/_includes/figures/devilbox/devilbox-intranet-vhosts-missing-htdocs.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/devilbox/devilbox-intranet-vhosts-missing-htdocs.png + + Devilbox intranet: misssing ``htdocs`` directory diff --git a/docs/_static/img/devilbox-vhosts-finished.png b/docs/_includes/figures/devilbox/devilbox-intranet-vhosts-working.png similarity index 100% rename from docs/_static/img/devilbox-vhosts-finished.png rename to docs/_includes/figures/devilbox/devilbox-intranet-vhosts-working.png diff --git a/docs/_includes/figures/devilbox/devilbox-intranet-vhosts-working.rst b/docs/_includes/figures/devilbox/devilbox-intranet-vhosts-working.rst new file mode 100644 index 00000000..d0b9357c --- /dev/null +++ b/docs/_includes/figures/devilbox/devilbox-intranet-vhosts-working.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/devilbox/devilbox-intranet-vhosts-working.png + + Devilbox intranet: vhost setup successfully diff --git a/docs/_static/img/devilbox-vhosts.png b/docs/_includes/figures/devilbox/devilbox-intranet-vhosts.png similarity index 100% rename from docs/_static/img/devilbox-vhosts.png rename to docs/_includes/figures/devilbox/devilbox-intranet-vhosts.png diff --git a/docs/_includes/figures/devilbox/devilbox-intranet-vhosts.rst b/docs/_includes/figures/devilbox/devilbox-intranet-vhosts.rst new file mode 100644 index 00000000..a638a4bc --- /dev/null +++ b/docs/_includes/figures/devilbox/devilbox-intranet-vhosts.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/devilbox/devilbox-intranet-vhosts.png + + Devilbox intranet: available virtual hosts diff --git a/docs/_static/img/devilbox-project-hello-world.png b/docs/_includes/figures/devilbox/devilbox-project-hello-world.png similarity index 100% rename from docs/_static/img/devilbox-project-hello-world.png rename to docs/_includes/figures/devilbox/devilbox-project-hello-world.png diff --git a/docs/_includes/figures/devilbox/devilbox-project-hello-world.rst b/docs/_includes/figures/devilbox/devilbox-project-hello-world.rst new file mode 100644 index 00000000..f63ce738 --- /dev/null +++ b/docs/_includes/figures/devilbox/devilbox-project-hello-world.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/devilbox/devilbox-project-hello-world.png + + Devilbox project: hello world on ``index.php`` diff --git a/docs/_static/img/devilbox-project-no-files.png b/docs/_includes/figures/devilbox/devilbox-project-missing-index.png similarity index 100% rename from docs/_static/img/devilbox-project-no-files.png rename to docs/_includes/figures/devilbox/devilbox-project-missing-index.png diff --git a/docs/_includes/figures/devilbox/devilbox-project-missing-index.rst b/docs/_includes/figures/devilbox/devilbox-project-missing-index.rst new file mode 100644 index 00000000..42c2a23b --- /dev/null +++ b/docs/_includes/figures/devilbox/devilbox-project-missing-index.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/devilbox/devilbox-project-missing-index.png + + Devilbox project: misssing ``index.php`` or ``index.html`` diff --git a/docs/_includes/figures/dns-server/android/android-wifi-advanced-options.jpg b/docs/_includes/figures/dns-server/android/android-wifi-advanced-options.jpg new file mode 100644 index 00000000..57a5fabd Binary files /dev/null and b/docs/_includes/figures/dns-server/android/android-wifi-advanced-options.jpg differ diff --git a/docs/_includes/figures/dns-server/android/android-wifi-advanced-options.rst b/docs/_includes/figures/dns-server/android/android-wifi-advanced-options.rst new file mode 100644 index 00000000..32bc72a2 --- /dev/null +++ b/docs/_includes/figures/dns-server/android/android-wifi-advanced-options.rst @@ -0,0 +1,4 @@ +.. figure:: /_includes/figures/dns-server/android/android-wifi-advanced-options.jpg + :width: 250px + + Android: Advanced options diff --git a/docs/_includes/figures/dns-server/android/android-wifi-list.jpg b/docs/_includes/figures/dns-server/android/android-wifi-list.jpg new file mode 100644 index 00000000..d3f2bdb0 Binary files /dev/null and b/docs/_includes/figures/dns-server/android/android-wifi-list.jpg differ diff --git a/docs/_includes/figures/dns-server/android/android-wifi-list.rst b/docs/_includes/figures/dns-server/android/android-wifi-list.rst new file mode 100644 index 00000000..313b0932 --- /dev/null +++ b/docs/_includes/figures/dns-server/android/android-wifi-list.rst @@ -0,0 +1,4 @@ +.. figure:: /_includes/figures/dns-server/android/android-wifi-list.jpg + :width: 250px + + Android: Wi-Fi list diff --git a/docs/_includes/figures/dns-server/android/android-wifi-select-dhcp-options-static.jpg b/docs/_includes/figures/dns-server/android/android-wifi-select-dhcp-options-static.jpg new file mode 100644 index 00000000..a7ae3444 Binary files /dev/null and b/docs/_includes/figures/dns-server/android/android-wifi-select-dhcp-options-static.jpg differ diff --git a/docs/_includes/figures/dns-server/android/android-wifi-select-dhcp-options-static.rst b/docs/_includes/figures/dns-server/android/android-wifi-select-dhcp-options-static.rst new file mode 100644 index 00000000..faf65691 --- /dev/null +++ b/docs/_includes/figures/dns-server/android/android-wifi-select-dhcp-options-static.rst @@ -0,0 +1,4 @@ +.. figure:: /_includes/figures/dns-server/android/android-wifi-select-dhcp-options-static.jpg + :width: 250px + + Android: Select static DHCP options diff --git a/docs/_includes/figures/dns-server/android/android-wifi-select-dhcp-options.jpg b/docs/_includes/figures/dns-server/android/android-wifi-select-dhcp-options.jpg new file mode 100644 index 00000000..281e4501 Binary files /dev/null and b/docs/_includes/figures/dns-server/android/android-wifi-select-dhcp-options.jpg differ diff --git a/docs/_includes/figures/dns-server/android/android-wifi-select-dhcp-options.rst b/docs/_includes/figures/dns-server/android/android-wifi-select-dhcp-options.rst new file mode 100644 index 00000000..87c46d02 --- /dev/null +++ b/docs/_includes/figures/dns-server/android/android-wifi-select-dhcp-options.rst @@ -0,0 +1,4 @@ +.. figure:: /_includes/figures/dns-server/android/android-wifi-select-dhcp-options.jpg + :width: 250px + + Android: Select DHCP options diff --git a/docs/_includes/figures/dns-server/android/android-wifi-set-dns-server.jpg b/docs/_includes/figures/dns-server/android/android-wifi-set-dns-server.jpg new file mode 100644 index 00000000..7bd64aaf Binary files /dev/null and b/docs/_includes/figures/dns-server/android/android-wifi-set-dns-server.jpg differ diff --git a/docs/_includes/figures/dns-server/android/android-wifi-set-dns-server.rst b/docs/_includes/figures/dns-server/android/android-wifi-set-dns-server.rst new file mode 100644 index 00000000..288426d1 --- /dev/null +++ b/docs/_includes/figures/dns-server/android/android-wifi-set-dns-server.rst @@ -0,0 +1,4 @@ +.. figure:: /_includes/figures/dns-server/android/android-wifi-set-dns-server.jpg + :width: 250px + + Android: Add custom DNS server diff --git a/docs/_includes/figures/dns-server/iphone/iphone-wifi-list.jpg b/docs/_includes/figures/dns-server/iphone/iphone-wifi-list.jpg new file mode 100644 index 00000000..bebe631b Binary files /dev/null and b/docs/_includes/figures/dns-server/iphone/iphone-wifi-list.jpg differ diff --git a/docs/_includes/figures/dns-server/iphone/iphone-wifi-list.rst b/docs/_includes/figures/dns-server/iphone/iphone-wifi-list.rst new file mode 100644 index 00000000..2b006d4f --- /dev/null +++ b/docs/_includes/figures/dns-server/iphone/iphone-wifi-list.rst @@ -0,0 +1,4 @@ +.. figure:: /_includes/figures/dns-server/iphone/iphone-wifi-list.jpg + :width: 250px + + iPhone: Wi-Fi list diff --git a/docs/_includes/figures/dns-server/iphone/iphone-wifi-select-manual.jpg b/docs/_includes/figures/dns-server/iphone/iphone-wifi-select-manual.jpg new file mode 100644 index 00000000..23c03131 Binary files /dev/null and b/docs/_includes/figures/dns-server/iphone/iphone-wifi-select-manual.jpg differ diff --git a/docs/_includes/figures/dns-server/iphone/iphone-wifi-select-manual.rst b/docs/_includes/figures/dns-server/iphone/iphone-wifi-select-manual.rst new file mode 100644 index 00000000..09f0d336 --- /dev/null +++ b/docs/_includes/figures/dns-server/iphone/iphone-wifi-select-manual.rst @@ -0,0 +1,4 @@ +.. figure:: /_includes/figures/dns-server/iphone/iphone-wifi-select-manual.jpg + :width: 250px + + iPhone: Wi-Fi list diff --git a/docs/_includes/figures/dns-server/iphone/iphone-wifi-set-dns-server.jpg b/docs/_includes/figures/dns-server/iphone/iphone-wifi-set-dns-server.jpg new file mode 100644 index 00000000..c2bbfa90 Binary files /dev/null and b/docs/_includes/figures/dns-server/iphone/iphone-wifi-set-dns-server.jpg differ diff --git a/docs/_includes/figures/dns-server/iphone/iphone-wifi-set-dns-server.rst b/docs/_includes/figures/dns-server/iphone/iphone-wifi-set-dns-server.rst new file mode 100644 index 00000000..b8e9f630 --- /dev/null +++ b/docs/_includes/figures/dns-server/iphone/iphone-wifi-set-dns-server.rst @@ -0,0 +1,4 @@ +.. figure:: /_includes/figures/dns-server/iphone/iphone-wifi-set-dns-server.jpg + :width: 250px + + iPhone: Wi-Fi list diff --git a/docs/_includes/figures/dns-server/iphone/iphone-wifi-settings.jpg b/docs/_includes/figures/dns-server/iphone/iphone-wifi-settings.jpg new file mode 100644 index 00000000..d4c8c0dd Binary files /dev/null and b/docs/_includes/figures/dns-server/iphone/iphone-wifi-settings.jpg differ diff --git a/docs/_includes/figures/dns-server/iphone/iphone-wifi-settings.rst b/docs/_includes/figures/dns-server/iphone/iphone-wifi-settings.rst new file mode 100644 index 00000000..cf92353a --- /dev/null +++ b/docs/_includes/figures/dns-server/iphone/iphone-wifi-settings.rst @@ -0,0 +1,4 @@ +.. figure:: /_includes/figures/dns-server/iphone/iphone-wifi-settings.jpg + :width: 250px + + iPhone: Wi-Fi list diff --git a/docs/_static/img/auto-dns-macos-dns.png b/docs/_includes/figures/dns-server/mac/mac-network-settings.png similarity index 100% rename from docs/_static/img/auto-dns-macos-dns.png rename to docs/_includes/figures/dns-server/mac/mac-network-settings.png diff --git a/docs/_includes/figures/dns-server/mac/mac-network-settings.rst b/docs/_includes/figures/dns-server/mac/mac-network-settings.rst new file mode 100644 index 00000000..e79ee4ed --- /dev/null +++ b/docs/_includes/figures/dns-server/mac/mac-network-settings.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/dns-server/mac/mac-network-settings.png + + MacOS: network settings diff --git a/docs/_static/img/auto-dns-windows-dns-02.jpg b/docs/_includes/figures/dns-server/windows/win-ethernet-properties.png similarity index 100% rename from docs/_static/img/auto-dns-windows-dns-02.jpg rename to docs/_includes/figures/dns-server/windows/win-ethernet-properties.png diff --git a/docs/_includes/figures/dns-server/windows/win-ethernet-properties.rst b/docs/_includes/figures/dns-server/windows/win-ethernet-properties.rst new file mode 100644 index 00000000..ecec3380 --- /dev/null +++ b/docs/_includes/figures/dns-server/windows/win-ethernet-properties.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/dns-server/windows/win-ethernet-properties.png + + Windows: ethernet properties diff --git a/docs/_static/img/auto-dns-windows-dns-03.jpg b/docs/_includes/figures/dns-server/windows/win-internet-protocol-properties.png similarity index 100% rename from docs/_static/img/auto-dns-windows-dns-03.jpg rename to docs/_includes/figures/dns-server/windows/win-internet-protocol-properties.png diff --git a/docs/_includes/figures/dns-server/windows/win-internet-protocol-properties.rst b/docs/_includes/figures/dns-server/windows/win-internet-protocol-properties.rst new file mode 100644 index 00000000..aa913f27 --- /dev/null +++ b/docs/_includes/figures/dns-server/windows/win-internet-protocol-properties.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/dns-server/windows/win-internet-protocol-properties.png + + Windows: internet protocol properties diff --git a/docs/_static/img/auto-dns-windows-dns-01.jpg b/docs/_includes/figures/dns-server/windows/win-network-connections.png similarity index 100% rename from docs/_static/img/auto-dns-windows-dns-01.jpg rename to docs/_includes/figures/dns-server/windows/win-network-connections.png diff --git a/docs/_includes/figures/dns-server/windows/win-network-connections.rst b/docs/_includes/figures/dns-server/windows/win-network-connections.rst new file mode 100644 index 00000000..de954642 --- /dev/null +++ b/docs/_includes/figures/dns-server/windows/win-network-connections.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/dns-server/windows/win-network-connections.png + + Windows: network connections diff --git a/docs/_static/img/global-configuration/https-ssl-02-chrome-advanced-settings.png b/docs/_includes/figures/https/chrome-advanced-settings.png similarity index 100% rename from docs/_static/img/global-configuration/https-ssl-02-chrome-advanced-settings.png rename to docs/_includes/figures/https/chrome-advanced-settings.png diff --git a/docs/_includes/figures/https/chrome-advanced-settings.rst b/docs/_includes/figures/https/chrome-advanced-settings.rst new file mode 100644 index 00000000..34b036c5 --- /dev/null +++ b/docs/_includes/figures/https/chrome-advanced-settings.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/https/chrome-advanced-settings.png + + Click on ``Manage certificates`` diff --git a/docs/_static/img/global-configuration/https-ssl-03-chrome-authorities.png b/docs/_includes/figures/https/chrome-manage-certificates.png similarity index 100% rename from docs/_static/img/global-configuration/https-ssl-03-chrome-authorities.png rename to docs/_includes/figures/https/chrome-manage-certificates.png diff --git a/docs/_includes/figures/https/chrome-manage-certificates.rst b/docs/_includes/figures/https/chrome-manage-certificates.rst new file mode 100644 index 00000000..f77afb6e --- /dev/null +++ b/docs/_includes/figures/https/chrome-manage-certificates.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/https/chrome-manage-certificates.png + + Click on ``IMPORT`` in the AUTHORITIES tab diff --git a/docs/_static/img/global-configuration/https-ssl-05-chrome-set-trust.png b/docs/_includes/figures/https/chrome-set-trust.png similarity index 100% rename from docs/_static/img/global-configuration/https-ssl-05-chrome-set-trust.png rename to docs/_includes/figures/https/chrome-set-trust.png diff --git a/docs/_includes/figures/https/chrome-set-trust.rst b/docs/_includes/figures/https/chrome-set-trust.rst new file mode 100644 index 00000000..33301cb3 --- /dev/null +++ b/docs/_includes/figures/https/chrome-set-trust.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/https/chrome-set-trust.png + + Tell Chrome to trust this CA diff --git a/docs/_static/img/global-configuration/https-ssl-01-chrome-settings.png b/docs/_includes/figures/https/chrome-settings.png similarity index 100% rename from docs/_static/img/global-configuration/https-ssl-01-chrome-settings.png rename to docs/_includes/figures/https/chrome-settings.png diff --git a/docs/_includes/figures/https/chrome-settings.rst b/docs/_includes/figures/https/chrome-settings.rst new file mode 100644 index 00000000..d7f6cb92 --- /dev/null +++ b/docs/_includes/figures/https/chrome-settings.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/https/chrome-settings.png + + Click on ``Advanced`` diff --git a/docs/_static/img/global-configuration/https-ssl-04-import.png b/docs/_includes/figures/https/file-manager-import-ca.png similarity index 100% rename from docs/_static/img/global-configuration/https-ssl-04-import.png rename to docs/_includes/figures/https/file-manager-import-ca.png diff --git a/docs/_includes/figures/https/file-manager-import-ca.rst b/docs/_includes/figures/https/file-manager-import-ca.rst new file mode 100644 index 00000000..41953328 --- /dev/null +++ b/docs/_includes/figures/https/file-manager-import-ca.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/https/file-manager-import-ca.png + + **Note**: your file manager might look different diff --git a/docs/_static/img/global-configuration/https-ssl-03-firefox-authorities.png b/docs/_includes/figures/https/firefox-certificate-manager.png similarity index 100% rename from docs/_static/img/global-configuration/https-ssl-03-firefox-authorities.png rename to docs/_includes/figures/https/firefox-certificate-manager.png diff --git a/docs/_includes/figures/https/firefox-certificate-manager.rst b/docs/_includes/figures/https/firefox-certificate-manager.rst new file mode 100644 index 00000000..501bd0e3 --- /dev/null +++ b/docs/_includes/figures/https/firefox-certificate-manager.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/https/firefox-certificate-manager.png + + Click on ``Import`` in the Authorities tab diff --git a/docs/_static/img/global-configuration/https-ssl-01-firefox-settings.png b/docs/_includes/figures/https/firefox-preferences.png similarity index 100% rename from docs/_static/img/global-configuration/https-ssl-01-firefox-settings.png rename to docs/_includes/figures/https/firefox-preferences.png diff --git a/docs/_includes/figures/https/firefox-preferences.rst b/docs/_includes/figures/https/firefox-preferences.rst new file mode 100644 index 00000000..4b98dd9d --- /dev/null +++ b/docs/_includes/figures/https/firefox-preferences.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/https/firefox-preferences.png + + Click on ``Privacy & Security`` in the left menu bar diff --git a/docs/_static/img/global-configuration/https-ssl-02-firefox-security-settings.png b/docs/_includes/figures/https/firefox-privacy-and-security.png similarity index 100% rename from docs/_static/img/global-configuration/https-ssl-02-firefox-security-settings.png rename to docs/_includes/figures/https/firefox-privacy-and-security.png diff --git a/docs/_includes/figures/https/firefox-privacy-and-security.rst b/docs/_includes/figures/https/firefox-privacy-and-security.rst new file mode 100644 index 00000000..cc09305b --- /dev/null +++ b/docs/_includes/figures/https/firefox-privacy-and-security.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/https/firefox-privacy-and-security.png + + Click on ``View Certificates`` diff --git a/docs/_static/img/global-configuration/https-ssl-05-firefox-set-trust.png b/docs/_includes/figures/https/firefox-set-trust.png similarity index 100% rename from docs/_static/img/global-configuration/https-ssl-05-firefox-set-trust.png rename to docs/_includes/figures/https/firefox-set-trust.png diff --git a/docs/_includes/figures/https/firefox-set-trust.rst b/docs/_includes/figures/https/firefox-set-trust.rst new file mode 100644 index 00000000..c68d1b23 --- /dev/null +++ b/docs/_includes/figures/https/firefox-set-trust.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/https/firefox-set-trust.png + + Tell Firefox to trust this CA diff --git a/docs/_static/img/global-configuration/https-ssl-address-bar.png b/docs/_includes/figures/https/https-ssl-address-bar.png similarity index 100% rename from docs/_static/img/global-configuration/https-ssl-address-bar.png rename to docs/_includes/figures/https/https-ssl-address-bar.png diff --git a/docs/_includes/figures/https/https-ssl-address-bar.rst b/docs/_includes/figures/https/https-ssl-address-bar.rst new file mode 100644 index 00000000..85b8f6dd --- /dev/null +++ b/docs/_includes/figures/https/https-ssl-address-bar.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/https/https-ssl-address-bar.png + + Valid HTTPS will automatically be available for all projects diff --git a/docs/_includes/figures/terminal/docker-toolbox-terminal-mac-quickstart-launchpad.png b/docs/_includes/figures/terminal/docker-toolbox-terminal-mac-quickstart-launchpad.png new file mode 100644 index 00000000..53cdb9db Binary files /dev/null and b/docs/_includes/figures/terminal/docker-toolbox-terminal-mac-quickstart-launchpad.png differ diff --git a/docs/_includes/figures/terminal/docker-toolbox-terminal-mac-quickstart-launchpad.rst b/docs/_includes/figures/terminal/docker-toolbox-terminal-mac-quickstart-launchpad.rst new file mode 100644 index 00000000..91bf210f --- /dev/null +++ b/docs/_includes/figures/terminal/docker-toolbox-terminal-mac-quickstart-launchpad.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/terminal/docker-toolbox-terminal-mac-quickstart-launchpad.png + + Copyright docs.docker.com diff --git a/docs/_includes/figures/terminal/docker-toolbox-terminal-win-quickstart-shortcut.png b/docs/_includes/figures/terminal/docker-toolbox-terminal-win-quickstart-shortcut.png new file mode 100644 index 00000000..d2c4b683 Binary files /dev/null and b/docs/_includes/figures/terminal/docker-toolbox-terminal-win-quickstart-shortcut.png differ diff --git a/docs/_includes/figures/terminal/docker-toolbox-terminal-win-quickstart-shortcut.rst b/docs/_includes/figures/terminal/docker-toolbox-terminal-win-quickstart-shortcut.rst new file mode 100644 index 00000000..5cb6b0e4 --- /dev/null +++ b/docs/_includes/figures/terminal/docker-toolbox-terminal-win-quickstart-shortcut.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/terminal/docker-toolbox-terminal-win-quickstart-shortcut.png + + Copyright docs.docker.com diff --git a/docs/_includes/figures/terminal/docker-toolbox-terminal-win-quickstart-terminal.png b/docs/_includes/figures/terminal/docker-toolbox-terminal-win-quickstart-terminal.png new file mode 100644 index 00000000..2d17cd08 Binary files /dev/null and b/docs/_includes/figures/terminal/docker-toolbox-terminal-win-quickstart-terminal.png differ diff --git a/docs/_includes/figures/terminal/docker-toolbox-terminal-win-quickstart-terminal.rst b/docs/_includes/figures/terminal/docker-toolbox-terminal-win-quickstart-terminal.rst new file mode 100644 index 00000000..9068af47 --- /dev/null +++ b/docs/_includes/figures/terminal/docker-toolbox-terminal-win-quickstart-terminal.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/terminal/docker-toolbox-terminal-win-quickstart-terminal.png + + Copyright docs.docker.com diff --git a/docs/_static/img/tutorials/xdebug_phpstorm_proxy.png b/docs/_includes/figures/xdebug/phpstorm-dbgp-proxy.png similarity index 100% rename from docs/_static/img/tutorials/xdebug_phpstorm_proxy.png rename to docs/_includes/figures/xdebug/phpstorm-dbgp-proxy.png diff --git a/docs/_includes/figures/xdebug/phpstorm-dbgp-proxy.rst b/docs/_includes/figures/xdebug/phpstorm-dbgp-proxy.rst new file mode 100644 index 00000000..037f2767 --- /dev/null +++ b/docs/_includes/figures/xdebug/phpstorm-dbgp-proxy.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/xdebug/phpstorm-dbgp-proxy.png + + PHPStorm settings: DBGp Proxy diff --git a/docs/_static/img/tutorials/xdebug_phpstorm_path_mapping.png b/docs/_includes/figures/xdebug/phpstorm-path-mapping.png similarity index 100% rename from docs/_static/img/tutorials/xdebug_phpstorm_path_mapping.png rename to docs/_includes/figures/xdebug/phpstorm-path-mapping.png diff --git a/docs/_includes/figures/xdebug/phpstorm-path-mapping.rst b/docs/_includes/figures/xdebug/phpstorm-path-mapping.rst new file mode 100644 index 00000000..1c02538c --- /dev/null +++ b/docs/_includes/figures/xdebug/phpstorm-path-mapping.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/xdebug/phpstorm-path-mapping.png + + PHPStorm settings: path mapping diff --git a/docs/_static/img/tutorials/xdebug_phpstorm_settings.png b/docs/_includes/figures/xdebug/phpstorm-settings.png similarity index 100% rename from docs/_static/img/tutorials/xdebug_phpstorm_settings.png rename to docs/_includes/figures/xdebug/phpstorm-settings.png diff --git a/docs/_includes/figures/xdebug/phpstorm-settings.rst b/docs/_includes/figures/xdebug/phpstorm-settings.rst new file mode 100644 index 00000000..19c0fc2e --- /dev/null +++ b/docs/_includes/figures/xdebug/phpstorm-settings.rst @@ -0,0 +1,3 @@ +.. figure:: /_includes/figures/xdebug/phpstorm-settings.png + + PHPStorm settings: Xdebug diff --git a/docs/_includes/html/defaults.rst b/docs/_includes/html/defaults.rst new file mode 100644 index 00000000..e4eba32f --- /dev/null +++ b/docs/_includes/html/defaults.rst @@ -0,0 +1,3 @@ +.. |br| raw:: html + +
diff --git a/docs/_includes/images/external.rst b/docs/_includes/images/external.rst new file mode 100644 index 00000000..62b117b8 --- /dev/null +++ b/docs/_includes/images/external.rst @@ -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/osx.png +.. |img_logo_win| image:: https://raw.githubusercontent.com/cytopia/icons/master/64x64/windows.png + +.. |img_banner| image:: /img/banner.png diff --git a/docs/_includes/links/apps.rst b/docs/_includes/links/apps.rst new file mode 100644 index 00000000..4bb06cd5 --- /dev/null +++ b/docs/_includes/links/apps.rst @@ -0,0 +1,12 @@ +.. |ext_lnk_app_android_dns_changer| raw:: html + + + DNS Changer + + +.. |ext_lnk_app_iphone_dns_override| raw:: html + + + DNS Override + + diff --git a/docs/_includes/links/blogs.rst b/docs/_includes/links/blogs.rst new file mode 100644 index 00000000..f708a97b --- /dev/null +++ b/docs/_includes/links/blogs.rst @@ -0,0 +1,23 @@ +.. |ext_lnk_blog_deliciousbrains| raw:: html + + + Using Devilbox For Local WordPress Development In Docker + + +.. |ext_lnk_blog_moritzkanzler| raw:: html + + + Devilbox: Lokaler Webserver mit Apache, PHP und MySQL im Docker Container + + +.. |ext_lnk_blog_joomla_pr_testing_platform| raw:: html + + + PR Testing Platform + + +.. |ext_lnk_blog_joomla_gsoc2017| raw:: html + + + Google Summer of Code 2017 + diff --git a/docs/_includes/links/dns.rst b/docs/_includes/links/dns.rst new file mode 100644 index 00000000..fc4652f8 --- /dev/null +++ b/docs/_includes/links/dns.rst @@ -0,0 +1,29 @@ +.. |ext_lnk_dns_archlinux_wiki_resolv_conf| raw:: html + + + Archlinux Wiki: resolv.conf + + +.. |ext_lnk_wikipedia_cname| raw:: html + + + CNAME + + +.. |ext_lnk_domain_dev| raw:: html + + + Google (ICANN) + + +.. |ext_lnk_domain_rfc_localhost| raw:: html + + + RFC Draft: localhost + + +.. |ext_lnk_domain_docker_rel_notes_localhost| raw:: html + + + Docker Release notes: 17.12.0-ce-mac46 + diff --git a/docs/_includes/links/docker-compose.rst b/docs/_includes/links/docker-compose.rst new file mode 100644 index 00000000..52b7a56e --- /dev/null +++ b/docs/_includes/links/docker-compose.rst @@ -0,0 +1,88 @@ +.. + ============================================================ + Commands + ============================================================ + +.. |ext_lnk_docker_compose_cmd_reference| raw:: html + + + Compose command-line reference overview + + +.. |ext_lnk_docker_compose_cmd_overview| raw:: html + + + overview + + +.. |ext_lnk_docker_compose_cmd_up| raw:: html + + + up + + +.. |ext_lnk_docker_compose_cmd_stop| raw:: html + + + stop + + +.. |ext_lnk_docker_compose_cmd_kill| raw:: html + + + kill + + +.. |ext_lnk_docker_compose_cmd_logs| raw:: html + + + logs + + +.. |ext_lnk_docker_compose_cmd_rm| raw:: html + + + rm + + +.. |ext_lnk_docker_compose_cmd_pull| raw:: html + + + pull + + +.. + ============================================================ + Install guides + ============================================================ + +.. |ext_lnk_docker_compose_install| raw:: html + + + Install Docker Compose + + +.. |ext_lnk_docker_compose_env_file| raw:: html + + + Declare default environment variables in file + + +.. |ext_lnk_docker_compose_env| raw:: html + + + .env + + +.. |ext_lnk_docker_compose_extra_hosts| raw:: html + + + Docker Compose: extra_hosts + + +.. |ext_lnk_docker_compose_extends| raw:: html + + + Docker Compose: Share Compose configurations between files and projects + + diff --git a/docs/_includes/links/docker-images.rst b/docs/_includes/links/docker-images.rst new file mode 100644 index 00000000..f71e2ac1 --- /dev/null +++ b/docs/_includes/links/docker-images.rst @@ -0,0 +1,35 @@ +.. |ext_lnk_docker_image_cockroach| raw:: html + + + Cockroachc DB + + +.. |ext_lnk_docker_image_grafana| raw:: html + + + Grafana + + +.. |ext_lnk_docker_image_postgres| raw:: html + + + PostgreSQL + + +.. |ext_lnk_docker_image_redis| raw:: html + + + Redis + + +.. |ext_lnk_docker_image_memcached| raw:: html + + + Memcached + + +.. |ext_lnk_docker_image_mongodb| raw:: html + + + MongoDB + diff --git a/docs/_includes/links/docker.rst b/docs/_includes/links/docker.rst new file mode 100644 index 00000000..7df46954 --- /dev/null +++ b/docs/_includes/links/docker.rst @@ -0,0 +1,117 @@ +.. + ============================================================ + General Guides + ============================================================ + +.. |ext_lnk_install_docker| raw:: html + + + Install Docker + + +.. |ext_link_docker_machine| raw:: html + + + Docker Machine + + +.. + ============================================================ + Docker for Linux + ============================================================ + +.. |ext_lnk_install_docker_centos| raw:: html + + + Get Docker CE for CentOS + + +.. |ext_lnk_install_docker_debian| raw:: html + + + Get Docker CE for Debian + + +.. |ext_lnk_install_docker_fedora| raw:: html + + + Get Docker CE for Fedora + + +.. |ext_lnk_install_docker_ubuntu| raw:: html + + + Get Docker CE for Ubuntu + + +.. |ext_lnk_install_docker_linux_post_steps| raw:: html + + + Post-installation steps for Linux + + + +.. + ============================================================ + Docker for Mac + ============================================================ + +.. |ext_lnk_install_docker_mac| raw:: html + + + Install Docker for Mac + + +.. |ext_lnk_install_docker_mac_get_started| raw:: html + + + Get started with Docker for Mac + + +.. |ext_lnk_install_docker_toolbox_mac| raw:: html + + + Install Docker Toolbox on MacOS + + +.. |ext_lnk_install_docker_toolbox_mac_native_vs_toolbox| raw:: html + + + Docker for Mac vs. Docker Toolbox + + +.. |ext_lnk_install_docker_toolbox_mac_shared_directory| raw:: html + + + Docker Toolbox on Mac: add shared directories + + + +.. + ============================================================ + Docker for Windows + ============================================================ + +.. |ext_lnk_install_docker_win| raw:: html + + + Install Docker for Windows + + +.. |ext_lnk_install_docker_win_get_started| raw:: html + + + Get started with Docker for Windows + + +.. |ext_lnk_install_docker_toolbox_win| raw:: html + + + Install Docker Toolbox on Windows + + +.. |ext_lnk_install_docker_toolbox_win_shared_directory| raw:: html + + + Docker Toolbox on Windows: add shared directories + diff --git a/docs/_includes/links/documentation.rst b/docs/_includes/links/documentation.rst new file mode 100644 index 00000000..b2edec7d --- /dev/null +++ b/docs/_includes/links/documentation.rst @@ -0,0 +1,23 @@ +.. |ext_lnk_doc_mysql_query_log| raw:: html + + + MySQL query log documentation + + +.. |ext_lnk_doc_bind_ttl| raw:: html + + + BIND TTL + + +.. |ext_lnk_doc_bind_soa| raw:: html + + + BIND SOA + + +.. |ext_lnk_doc_wiki_database_timezones| raw:: html + + + Wikipedia: List of database timezones + diff --git a/docs/_includes/links/examples.rst b/docs/_includes/links/examples.rst new file mode 100644 index 00000000..2d42e5c0 --- /dev/null +++ b/docs/_includes/links/examples.rst @@ -0,0 +1,83 @@ +.. |ext_lnk_example_cakephp_documentation| raw:: html + + + Official CakePHP Documentation + + +.. |ext_lnk_example_codeignitor_documentation| raw:: html + + + Official CodeIgniter Documentation + + +.. |ext_lnk_example_drupal_documentation| raw:: html + + + Official Drupal Documentation + + +.. |ext_lnk_example_joomla_documentation| raw:: html + + + Official Joomla Documentation + + +.. |ext_lnk_example_laravel_documentation| raw:: html + + + Official Laravel Documentation + + +.. |ext_lnk_example_phalcon_documentation| raw:: html + + + Official Phalcon Documentation + + +.. |ext_lnk_example_photon_cms| raw:: html + + + Official Photon CMS Documentation + + +.. |ext_lnk_example_shopware_documentation| raw:: html + + + Official Shopware Documentation + + +.. |ext_lnk_example_shopware_github| raw:: html + + + Shopware Github repository + + +.. |ext_lnk_example_symfony_documentation| raw:: html + + + Official Symfony Documentation + + +.. |ext_lnk_example_typo3_documentation| raw:: html + + + Official Typo3 Documentation + + +.. |ext_lnk_example_wordpress_documentation| raw:: html + + + Official Wordpress Documentation + + +.. |ext_lnk_example_yii_documentation| raw:: html + + + Official Yii Documentation + + +.. |ext_lnk_example_zend_documentation| raw:: html + + + Official Zend Documentation + diff --git a/docs/_includes/links/git.rst b/docs/_includes/links/git.rst new file mode 100644 index 00000000..d58cb3f9 --- /dev/null +++ b/docs/_includes/links/git.rst @@ -0,0 +1,5 @@ +.. |ext_lnk_download_git_win| raw:: html + + + Download Git for Windows + diff --git a/docs/_includes/links/prerequistes.rst b/docs/_includes/links/prerequistes.rst new file mode 100644 index 00000000..5a9910d6 --- /dev/null +++ b/docs/_includes/links/prerequistes.rst @@ -0,0 +1,35 @@ +.. |ext_lnk_prereq_docker_lin| raw:: html + + + Docker + + +.. |ext_lnk_prereq_docker_mac| raw:: html + + + Docker for Mac + + +.. |ext_lnk_prereq_docker_mac_tb| raw:: html + + + Docker Toolbox + + +.. |ext_lnk_prereq_docker_win| raw:: html + + + Docker for Windows + + +.. |ext_lnk_prereq_docker_win_tb| raw:: html + + + Docker Toolbox + + +.. |ext_lnk_prereq_docker_win_ee| raw:: html + + + Docker EE + diff --git a/docs/_includes/links/ssh.rst b/docs/_includes/links/ssh.rst new file mode 100644 index 00000000..5f818662 --- /dev/null +++ b/docs/_includes/links/ssh.rst @@ -0,0 +1,12 @@ +.. |ext_lnk_ssh_tunnelling_for_fun_and_profit| raw:: html + + + SSH tunnelling for fun and profie: Local vs Remote + + + +.. |ext_lnk_stackoverflow_ssh_into_docker_machine| raw:: html + + + Stackoverflow: SSH into Docker machine + diff --git a/docs/_includes/links/ssl.rst b/docs/_includes/links/ssl.rst new file mode 100644 index 00000000..a4ea3b63 --- /dev/null +++ b/docs/_includes/links/ssl.rst @@ -0,0 +1,23 @@ +.. |ext_lnk_ssl_wiki_hsts| raw:: html + + + HSTS header + + +.. |ext_lnk_ssl_blog_chrome_dev_hsts| raw:: html + + + Chrome & Firefox now force .dev domains to HTTPS via preloaded HSTS + + +.. |ext_lnk_ssl_certificate_authority| raw:: html + + + Certificate Authority + + +.. |ext_lnk_ssl_gfi_root_cert_guide| raw:: html + + + GFI Root Certificate guide + diff --git a/docs/_includes/links/tools.rst b/docs/_includes/links/tools.rst new file mode 100644 index 00000000..529752a3 --- /dev/null +++ b/docs/_includes/links/tools.rst @@ -0,0 +1,262 @@ +.. + ============================================================ + Command line tools + ============================================================ + +.. |ext_lnk_tool_awesome_ci| raw:: html + + + awesome-ci + + +.. |ext_lnk_tool_linuxbrew| raw:: html + + + Linux brew + + +.. |ext_lnk_tool_composer| raw:: html + + + Composer + + +.. |ext_lnk_tool_drush| raw:: html + + + Drush + + +.. |ext_lnk_tool_drupal_console| raw:: html + + + Drupal Console + + +.. |ext_lnk_tool_eslint| raw:: html + + + ESLint + + +.. |ext_lnk_tool_git| raw:: html + + + Git + + +.. |ext_lnk_tool_git_flow| raw:: html + + + Git flow + + +.. |ext_lnk_tool_gulp| raw:: html + + + Gulp + + +.. |ext_lnk_tool_grunt| raw:: html + + + Grunt + + +.. |ext_lnk_tool_jsonlint| raw:: html + + + JSON lint + + +.. |ext_lnk_tool_laravel| raw:: html + + + Laravel installer + + +.. |ext_lnk_tool_mdl| raw:: html + + + Markdown lint + + +.. |ext_lnk_tool_mdlint| raw:: html + + + MD linter + + +.. |ext_lnk_tool_mongodump| raw:: html + + + mongodump + + +.. |ext_lnk_tool_mongorestore| raw:: html + + + mongorestore + + +.. |ext_lnk_tool_mysqldump| raw:: html + + + mysqldump + + +.. |ext_lnk_tool_mysqldump_secure| raw:: html + + + mysqldump-secure + + +.. |ext_lnk_tool_node| raw:: html + + + Node + + +.. |ext_lnk_tool_npm| raw:: html + + + Node + + +.. |ext_lnk_tool_phalcon| raw:: html + + + Phalcon DevTools + + +.. |ext_lnk_tool_phpcs| raw:: html + + + PHP CodeSniffer + + +.. |ext_lnk_tool_phpcbf| raw:: html + + + PHP Code Beautifier and Fixer + + +.. |ext_lnk_tool_pg_dump| raw:: html + + + pg_dump + + +.. |ext_lnk_tool_pgsql_restore| raw:: html + + + pgsql + + +.. |ext_lnk_tool_photon| raw:: html + + + Photon CMS cli + + +.. |ext_lnk_tool_sass| raw:: html + + + Sass + + +.. |ext_lnk_tool_scss_lint| raw:: html + + + SCSS Lint + + +.. |ext_lnk_tool_ssh| raw:: html + + + OpenSSH + + +.. |ext_lnk_tool_symfony| raw:: html + + + Symfony installer + + +.. |ext_lnk_tool_tig| raw:: html + + + Text-mode Interface for Git + + +.. |ext_lnk_tool_webpack| raw:: html + + + Webpack + + +.. |ext_lnk_tool_wp| raw:: html + + + Wordpress CLI + + +.. |ext_lnk_tool_yamllint| raw:: html + + + Yamllint + + +.. |ext_lnk_tool_yarn| raw:: html + + + Yarn + + + +.. + ============================================================ + Web tools + ============================================================ + +.. |ext_lnk_tool_phpmyadmin| raw:: html + + + phpMyAdmin + + +.. |ext_lnk_tool_adminer| raw:: html + + + Adminer + + +.. |ext_lnk_tool_opcachegui| raw:: html + + + OpcacheGui + + + +.. + ============================================================ + Projects + ============================================================ + +.. |ext_lnk_project_vhost_gen| raw:: html + + + vhost-gen + + +.. |ext_lnk_project_watcherd| raw:: html + + + watcherd + + +.. |ext_lnk_project_watcherp| raw:: html + + + watcherp + diff --git a/docs/_includes/links/uid.rst b/docs/_includes/links/uid.rst new file mode 100644 index 00000000..27f798f0 --- /dev/null +++ b/docs/_includes/links/uid.rst @@ -0,0 +1,5 @@ +.. |ext_lnk_uid| raw:: html + + + Wikipedia: uid + diff --git a/docs/_includes/links/xdebug.rst b/docs/_includes/links/xdebug.rst new file mode 100644 index 00000000..c072665a --- /dev/null +++ b/docs/_includes/links/xdebug.rst @@ -0,0 +1,53 @@ +.. + ============================================================ + Xdebug configuration + ============================================================ + + +.. |ext_lnk_github_devilbox_xdebug_on_mac| raw:: html + + + Xdebug on MacOS + + +.. |ext_lnk_github_original_xdebug_on_mac| raw:: html + + + Xdebug on MacOS (original) + + +.. |ext_lnk_xdebug_settings| raw:: html + + + Xdebug: all settings + + +.. |ext_lnk_xdebug_remote_debugging| raw:: html + + + Xdebug: remote debugging + + + +.. + ============================================================ + Xdebug IDE/editor configuration + ============================================================ + +.. |ext_lnk_xdebug_ide_atom_php_debug| raw:: html + + + php-debug + + +.. |ext_lnk_xdebug_ide_sublime_xdebug_client| raw:: html + + + Xdebug client + + +.. |ext_lnk_xdebug_ide_vscode_php_debug| raw:: html + + + vscode-php-debug + diff --git a/docs/_static/css/custom.css b/docs/_static/css/devilbox.css similarity index 54% rename from docs/_static/css/custom.css rename to docs/_static/css/devilbox.css index 43fd5d5d..90933da0 100644 --- a/docs/_static/css/custom.css +++ b/docs/_static/css/devilbox.css @@ -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, diff --git a/docs/_static/img/devilbox-email-catch-all.png b/docs/_static/img/devilbox-email-catch-all.png deleted file mode 100644 index e8f1b430..00000000 Binary files a/docs/_static/img/devilbox-email-catch-all.png and /dev/null differ diff --git a/docs/advanced/add-custom-cname-records.rst b/docs/advanced/add-custom-cname-records.rst new file mode 100644 index 00000000..255001c7 --- /dev/null +++ b/docs/advanced/add-custom-cname-records.rst @@ -0,0 +1,44 @@ +.. include:: /_includes/all.rst + +.. _add_custom_cname_records: + +**************************** +Add custom CNAME DNS entries +**************************** + +You can add an infinite number of custom +|ext_lnk_wikipedia_cname| records that will be available in your +running Docker container. +If Auto-DNS is turned on, those records will be available on your host operating system as well. + +.. seealso:: :ref:`setup_auto_dns` + + +**Table of Contents** + +.. contents:: :local: + + +Why and what? +============= + +This might be useful if you have an IP address or hostname on your LAN or any other domain which +you want to expose to your container by a different CNAME of your choice. + +Think of it as setting your ``/etc/hosts``, but which will be distributed accross all hosts which +are using the Devilbox' bundled DNS server. + +How? +==== + +Adjust the :ref:`env_extra_hosts` variable inside ``.env`` to add as many CNAME's as you need. + +As an example, to create a CNAME ``mywebserver.com`` pointing to ``172.16.238.1``, change your +.env file as shown below: + +.. code-block:: bash + :caption: .env + + EXTRA_HOSTS=mywebserver.loc=172.16.238.1 + +.. seealso:: See :ref:`env_extra_hosts` for an in-depth explanation with multiple examples. diff --git a/docs/tutorials/add-your-own-docker-image.rst b/docs/advanced/add-your-own-docker-image.rst similarity index 97% rename from docs/tutorials/add-your-own-docker-image.rst rename to docs/advanced/add-your-own-docker-image.rst index be60aeea..8b01954e 100644 --- a/docs/tutorials/add-your-own-docker-image.rst +++ b/docs/advanced/add-your-own-docker-image.rst @@ -1,3 +1,5 @@ +.. include:: /_includes/all.rst + .. _add_your_own_docker_image: ************************* @@ -118,7 +120,7 @@ Two new services CockroachDB example ------------------- -Gather the requirements for the `Cockroach DB `_ +Gather the requirements for the |ext_lnk_docker_image_cockroach| Docker image: 1. Name: ``cockroach`` diff --git a/docs/advanced/connect-to-external-hosts.rst b/docs/advanced/connect-to-external-hosts.rst new file mode 100644 index 00000000..721b5755 --- /dev/null +++ b/docs/advanced/connect-to-external-hosts.rst @@ -0,0 +1,17 @@ +.. _connect_to_external_hosts: + +************************* +Connect to external hosts +************************* + + +Connecting from inside a Devilbox Docker container to any external host works out of the box. +The only thing you need is internet/network access and know its hostname or IP address. + +Each container has internet access, thus you can ``curl``, ``fetch``, connect to or download +any online resources from within the container. + + +.. seealso:: + * :ref:`connect_to_host_os` + * :ref:`connect_to_other_docker_container` diff --git a/docs/advanced/connect-to-host-os.rst b/docs/advanced/connect-to-host-os.rst new file mode 100644 index 00000000..318474ea --- /dev/null +++ b/docs/advanced/connect-to-host-os.rst @@ -0,0 +1,171 @@ +.. include:: /_includes/all.rst + +.. _connect_to_host_os: + +****************** +Connect to host OS +****************** + +This section explains how to connect from inside a Devilbox container to the host operating system. + + +**Table of Contents** + +.. contents:: :local: + + +Prerequisites +============= + +When you want to connect from inside a Docker container to a port on your host operating system, +ensure the host service is listening on all interfaces for simplicity. + +The following sections will give you the IP address and/or the CNAME where the host os can be +reached from within a container. + + +.. _connect_to_host_os_docker_on_linux: + +Docker on Linux +=============== + +If you run Docker on Linux the host IP is always ``172.16.238.1``, which is the default gateway +IP address within the Devilbox bridge network (see ``docker-compose.yml``). + +.. important:: Ensure services on the host listen on that IP address or on all interfaces. + +By default Docker on Linux does not have CNAME's of the host computer as for example with MacOS +or Windows, therefore two custom CNAME's have been added by the Devilbox in order to emulate the +same behaviour: + +* CNAME: ``docker.for.lin.host.internal`` +* CNAME: ``docker.for.lin.localhost`` + + +.. _connect_to_host_os_docker_for_mac: + +Docker for Mac +============== + +If you run Docker for Mac, an IP address is not necessary as it already provides a CNAME which will +always point to the IP address of your host operating system. Depending on the Docker version this +CNAME will differ: + +Docker 18.03.0-ce+ and Docker compose 1.20.1+ +--------------------------------------------- + +CNAME: ``host.docker.internal`` + +Docker 17.12.0-ce+ and Docker compose 1.18.0+ +--------------------------------------------- + +CNAME: ``docker.for.mac.host.internal`` + +Docker 17.06.0-ce+ and Docker compose 1.14.0+ +--------------------------------------------- + +CNAME: ``docker.for.mac.localhost`` + + +.. _connect_to_host_os_docker_for_win: + +Docker for Windows +================== + +If you run Docker for Windows, an IP address is not necessary as it already provides a CNAME which will +always point to the IP address of your host operating system. Depending on the Docker version this +CNAME will differ: + +.. important:: Ensure your firewall is not blocking Docker to host connections. + +Docker 18.03.0-ce+ and Docker compose 1.20.1+ +--------------------------------------------- + +* CNAME: ``docker.for.win.host.internal`` +* CNAME: ``host.docker.internal`` + + +Docker 17.06.0-ce+ and Docker compose 1.14.0+ +--------------------------------------------- + +CNAME: ``docker.for.win.host.localhost`` + + +Docker Toolbox +============== + +.. note:: This section applies for both, Docker Toolbox on MacOS and Docker Toolbox on Windows. + +Docker Toolbox behaves the same way as Docker on Linux, with one major difference. +The Devilbox IP address or the custom provided CNAMEs actually refer to the Docker Toolbox machine. + +In order to connect from inside the Docker container (which is inside the Docker Toolbox machine) +to your host os, you need to create: + +1. either a **local** port-forward on the **Docker Toolbox** machine (``ssh -L``) +2. or a **remote** port-forward on your **host os** (``ssh -R``) + +.. seealso:: |ext_lnk_ssh_tunnelling_for_fun_and_profit| + + +For both examples we assume the following: + +* MySQL database exists on your host os and listens on ``127.0.0.1`` on port ``3306`` +* Docker Toolbox IP address is ``192.168.99.100`` +* Host IP address where SSH is listening on ``172.16.0.1`` +* Host SSH username is ``user`` +* Devilbox Docker container wants to access MySQL on host os + + +Local port forward on Docker Toolbox +------------------------------------ + +.. important:: + For that to work, your host operating system requires an SSH server to be up and running. + ++----------------+----------------+--------------+--------------------+--------------+ +| Initiator | From host | From port | To host | To port | ++================+================+==============+====================+==============+ +| Docker Toolbox | ``127.0.0.1`` | ``3306`` | ``192.168.99.100`` | ``3306`` | ++----------------+----------------+--------------+--------------------+--------------+ + +.. code-block:: bash + + # From Docker Toolbox forward port 3306 (on host 172.16.0.1) to myself (192.168.99.100) + toolbox> ssh -L 3306:127.0.0.1:3306 user@172.16.0.1 + +.. seealso:: + * :ref:`howto_find_docker_toolbox_ip_address` + * :ref:`howto_ssh_into_docker_toolbox` + * :ref:`howto_ssh_port_forward_on_docker_toolbox_from_host` + +Remote port-forward on host os +------------------------------ + +.. important:: + For that to work, your host operating system requires an SSH client (``ssh`` binary). + ++----------------+----------------+--------------+--------------------+--------------+ +| Initiator | From host | From port | To host | To port | ++================+================+==============+====================+==============+ +| Host os | ``127.0.0.1`` | ``3306`` | ``192.168.99.100`` | ``3306`` | ++----------------+----------------+--------------+--------------------+--------------+ + +.. code-block:: bash + + # From host os forward port 3306 (from loopback 127.0.0.1) to Docker Toolbox (192.168.99.100) + host> ssh -R 3306:127.0.0.1:3306 docker@192.168.99.100 + +.. seealso:: + * :ref:`howto_find_docker_toolbox_ip_address` + * :ref:`howto_ssh_into_docker_toolbox` + * :ref:`howto_ssh_port_forward_on_host_to_docker_toolbox` + +Post steps +---------- + +With either of the above you have achieved the exact behaviour as +:ref:`connect_to_host_os_docker_on_linux` for one single service/port (MySQL port 3306). + +You must now follow the steps for :ref:`connect_to_host_os_docker_on_linux` to actually connect +to that service from within the Devilbox Docker container. diff --git a/docs/advanced/connect-to-other-docker-container.rst b/docs/advanced/connect-to-other-docker-container.rst new file mode 100644 index 00000000..26442d6d --- /dev/null +++ b/docs/advanced/connect-to-other-docker-container.rst @@ -0,0 +1,77 @@ +.. include:: /_includes/all.rst + +.. _connect_to_other_docker_container: + +********************************* +Connect to other Docker container +********************************* + +Other Docker container can either be accessed by connecting back to the host os or by adding its +image directly to the Devilbox stack. + + +**Table of Contents** + +.. contents:: :local: + + +Any Docker container on host os +=============================== + +1. To connect to any other Docker container on your host os from within the Devilbox Docker + container, you first need to make sure, you are able to connect to your host os from within the + Devilbox Docker container. + + .. seealso:: :ref:`connect_to_host_os` + +2. Once you are able to connect to the host os, start any other Docker container and make its + port that you want to access available to your host os by specifying ``-p``. + An example with e.g. an external |ext_lnk_docker_image_grafana| container + might look like this: + + .. code-block:: bash + + host> docker run -d --name=grafana -p 3000:3000 grafana/grafana + + You can then connect to your host os on port ``3000`` from within the Devilbox Docker container + and be able to use it. + + +Add Docker container to Devilbox network +======================================== + +The Devilbox defines its own bridge network, usually called ``devilbox_app_net``. + +.. note:: + The name may vary depending on the name of the Devilbox directory. It assembles itself by + ``_app_net``. + +1. Start the Devilbox +2. Start your container of choice + + .. code-block:: bash + + host> docker run -d --name mycontainer + +3. Attach your container to the Devilbox network + + .. code-block:: bash + + host> docker network connect devilbox_app_net mycontainer + +Once you have done that, ``mycontainer`` is then part of the internal Devilbox network +and is able to resolve Devilbox container by its name and vice-versa. + +4. Connect from Devilbox PHP container to ``mycontainer`` + + From inside the PHP container, you can then refer to your container by its hostname + ``mycontainer`` + + +Add Docker container to Devilbox stack +====================================== + +Alternatively you can also add any Docker container to the Devilbox network by adding an image +it to the Devilbox stack directly. + +.. seealso:: :ref:`add_your_own_docker_image` diff --git a/docs/advanced/customize-php-globally.rst b/docs/advanced/customize-php-globally.rst new file mode 100644 index 00000000..71c86feb --- /dev/null +++ b/docs/advanced/customize-php-globally.rst @@ -0,0 +1,84 @@ +.. _customize_php_globally: + + +********************** +Customize PHP globally +********************** + +PHP settings can be applied globally to all projects, but are bound to a specific PHP version. +This means every PHP version can have its own profile of customized settings. + +.. note:: + By default, all PHP container use roughly the same settings. This might only differ if some + options or modules do not exist in a specific container. + +**Table of Contents** + +.. contents:: :local: + + +Configure PHP settings globally +=============================== + +PHP settings can either be applied in its ``php.ini`` configuration file or through the +PHP-FPM configuration itself via ``php_value`` and ``php_flag``. + +Settings in ``php.ini`` are also picked up by the PHP command line tool, whereas ``php_value`` +and ``php_flag`` settings are only valid for requests over the webserver. + +This means you can set different values, when executing command line tasks and when the +application is run through the browser. + + +Settings via php.ini +-------------------- + +To configure PHP globally via php.ini follow the provided link: + +.. seealso:: :ref:`php_ini` + +Settings via php-fpm.conf +------------------------- + +To configure PHP globally via PHP-FPM follow the provided link: + +.. seealso:: :ref:`php_fpm_conf` + + +Configure non-overwritable settings globally +============================================ + +Settings defined via ``php.ini``, ``php_value`` and ``php_flag`` are applied globally, however +they can still be overwritten by any project via the PHP function ``ini_set()``. + +If you want to create PHP settings and force them, so no application can accidentally or on purpose +overwrite them, you need to use ``php_admin_value`` and ``php_admin_flag``. + +.. important:: + Keep in mind that those settings are not picked up by the command line execution of PHP, + but only through the browser. + + +To configure PHP globally and non-overwritable via PHP-FPM follow the provided link: + +.. seealso:: :ref:`php_fpm_conf` + + +Configure loaded PHP modules +============================ + +The ``.env`` file offers the option to specify what PHP modules to enable or disable specifically. + +.. seealso:: :ref:`enable_disable_php_modules` + + +Configure PHP-FPM service +========================= + +You can also configure the PHP-FPM service itself. Settings can be applied for the core service +as well as for the pool. This is useful if you need to adjust performance settings such as number +of running child processes, file- and memory limits, timeouts and many more. + +Be sure to read up on the PHP-FPM documentation to understand what you are doing. + +.. seealso:: :ref:`php_fpm_conf` diff --git a/docs/advanced/customize-webserver-globally.rst b/docs/advanced/customize-webserver-globally.rst new file mode 100644 index 00000000..2e08f43a --- /dev/null +++ b/docs/advanced/customize-webserver-globally.rst @@ -0,0 +1,57 @@ +***************************** +Customize web server globally +***************************** + +Web server settings can be applied globally, which will affect the web server behaviour itself, +but not the vhost configuration. Configuration can be done for each version separetely, which means +each web server can have its own profile of customized settings. + +.. + In order to customize the vhosts, have a look at the following links: + * :ref:`customize_specific_virtual_host` + * :ref:`customize_all_virtual_hosts_globally` + +.. seealso:: + In order to customize a specific vhosts, have a look at the following link: + + * :ref:`customize_specific_virtual_host` + +**Table of Contents** + +.. contents:: :local: + + +Configure Apache +================ + +All settings that usually go into the main ``httpd.conf`` or ``apache2.conf`` configuration file +can be overwritten or customized separately for Apache 2.2 and Apache 2.4. + +.. seealso:: :ref:`apache_conf` + +Configure Nginx +=============== + + +All settings that usually go into the main ``nginx.conf`` configuration file +can be overwritten or customized separately for Nginx stable and Nginx mainline. + +.. seealso:: :ref:`nginx_conf` + + +Devilbox specific settings +========================== + +There are certain other settings that are directly managed by the Devilbox's ``.env`` file in order +to make other containers aware of those settings. + +.. important:: Try to avoid to overwrite the ``.env`` settings via web server configuration files. + +Use the following ``.env`` variables to customize this behaviour globally. + +.. seealso:: + * :ref:`env_tld_suffix` + * :ref:`env_host_port_httpd` + * :ref:`env_host_port_httpd_ssl` + * :ref:`env_httpd_template_dir` + * :ref:`env_httpd_docroot_dir` diff --git a/docs/tutorials/overwrite-existing-docker-image.rst b/docs/advanced/overwrite-existing-docker-image.rst similarity index 100% rename from docs/tutorials/overwrite-existing-docker-image.rst rename to docs/advanced/overwrite-existing-docker-image.rst diff --git a/docs/conf.py b/docs/conf.py index 03bf4333..972a54d3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -21,14 +21,14 @@ from recommonmark.parser import CommonMarkParser # -- Project information ----------------------------------------------------- -project = u'devilbox' +project = u'Devilbox' copyright = u'2018, cytopia' author = u'cytopia' # The short X.Y version -version = u'' +version = u'1.0' # The full version, including alpha/beta/rc tags -release = u'' +release = u'1.0' # -- General configuration --------------------------------------------------- @@ -75,11 +75,33 @@ 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 ------------------------------------------------- + +# http://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder +linkcheck_ignore = [ + r'http(s)?://localhost(/)?.*', + r'http(s)?://127\.0\.0\.1(/)?.*', + r'http(s)?://.+\.loc$' +] +linkcheck_retries = 5 +linkcheck_timeout = 60 +linkcheck_anchors = True + # -- Options for HTML output ------------------------------------------------- @@ -111,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, @@ -137,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 --------------------------------------------- @@ -170,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' + ), ] @@ -180,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 + ) ] @@ -191,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' + ), ] diff --git a/docs/configuration-files/apache-conf.rst b/docs/configuration-files/apache-conf.rst index f509d5c2..3019b7a7 100644 --- a/docs/configuration-files/apache-conf.rst +++ b/docs/configuration-files/apache-conf.rst @@ -13,8 +13,11 @@ 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_specific_virtual_host` +.. + * :ref:`customize_all_virtual_hosts_globally` **Table of Contents** diff --git a/docs/configuration-files/bashrc-sh.rst b/docs/configuration-files/bashrc-sh.rst index f16b7b9b..e90e080f 100644 --- a/docs/configuration-files/bashrc-sh.rst +++ b/docs/configuration-files/bashrc-sh.rst @@ -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** diff --git a/docs/configuration-files/docker-compose-override-yml.rst b/docs/configuration-files/docker-compose-override-yml.rst index dd961b8a..57b1112b 100644 --- a/docs/configuration-files/docker-compose-override-yml.rst +++ b/docs/configuration-files/docker-compose-override-yml.rst @@ -1,3 +1,5 @@ +.. include:: /_includes/all.rst + .. _docker_compose_override_yml: *************************** @@ -14,7 +16,7 @@ By default, this file does not exist and you must create it. You can either copy .. contents:: :local: -.. seealso:: Official Docker documentation: `Share Compose configurations between files and projects `_ +.. seealso:: |ext_lnk_docker_compose_extends| Create docker-compose.override.yml diff --git a/docs/configuration-files/env-file.rst b/docs/configuration-files/env-file.rst index 63d98f7a..c8da9c90 100644 --- a/docs/configuration-files/env-file.rst +++ b/docs/configuration-files/env-file.rst @@ -1,3 +1,5 @@ +.. include:: /_includes/all.rst + .. _env_file: ********* @@ -5,10 +7,13 @@ ********* 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:: - what is the `.env `_ file? +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 |ext_lnk_docker_compose_env| file? .. note:: Use your browsers search function to quickly find the desired variable name. @@ -228,11 +233,10 @@ this project visible to everyone in your corporate LAN. .. warning:: Do not use ``dev`` as a domain suffix (I know, it's tempting). It has been registered by - `Google `_ and they advertise the - `HSTS header `_ + |ext_lnk_domain_dev| and they advertise the |ext_lnk_ssl_wiki_hsts| which makes your browser redirect every http request to https. - **See also:** `This blog post `_ + **See also:** |ext_lnk_ssl_blog_chrome_dev_hsts| .. warning:: Do not use ``localhost`` as a domain suffix. @@ -240,9 +244,7 @@ this project visible to everyone in your corporate LAN. should be redirected to the systems loopback interface. Docker has already released a commit preventing the use of ``localhost`` on MacOS. - **See also:** `RFC Draft `_ - and - `Docker Release notes `_ + **See also:** |ext_lnk_domain_rfc_localhost| and |ext_lnk_domain_docker_rel_notes_localhost| .. _env_extra_hosts: @@ -309,9 +311,9 @@ A few examples for adding extra hosts: .. seealso:: - This resembles the feature of `Docker Compose: extra_hosts `_ to add external links. + This resembles the feature of |ext_lnk_docker_compose_extra_hosts| to add external links. -.. seealso:: :ref:`communicating_with_external_hosts` +.. seealso:: :ref:`connect_to_external_hosts` .. _env_new_uid: @@ -394,7 +396,7 @@ This is especially useful to keep PHP and database timezones in sync. | ``TIMEZONE`` | valid timezone | ``Europe/Berlin`` | +-----------------------+----------------+-------------------+ -Have a look at Wikipedia to get a list of valid timezones: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones +Have a look at Wikipedia to get a list of valid timezones: |ext_lnk_doc_wiki_database_timezones| .. note:: It is always a good practice not to assume a specific timezone anyway and store all values @@ -449,7 +451,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: @@ -641,7 +643,7 @@ All values are already available in the ``.env`` file and just need to be commen .. note:: This is the official PostgreSQL server which might already have other tags available, check their official website for even more versions. - https://hub.docker.com/_/postgres/ + |ext_lnk_docker_image_postgres| .. _env_redis_server: @@ -673,7 +675,7 @@ All values are already available in the ``.env`` file and just need to be commen .. note:: This is the official Redis server which might already have other tags available, check their official website for even more versions. - https://hub.docker.com/_/redis/ + |ext_lnk_docker_image_redis| .. _env_memcd_server: @@ -724,7 +726,7 @@ All values are already available in the ``.env`` file and just need to be commen .. note:: This is the official Memcached server which might already have other tags available, check their official website for even more versions. - https://hub.docker.com/_/memcached/ + |ext_lnk_docker_image_memcached| .. _env_mongo_server: @@ -757,7 +759,7 @@ All values are already available in the ``.env`` file and just need to be commen .. note:: This is the official MongoDB server which might already have other tags available, check their official website for even more versions. - https://hub.docker.com/_/mongo/ + |ext_lnk_docker_image_mongodb| Docker host mounts @@ -989,7 +991,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` @@ -998,6 +1000,8 @@ Open the command prompt and type the following: system by other services. +.. _env_host_port_httpd: + HOST_PORT_HTTPD --------------- @@ -1010,6 +1014,7 @@ else if 80 is already in use on your host operating system. | ``HOST_PORT_HTTPD`` | ``1`` - ``65535`` | ``80`` | +----------------------+-------------------+------------------+ +.. _env_host_port_httpd_ssl: HOST_PORT_HTTPD_SSL ------------------- @@ -1109,7 +1114,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 @@ -1118,6 +1123,8 @@ Container settings PHP --- +.. _env_file_php_modules_enable: + PHP_MODULES_ENABLE ^^^^^^^^^^^^^^^^^^ @@ -1141,6 +1148,8 @@ Example: # Enable ionCube PHP_MODULES_ENABLE=ioncube +.. _env_file_php_modules_disable: + PHP_MODULES_DISABLE ^^^^^^^^^^^^^^^^^^^ @@ -1196,12 +1205,14 @@ 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 ---------- +.. _env_httpd_docroot_dir: + HTTPD_DOCROOT_DIR ^^^^^^^^^^^^^^^^^ @@ -1282,7 +1293,6 @@ As you can see, the web server is still able to server the files from the ``htdo this time however, ``htdocs`` itself is a symlink pointing to a much deeper and nested location inside an actual framework directory. - .. _env_httpd_template_dir: HTTPD_TEMPLATE_DIR @@ -1367,18 +1377,18 @@ servers virtual host to anything from adding rewrite rules, overwriting director changing the server name or adding locations to other assets. .. seealso:: - The whole process is based on a project called `vhost-gen `_. + The whole process is based on a project called |ext_lnk_project_vhost_gen|. A virtual host generator for Apache 2.2, Apache 2.4 and any Nginx version. .. 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`. - **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` + read up more on: + * :ref:`customize_specific_virtual_host` + * :ref:`example_add_sub_domains` +.. + * :ref:`customize_all_virtual_hosts_globally` MySQL ----- @@ -1418,7 +1428,7 @@ As the Devilbox is intended to be used for development, this feature is turned o **MySQL documentation:** "The general query log is a general record of what mysqld is doing. The server writes information to this log when clients connect or disconnect, and it logs each SQL statement received from clients. The general query log can be very useful when you suspect an error in a client and want to know exactly what the client sent to mysqld." - -- https://dev.mysql.com/doc/refman/5.7/en/query-log.html + -- |ext_lnk_doc_mysql_query_log| PostgreSQL ---------- @@ -1537,8 +1547,8 @@ This variable controls the DNS TTL in seconds. If empty or removed it will fallb .. seealso:: - * `BIND TTL `_ - * `BIND SOA `_ + * |ext_lnk_doc_bind_ttl| + * |ext_lnk_doc_bind_soa| BIND_REFRESH_TIME ^^^^^^^^^^^^^^^^^ @@ -1551,7 +1561,7 @@ This variable controls the DNS Refresh time in seconds. If empty or removed it w | ``BIND_REFRESH_TIME`` | integer | empty | +--------------------------+----------------------+---------------------+ -.. seealso:: `BIND SOA `_ +.. seealso:: |ext_lnk_doc_bind_soa| BIND_RETRY_TIME ^^^^^^^^^^^^^^^ @@ -1564,7 +1574,7 @@ This variable controls the DNS Retry time in seconds. If empty or removed it wil | ``BIND_RETRY_TIME`` | integer | empty | +--------------------------+----------------------+---------------------+ -.. seealso:: `BIND SOA `_ +.. seealso:: |ext_lnk_doc_bind_soa| BIND_EXPIRY_TIME ^^^^^^^^^^^^^^^^ @@ -1577,7 +1587,7 @@ This variable controls the DNS Expiry time in seconds. If empty or removed it wi | ``BIND_EXPIRY_TIME`` | integer | empty | +--------------------------+----------------------+---------------------+ -.. seealso:: `BIND SOA `_ +.. seealso:: |ext_lnk_doc_bind_soa| BIND_MAX_CACHE_TIME ^^^^^^^^^^^^^^^^^^^ @@ -1590,13 +1600,4 @@ This variable controls the DNS Max Cache time in seconds. If empty or removed it | ``BIND_MAX_CACHE_TIME`` | integer | empty | +--------------------------+----------------------+---------------------+ -.. seealso:: `BIND SOA `_ - - - - - - -.. |br| raw:: html - -
+.. seealso:: |ext_lnk_doc_bind_soa| diff --git a/docs/configuration-files/my-cnf.rst b/docs/configuration-files/my-cnf.rst index 43664e98..614cb82f 100644 --- a/docs/configuration-files/my-cnf.rst +++ b/docs/configuration-files/my-cnf.rst @@ -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. diff --git a/docs/configuration-files/nginx-conf.rst b/docs/configuration-files/nginx-conf.rst index 4708f853..6f63fb2c 100644 --- a/docs/configuration-files/nginx-conf.rst +++ b/docs/configuration-files/nginx-conf.rst @@ -13,8 +13,11 @@ 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_specific_virtual_host` +.. + * :ref:`customize_all_virtual_hosts_globally` **Table of Contents** diff --git a/docs/configuration-files/php-fpm-conf.rst b/docs/configuration-files/php-fpm-conf.rst index b4cf7e47..1b192f97 100644 --- a/docs/configuration-files/php-fpm-conf.rst +++ b/docs/configuration-files/php-fpm-conf.rst @@ -93,7 +93,7 @@ Change child process on pool ``www`` for PHP 5.6 The following examples shows you how to change the `pm `_, -`pm.max_children `_, +`pm.max_children `_, `pm.start_servers `_, `pm.min_spare_servers `_ and diff --git a/docs/configuration-global/auto-dns.rst b/docs/configuration-global/auto-dns.rst deleted file mode 100644 index d1ceb048..00000000 --- a/docs/configuration-global/auto-dns.rst +++ /dev/null @@ -1,202 +0,0 @@ -.. _global_configuration_auto_dns: - -******** -Auto-DNS -******** - -If you don't want to add DNS records manually for every project, you can also use the bundled -DNS server and use it's DNS catch-all feature to have all DNS records automatically available. - -.. important:: - By default, the DNS server is set to listen on ``1053`` to avoid port collisions during startup. - You need to change it to ``53`` in ``.env`` via :ref:`env_host_port_bind`. - - -**Table of Contents** - -.. contents:: :local: - - -Native Docker -============= - -The webserver as well as the DNS server must be available on ``127.0.0.1`` or on all interfaces -on ``0.0.0.0``. Additionally the DNS server port must be set to ``53`` (it is not by default). - -* Ensure :ref:`env_local_listen_addr` is set accordingly -* Ensure :ref:`env_host_port_bind` is set accordingly -* No other DNS resolver should listen on ``127.0.0.1:53`` - - -Prerequisites -------------- - -First ensure that :ref:`env_local_listen_addr` is either empty or listening on ``127.0.0.1``. - -.. code-block:: bash - :caption: .env - :emphasize-lines: 3 - - host> cd path/to/devilbox - host> vi .env - LOCAL_LISTEN_ADDR= - -Then you need to ensure that :ref:`env_host_port_bind` is set to ``53``. - -.. code-block:: bash - :caption: .env - :emphasize-lines: 3 - - host> cd path/to/devilbox - host> vi .env - HOST_PORT_BIND=53 - -Before starting up the Devilbox, ensure that port ``53`` is not already used on ``127.0.0.1``. - -.. code-block:: bash - :emphasize-lines: 2 - - host> netstat -an | grep -E 'LISTEN\s*$' - tcp 0 0 127.0.0.1:53 0.0.0.0:* LISTEN - tcp 0 0 127.0.0.1:43477 0.0.0.0:* LISTEN - tcp 0 0 127.0.0.1:50267 0.0.0.0:* LISTEN - -If you see port ``53`` already being used as in the above example, ensure to stop any -DNS resolver, otherwise it does not work. - -The output should look like this (It is only important that there is no ``:53``. - -.. code-block:: bash - - host> netstat -an | grep -E 'LISTEN\s*$' - tcp 0 0 127.0.0.1:43477 0.0.0.0:* LISTEN - tcp 0 0 127.0.0.1:50267 0.0.0.0:* LISTEN - - -Linux ------ - -On Linux the DNS settings can be controlled by various different methods. Two of them are via -Network Manager and systemd-resolved. Choose on of the methods depending on your local setup. - -Network Manager -^^^^^^^^^^^^^^^ - -If the prerequisites are met, you can edit ``/etc/dhcp/dhclient.conf`` with root or sudo privileges -and add an instruction, which tells your local DHCP client that whenever any of your DNS servers -are changed, you always want to have an additional entry, which is the one from the Devilbox. - -Add the following line to to the very beginning to ``/etc/dhcp/dhclient.conf``: - -.. code-block:: bash - :caption: /etc/dhcp/dhclient.conf - - prepend domain-name-servers 127.0.0.1; - -When you do that for the first time, you need to restart the ``network-manager`` service. - -.. code-block:: bash - - # Via service command - host> sudo service network-manager restart - - # Or the systemd way - host> sudo systemctl restart network-manager - -This will make sure that whenever your /etc/resolv.conf is deployed, you will have ``127.0.0.1`` -as the first entry and also make use of any other DNS server which are deployed via the LAN's DHCP server. - -If the Devilbox DNS server is not running, it does not affect the name resolution, because you will -still have other entries in ``/etc/resolv.conf``. - - -systemd-resolved -^^^^^^^^^^^^^^^^ - -In case you are using systemd-resolved instead of NetworkManager, add the following line to -the very beginning to ``/etc/resolv.conf.head``: - -.. code-block:: bash - :caption: /etc/resolv.conf.head - - nameserver 127.0.0.1 - -Prevent NetworkManager from modifying ``/etc/resolv.conf`` and leave everything to -systemd-resolved by adding the following line under the ``[main]`` section of -``/etc/NetworkManager/NetworkManager.conf`` - -.. code-block:: bash - :caption: /etc/NetworkManager/NetworkManager.conf - - dns=none - -As a last step you will have to restart ``systemd-resolved``. - -.. code-block:: bash - - host> sudo systemctl stop systemd-resolved - host> sudo systemctl start systemd-resolved - -Once done, you can verify if the new DNS settings are effective: - -.. code-block:: bash - - host> systemd-resolve --status - -.. seealso:: `Archlinux Wiki: resolv.conf `_ - - -MacOS ------ - -Modifying ``/etc/resolv.conf`` does not work on MacOS, you need to make changes in your -System Preferences: - -1. Open System Preferences -2. Go to Network -3. Select your connected interface -4. Click on ``DNS`` tab -5. Add new DNS server by clicking the ``+`` sign -6. Add ``127.0.0.1`` - -.. image:: /_static/img/auto-dns-macos-dns.png - - -Windows -------- - -On Windows, you need to change your active network adapter. See the following screenshots -for how to do it. - -.. image:: /_static/img/auto-dns-windows-dns-01.jpg -.. image:: /_static/img/auto-dns-windows-dns-02.jpg -.. image:: /_static/img/auto-dns-windows-dns-03.jpg - -In the last screenshot, you will have to add ``127.0.0.1`` as your ``Preferred DNS server``. - - -Docker Toolbox -============== - -.. seealso:: :ref:`docker_toolbox` - -MacOS ------ - -* :ref:`env_local_listen_addr` must be empty in order to listen on all interfaces -* :ref:`env_host_port_bind` must be set to ``53`` -* Port ``80`` from the Docker Toolbox virtual machine must be port-forwarded to ``127.0.0.1:80`` on your host os -* Port ``53`` from the Docker Toolbox virtual machine must be port-forwarded to ``127.0.0.1:53`` on your host os - -.. todo:: This section needs further proof and information. - - -Windows --------- - -* :ref:`env_local_listen_addr` must be empty in order to listen on all interfaces -* :ref:`env_host_port_bind` must be set to ``53`` -* Port ``80`` from the Docker Toolbox virtual machine must be port-forwarded to ``127.0.0.1:80`` on your host os -* Port ``53`` from the Docker Toolbox virtual machine must be port-forwarded to ``127.0.0.1:53`` on your host os - -.. todo:: This section needs further proof and information. diff --git a/docs/configuration-project/dns-records.rst b/docs/configuration-project/dns-records.rst deleted file mode 100644 index a315d422..00000000 --- a/docs/configuration-project/dns-records.rst +++ /dev/null @@ -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 ```` 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, let’s 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 diff --git a/docs/corporate-usage/shared-devilbox-server-in-lan.rst b/docs/corporate-usage/shared-devilbox-server-in-lan.rst new file mode 100644 index 00000000..05a28c2a --- /dev/null +++ b/docs/corporate-usage/shared-devilbox-server-in-lan.rst @@ -0,0 +1,212 @@ +.. _shared_devilbox_server_in_lan: + +***************************** +Shared Devilbox server in LAN +***************************** + +Devilbox as a shared **development**, **staging** or **CI** server is setup in a similar way as +you would do locally. The only three important parts to take care of are: + +1. Project access to deploy/update code +2. Handle DNS entries +3. Share Devilbox CA + + +**Table of Contents** + +.. contents:: :local: + + +Prerequisites +============= + +This walk-through will use the following example values: + ++--------------------+------------------+-----------+---------------------------+ +| LAN / Network | Devilbox server | TLD_SUFFX | LOCAL_LISTEN_ADDR | ++====================+==================+===========+===========================+ +| ``192.168.0.0/24`` | ``192.168.0.12`` | ``loc`` | ``192.168.0.12`` or empty | ++--------------------+------------------+-----------+---------------------------+ + +.. seealso:: + * :ref:`env_tld_suffix` + * :ref:`env_local_listen_addr` + + +Project access +============== + +SSH +--- + +Enable and start an SSH server and give access to whatever system or user requires it. +This can be done directly on the host system or via various other Docker container that offer +ssh server. + +Copy via sftp +^^^^^^^^^^^^^ +If your SSH server is setup, users can use their sftp clients to deploy code updates. This however +is not encouraged and you should use git or any other version control system. + +Manually git pull/checkout +^^^^^^^^^^^^^^^^^^^^^^^^^^ +When using git, users can directly ssh into the shared Devilbox server and ``git pull`` or +``git checkout `` on their projects. + +Automated git pull/checkout +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In case you are using a staging or CI server, use Jenkins jobs or other automation tools +(e.g. Ansible) to auto-deploy via SSH. + +Samba +----- + +For a shared development server, you could also setup Samba network shares for each projects +and have users deploy their code via Samba. + + +Handle DNS records +================== + +There are multiple ways of having DNS records available accross the LAN. + +Before you read on, have a quick look on the decision Matrix to find the best method for your +use-case. + ++---------------------+------------------+--------------------------------------------------------------------------------------------------------+ +| Method | Sub-method | Outcome | ++=====================+==================+========================================================================================================+ +| Real domain | | All network devices will have Auto DNS | ++---------------------+------------------+--------------------------------------------------------------------------------------------------------+ +| Own DNS server | | All network devices will have Auto DNS | ++---------------------+------------------+--------------------------------------------------------------------------------------------------------+ +| Devilbox DNS server | Manual | Every network device must configure its DNS settings | +| +------------------+--------------------------------------------------------------------------------------------------------+ +| | DHCP distributed | All network devices will have Auto DNS | ++---------------------+------------------+--------------------------------------------------------------------------------------------------------+ +| Hosts entry | | Every network device must manually set hosts entries |br| for each project. (Does not work for phones) | ++---------------------+------------------+--------------------------------------------------------------------------------------------------------+ + +.. |br| raw:: html + +
+ +.. important:: + When using a shared Devilbox server and another Devilbox setup on your local computer, + ensure that you are using different :ref:`env_tld_suffix` in order to not confuse + DNS records. + +Use a real domain +----------------- + +*(This will allow all devices on the network to have Auto-DNS)* + +If you own a real domain, such as ``my-company.com``, you can create a wildcard DNS record for +a subdomain, such as ``*.dev.my-company.com`` which must point to ``192.168.0.12.``. +This should be done in your hosting provider's DNS configuration pannel. + +You must then also change the ``TLD_SUFFIX`` to that subdomain. + +.. code-block:: bash + :caption: .env + + TLD_SUFFIX=dev.my-company.com + +Handle DNS records in your own DNS server +----------------------------------------- + +*(This will allow all devices on the network to have Auto-DNS)* + +If your LAN already provides its own customizable DNS server, you can setup a new wildcard DNS +zone for ``*.loc`` which points to ``192.168.0.12``. + +Run a second instance of the Devilbox DNS server +------------------------------------------------ + +If the above two methods for automated DNS records don't apply to you, you will need to run +a second stand-alone Docker container of the Devilbox DNS server. + +Run this container permantently on the shared Devilbox server with the following command: + +.. code-block:: bash + + host> docker run -d \ + --restart unless-stopped \ + -p 53:53/tcp \ + -p 53:53/udp \ + -e WILDCARD_DNS='loc=192.168.0.12' \ + -t cytopia/bind + +.. seealso:: https://github.com/cytopia/docker-bind + +Now there are two ways to consume the DNS records on your local machine: + +1. Manual +2. DHCP distributed + +Manual DNS settings +^^^^^^^^^^^^^^^^^^^ +*(Each device on the network needs to manually set the DNS server)* + +When using this approach, you have to manually add the DNS server (IP: ``192.168.0.12``) to your +host operating system. + +.. important:: + Keep in mind that you have to do this for every machine within the network which wants to access + the shared Devilbox server. + +.. seealso:: + * :ref:`howto_add_custom_dns_server_on_linux` + * :ref:`howto_add_custom_dns_server_on_mac` + * :ref:`howto_add_custom_dns_server_on_win` + * :ref:`howto_add_custom_dns_server_on_android` + * :ref:`howto_add_custom_dns_server_on_iphone` + +DHCP distributed +^^^^^^^^^^^^^^^^ +*(This will allow all devices on the network to have Auto-DNS)* + +This is the automated and more pain-free approach, as all devices within the network will be able +to access projects on the shared Devilbox server. + + +Self-managed DHCP server +"""""""""""""""""""""""" +If you run your own DHCP server within a network, you probably know how to add other DNS servers. +The only thing you should keep in mind is, that the Devilbox DNS server should be the first in +the list. + +DSL box / LAN or WIFI router +"""""""""""""""""""""""""""" +Most `SOHO `_ networks probably use some +vendor router which has a web interface. Generally speaking, you need to find the DNS/DHCP settings +in its web interface and add the Devilbox DNS server as the first in the list (``192.168.0.12``). + +.. seealso:: + * `Change DNS server in Fritzbox `_ + + +Add hosts entries for every project +----------------------------------- + +*(Each device on the network needs to manually set the hosts entries for every single projcet)* + +As you also do for the Devilbox locally when not using Auto-DNS, you can do as well for remote +computer. Just edit your local hosts file and add one DNS entry for every project on the shared +Devilbox server. + +Keep in mind that this time you will have to use ``192.168.0.12`` instead of ``127.0.0.1``. + +.. seealso:: + * :ref:`howto_add_project_hosts_entry_on_linux` + * :ref:`howto_add_project_hosts_entry_on_mac` + * :ref:`howto_add_project_hosts_entry_on_win` + + +Share Devilbox CA +================= + +The last step to also have valid HTTPS connections on your shared Devilbox server is to copy +the CA onto your local machine and import it into your browser or system. + +.. seealso:: :ref:`setup_valid_https` diff --git a/docs/corporate-usage/use-external-databases.rst b/docs/corporate-usage/use-external-databases.rst new file mode 100644 index 00000000..89501e61 --- /dev/null +++ b/docs/corporate-usage/use-external-databases.rst @@ -0,0 +1,90 @@ +.. include:: /_includes/all.rst + +.. _use_external_databases: + +********************** +Use external databases +********************** + +**Table of Contents** + +.. contents:: :local: + + +Why +=== + +Some people or companies might have concerns with dockerized databases and rather rely on good old +host-based database setups. +There could already be a database cluster in your network or you rather want to use AWS RDS or +other cloud-based solutions. + +There are many reasons for having an external database. + + + +Database on host os +=================== + +.. note:: + If the local database is listening on an IP address that is reachable over your current LAN, + you can directly skip to: :ref:`use_external_databases_database_on_network` + +In order to use an already existing database that is running on the host os, you need to +make sure the following is met: + +1. Be able to connect to the host os from inside the container + + .. seealso:: :ref:`connect_to_host_os` + +2. Configure your application to use the IP/CNAME of the host os + +3. When starting the Devilbox, explicitly specify the service to use and exclude the databases: + + .. code-block:: bash + + # Explicitly specify services to start (otherwise all will start) + # Omit the database + host> docker-compose up -d php httpd bind redis + + .. seealso:: :ref:`start_the_devilbox` + + +.. _use_external_databases_database_on_network: + +Database on network +=================== + +In order to use an already existing database that is running on the network, you need to +make sure the following is met: + +1. Configure your application to use the IP/CNAME of the database host + +2. When starting the Devilbox, explicitly specify the service to use and exclude the databases: + + .. code-block:: bash + + # Explicitly specify services to start (otherwise all will start) + # Omit the database + host> docker-compose up -d php httpd bind redis + + .. seealso:: :ref:`start_the_devilbox` + + +Database on internet +==================== + +In order to use an already existing database that is running on the network, you need to +make sure the following is met: + +1. Configure your application to use the IP/CNAME of the database host + +2. When starting the Devilbox, explicitly specify the service to use and exclude the databases: + + .. code-block:: bash + + # Explicitly specify services to start (otherwise all will start) + # Omit the database + host> docker-compose up -d php httpd bind redis + + .. seealso:: :ref:`start_the_devilbox` diff --git a/docs/devilbox-purpose.rst b/docs/devilbox-purpose.rst new file mode 100644 index 00000000..bcc56540 --- /dev/null +++ b/docs/devilbox-purpose.rst @@ -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. + diff --git a/docs/examples/setup-cakephp.rst b/docs/examples/setup-cakephp.rst index b0116068..2ed7b0d5 100644 --- a/docs/examples/setup-cakephp.rst +++ b/docs/examples/setup-cakephp.rst @@ -1,3 +1,5 @@ +.. include:: /_includes/all.rst + .. _example_setup_cakephp: ************* @@ -6,7 +8,7 @@ Setup CakePHP This example will use ``composer`` to install CakePHP from within the PHP container. -.. seealso:: `Official CakePHP Documentation `_ +.. seealso:: |ext_lnk_example_cakephp_documentation| **Table of Contents** @@ -51,7 +53,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 +126,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 +136,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_hosts_entry_on_mac` + * :ref:`howto_add_project_hosts_entry_on_win` + * :ref:`setup_auto_dns` 8. Open your browser diff --git a/docs/examples/setup-codeigniter.rst b/docs/examples/setup-codeigniter.rst index ff2fd800..9a1d44fe 100644 --- a/docs/examples/setup-codeigniter.rst +++ b/docs/examples/setup-codeigniter.rst @@ -1,11 +1,12 @@ +.. include:: /_includes/all.rst + .. _example_setup_codeigniter: ***************** Setup CodeIgniter ***************** - -.. seealso:: `Official CodeIgniter Documentation `_ +.. seealso:: |ext_lnk_example_codeignitor_documentation| **Table of Contents** @@ -50,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 @@ -129,7 +130,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 +140,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_hosts_entry_on_mac` + * :ref:`howto_add_project_hosts_entry_on_win` + * :ref:`setup_auto_dns` 8. Open your browser diff --git a/docs/examples/setup-drupal.rst b/docs/examples/setup-drupal.rst index 52e191a0..a943f469 100644 --- a/docs/examples/setup-drupal.rst +++ b/docs/examples/setup-drupal.rst @@ -1,3 +1,5 @@ +.. include:: /_includes/all.rst + .. _example_setup_drupal: ************ @@ -6,7 +8,7 @@ Setup Drupal This example will use ``drush`` to install Drupal from within the PHP container. -.. seealso:: `Official Drupal Documentation `_ +.. seealso:: |ext_lnk_example_drupal_documentation| **Table of Contents** @@ -49,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 @@ -80,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): @@ -90,8 +92,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_hosts_entry_on_mac` + * :ref:`howto_add_project_hosts_entry_on_win` + * :ref:`setup_auto_dns` 6. Open your browser diff --git a/docs/examples/setup-joomla.rst b/docs/examples/setup-joomla.rst index cf111fe6..a84a2155 100644 --- a/docs/examples/setup-joomla.rst +++ b/docs/examples/setup-joomla.rst @@ -1,3 +1,5 @@ +.. include:: /_includes/all.rst + .. _example_setup_joomla: ************ @@ -6,7 +8,7 @@ Setup Joomla This example will install Joomla from within the PHP container. -.. seealso:: `Official Joomla Documentation `_ +.. seealso:: |ext_lnk_example_joomla_documentation| **Table of Contents** @@ -49,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 @@ -82,7 +84,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 +94,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_hosts_entry_on_mac` + * :ref:`howto_add_project_hosts_entry_on_win` + * :ref:`setup_auto_dns` 6. Open your browser diff --git a/docs/examples/setup-laravel.rst b/docs/examples/setup-laravel.rst index a8d97658..d404e15a 100644 --- a/docs/examples/setup-laravel.rst +++ b/docs/examples/setup-laravel.rst @@ -1,3 +1,5 @@ +.. include:: /_includes/all.rst + .. _example_setup_laravel: ************* @@ -6,7 +8,7 @@ Setup Laravel This example will use ``laravel`` to install Laravel from within the PHP container. -.. seealso:: `Official Laravel Documentation `_ +.. seealso:: |ext_lnk_example_laravel_documentation| **Table of Contents** @@ -49,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 @@ -80,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): @@ -90,8 +92,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_hosts_entry_on_mac` + * :ref:`howto_add_project_hosts_entry_on_win` + * :ref:`setup_auto_dns` 6. Open your browser diff --git a/docs/examples/setup-other-frameworks.rst b/docs/examples/setup-other-frameworks.rst index 3b6650f4..17ceef68 100644 --- a/docs/examples/setup-other-frameworks.rst +++ b/docs/examples/setup-other-frameworks.rst @@ -9,3 +9,5 @@ and the list is in no way complete. The Devilbox itself is a normal development stack and is capable of running *any* framework, CMS or custom written PHP software. + +If you wish to see more install guides, open up an issue at Github: https://github.com/cytopia/devilbox/issues diff --git a/docs/examples/setup-phalcon.rst b/docs/examples/setup-phalcon.rst index e86c999b..ec86662a 100644 --- a/docs/examples/setup-phalcon.rst +++ b/docs/examples/setup-phalcon.rst @@ -1,3 +1,5 @@ +.. include:: /_includes/all.rst + .. _example_setup_phalcon: ************* @@ -6,7 +8,7 @@ Setup Phalcon This example will use ``phalcon`` to install Phalcon from within the PHP container. -.. seealso:: `Official Phalcon Documentation `_ +.. seealso:: |ext_lnk_example_phalcon_documentation| **Table of Contents** @@ -49,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 @@ -80,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): @@ -90,8 +92,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_hosts_entry_on_mac` + * :ref:`howto_add_project_hosts_entry_on_win` + * :ref:`setup_auto_dns` 6. Open your browser diff --git a/docs/examples/setup-photon-cms.rst b/docs/examples/setup-photon-cms.rst index 350098a0..0fae2c12 100644 --- a/docs/examples/setup-photon-cms.rst +++ b/docs/examples/setup-photon-cms.rst @@ -1,3 +1,5 @@ +.. include:: /_includes/all.rst + .. _example_setup_photon_cms: **************** @@ -6,7 +8,7 @@ Setup Photon CMS This example will use ``photon`` cli to install Photon CMS from within the PHP container. -.. seealso:: `Official Photon CMS Documentation `_ +.. seealso:: |ext_lnk_example_photon_cms| **Table of Contents** @@ -51,7 +53,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 +92,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 +102,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_hosts_entry_on_mac` + * :ref:`howto_add_project_hosts_entry_on_win` + * :ref:`setup_auto_dns` 6. Open your browser diff --git a/docs/examples/setup-shopware.rst b/docs/examples/setup-shopware.rst new file mode 100644 index 00000000..21d5eecf --- /dev/null +++ b/docs/examples/setup-shopware.rst @@ -0,0 +1,133 @@ +.. include:: /_includes/all.rst + +.. _example_setup_shopware: + +************** +Setup Shopware +************** + +This example will use ``git`` to install Shopware from within the PHP container. + +.. seealso:: + * |ext_lnk_example_shopware_documentation| + * |ext_lnk_example_shopware_github| + + +**Table of Contents** + +.. contents:: :local: + + +Overview +======== + +The following configuration will be used: + ++--------------+--------------------------+-------------+------------+-----------------------+ +| Project name | VirtualHost directory | Database | TLD_SUFFIX | Project URL | ++==============+==========================+=============+============+=======================+ +| my-sw | /shared/httpd/my-sw | my_sw | loc | http://my-sw.loc | ++--------------+--------------------------+-------------+------------+-----------------------+ + + +Walk through +============ + +It will be ready in seven simple steps: + +1. Enter the PHP container +2. Create a new VirtualHost directory +3. Download Shopware via ``git`` +4. Symlink webroot directory +5. Add MySQL database +6. Setup DNS record +7. Follow installation steps in http://my-sw.loc in your browser + + +.. seealso:: :ref:`available_tools` + + +1. Enter the PHP container +-------------------------- + +.. code-block:: bash + + host> ./shell.sh + +.. seealso:: :ref:`work_inside_the_php_container` + + +2. Create new vhost directory +----------------------------- + +.. code-block:: bash + + devilbox@php-7.0.20 in /shared/httpd $ mkdir my-sw + + +3. Download Shopware +-------------------- + +.. code-block:: bash + + devilbox@php-7.0.20 in /shared/httpd $ cd my-sw + devilbox@php-7.0.20 in /shared/httpd/my-sw $ git clone https://github.com/shopware/shopware + + +4. Symlink webroot +------------------ + +.. code-block:: bash + + devilbox@php-7.0.20 in /shared/httpd/my-sw $ ln -s shopware/ htdocs + + +5. Add MySQL Database +--------------------- + +.. code-block:: bash + + devilbox@php-7.0.20 in /shared/httpd/my-sw $ mysql -u root -h 127.0.0.1 -p -e 'CREATE DATABASE my_sw;' + + +6. DNS record +------------- + +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): + +.. code-block:: bash + :caption: /etc/hosts + + 127.0.0.1 my-sw.loc + +.. seealso:: + + * :ref:`howto_add_project_hosts_entry_on_mac` + * :ref:`howto_add_project_hosts_entry_on_win` + * :ref:`setup_auto_dns` + + +7. Follow install steps in your browser +--------------------------------------- + +All set now, you can visit http://my-sw.loc in your browser and follow the installation steps as +described in the |ext_lnk_example_shopware_documentation|: + +.. important:: + When setting up database connection use the following values: + + * Database server: ``127.0.0.1`` + * Database user: ``root`` (if you don't have a dedicated user already) + * Database pass: by default the root password is empty + * Database name: ``my_sw`` + + +Encountered problems +==================== + +By the time of writing (2018-07-07) Shopware had loading issues with the combination of ``PHP 5.6`` +and ``Apache 2.4``. Use any other combination. + +.. seealso:: https://github.com/cytopia/devilbox/issues/300 diff --git a/docs/examples/setup-symfony.rst b/docs/examples/setup-symfony.rst index 231f2f9d..ead3dc1e 100644 --- a/docs/examples/setup-symfony.rst +++ b/docs/examples/setup-symfony.rst @@ -1,3 +1,5 @@ +.. include:: /_includes/all.rst + .. _example_setup_symfony: ************* @@ -6,7 +8,7 @@ Setup Symfony This example will use ``symfony`` to install Symfony from within the PHP container. -.. seealso:: `Official Symfony Documentation `_ +.. seealso:: |ext_lnk_example_symfony_documentation| **Table of Contents** @@ -50,7 +52,7 @@ It will be ready in seven 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 +92,7 @@ It will be ready in seven simple steps: 6. 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 +102,10 @@ following line to your host operating systems ``/etc/hosts`` file 127.0.0.1 my-symfony.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_hosts_entry_on_mac` + * :ref:`howto_add_project_hosts_entry_on_win` + * :ref:`setup_auto_dns` 7. Open your browser diff --git a/docs/examples/setup-typo3.rst b/docs/examples/setup-typo3.rst new file mode 100644 index 00000000..a171a1da --- /dev/null +++ b/docs/examples/setup-typo3.rst @@ -0,0 +1,143 @@ +.. include:: /_includes/all.rst + +.. _example_setup_typo3: + +*********** +Setup Typo3 +*********** + +This example will use ``composer`` to install Typo3 from within the PHP container. + +.. seealso:: |ext_lnk_example_typo3_documentation| + + +**Table of Contents** + +.. contents:: :local: + + +Overview +======== + +The following configuration will be used: + ++--------------+--------------------------+-------------+------------+-----------------------+ +| Project name | VirtualHost directory | Database | TLD_SUFFIX | Project URL | ++==============+==========================+=============+============+=======================+ +| my-typo | /shared/httpd/my-typo | my_typo | loc | http://my-typo.loc | ++--------------+--------------------------+-------------+------------+-----------------------+ + + +Walk through +============ + +It will be ready in eight simple steps: + +1. Enter the PHP container +2. Create a new VirtualHost directory +3. Install Typo3 via ``composer`` +4. Symlink webroot directory +5. Setup DNS record +6. Create ``FIRST_INSTALL`` file +7. Open your browser +8. Step through guided web installation + + +.. seealso:: :ref:`available_tools` + + +1. Enter the PHP container +-------------------------- + +.. code-block:: bash + + host> ./shell.sh + +.. seealso:: :ref:`work_inside_the_php_container` + + +2. Create new vhost directory +----------------------------- + +.. code-block:: bash + + devilbox@php-7.0.20 in /shared/httpd $ mkdir my-typo + + +3. Install Typo3 +---------------- + +.. code-block:: bash + + devilbox@php-7.0.20 in /shared/httpd $ cd my-typo + devilbox@php-7.0.20 in /shared/httpd/my-typo $ composer create-project typo3/cms-base-distribution typo3 + + +4. Symlink webroot +------------------ + +.. code-block:: bash + + devilbox@php-7.0.20 in /shared/httpd/my-typo $ ln -s typo3/public htdocs + + +5. DNS record +------------- + +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): + +.. code-block:: bash + :caption: /etc/hosts + + 127.0.0.1 my-typo.loc + +.. seealso:: + + * :ref:`howto_add_project_hosts_entry_on_mac` + * :ref:`howto_add_project_hosts_entry_on_win` + * :ref:`setup_auto_dns` + + +6. Create ``FIRST_INSTALL`` file +-------------------------------- + +To continue installing via the guided web install, you need to create a file called +``FIRST_INSTALL`` in the document root. + +.. code-block:: bash + + devilbox@php-7.0.20 in /shared/httpd/my-typo $ touch htdocs/FIRST_INSTALL + + +7. Open your browser +-------------------- + +Open your browser at http://my-typo.loc. + + +8. Step through guided web installation +--------------------------------------- + +1. Select database + + * Connection: Manually configured MySWQL TCP/IP connection + * Username: root + * Password + * Host: 127.0.0.1 + * Port: 3306 + +2. Select database + + * Create a new database: ``typo3`` + +3. Create Administrative User / Specify Site Name + + * Username: admin + * Password: choose a secure password + * Site name: My Typo + +4. Installation complete + + * Create empty starting page diff --git a/docs/examples/setup-wordpress.rst b/docs/examples/setup-wordpress.rst index d2ed9a39..9eb32506 100644 --- a/docs/examples/setup-wordpress.rst +++ b/docs/examples/setup-wordpress.rst @@ -1,3 +1,5 @@ +.. include:: /_includes/all.rst + .. _example_setup_wordpress: *************** @@ -6,7 +8,7 @@ Setup Wordpress This example will use ``git`` to install Wordpress from within the PHP container. -.. seealso:: `Official Wordpress Documentation `_ +.. seealso:: |ext_lnk_example_wordpress_documentation| **Table of Contents** @@ -49,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 @@ -80,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): @@ -90,8 +92,10 @@ following line to your host operating systems ``/etc/hosts`` file 127.0.0.1 my-wp.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_hosts_entry_on_mac` + * :ref:`howto_add_project_hosts_entry_on_win` + * :ref:`setup_auto_dns` 6. Open your browser diff --git a/docs/examples/setup-yii.rst b/docs/examples/setup-yii.rst index 13267ee7..22917b13 100644 --- a/docs/examples/setup-yii.rst +++ b/docs/examples/setup-yii.rst @@ -1,3 +1,5 @@ +.. include:: /_includes/all.rst + .. _example_setup_yii: ********* @@ -6,7 +8,7 @@ Setup Yii This example will use ``composer`` to install Yii from within the PHP container. -.. seealso:: `Official Yii Documentation `_ +.. seealso:: |ext_lnk_example_yii_documentation| **Table of Contents** @@ -49,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 @@ -80,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): @@ -90,8 +92,10 @@ following line to your host operating systems ``/etc/hosts`` file 127.0.0.1 my-yii.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_hosts_entry_on_mac` + * :ref:`howto_add_project_hosts_entry_on_win` + * :ref:`setup_auto_dns` 6. Open your browser diff --git a/docs/examples/setup-zend.rst b/docs/examples/setup-zend.rst index 90d40fcb..016b189e 100644 --- a/docs/examples/setup-zend.rst +++ b/docs/examples/setup-zend.rst @@ -1,3 +1,5 @@ +.. include:: /_includes/all.rst + .. _example_setup_zend: ********** @@ -6,7 +8,7 @@ Setup Zend This example will use ``composer`` to install Zend from within the PHP container. -.. seealso:: `Official Zend Documentation `_ +.. seealso:: |ext_lnk_example_zend_documentation| **Table of Contents** @@ -49,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 @@ -80,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): @@ -90,8 +92,10 @@ following line to your host operating systems ``/etc/hosts`` file 127.0.0.1 my-zend.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_hosts_entry_on_mac` + * :ref:`howto_add_project_hosts_entry_on_win` + * :ref:`setup_auto_dns` 6. Open your browser diff --git a/docs/about/features.rst b/docs/features.rst similarity index 94% rename from docs/about/features.rst rename to docs/features.rst index c1f5bc3b..b3b49cc7 100644 --- a/docs/about/features.rst +++ b/docs/features.rst @@ -1,3 +1,5 @@ +.. include:: /_includes/all.rst + .. _features: ******** @@ -92,7 +94,7 @@ each Apache..., each Nginx... you get the idea. Project specific configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Even down to projects, the Devilbox allows for full customization when it comes to virtual host -settings via `vhost-gen `_. +settings via |ext_lnk_project_vhost_gen|. Intranet @@ -105,10 +107,8 @@ port exposures, hostnames and any errors including how they can be resolved. Third-party tools ^^^^^^^^^^^^^^^^^ -Mandatory web projects are also shipped: -`phpMyAdmin `_, -`Adminer `_ and -`OpcacheGui `_ as well as a web GUI to view all sent emails. +Mandatory web projects are also shipped: |ext_lnk_tool_phpmyadmin|, |ext_lnk_tool_adminer| and +|ext_lnk_tool_opcachegui| as well as a web GUI to view all sent emails. Dockerized diff --git a/docs/getting-started/change-container-versions.rst b/docs/getting-started/change-container-versions.rst new file mode 100644 index 00000000..edce608e --- /dev/null +++ b/docs/getting-started/change-container-versions.rst @@ -0,0 +1,241 @@ +************************* +Change container versions +************************* + +One of the core concepts of the Devilbox is to easily change between different versions of a +specific service. + + +**Table of Contents** + +.. contents:: :local: + + +Implications +============ + +Configuration changes +--------------------- + +Be aware that every version has its own configuration files in the ``cfg/`` directory. +If you switch to a different version, you might end up with a different custom configuration. +This however only applies, if you have already customized the configuration for your current +service. + +.. seealso:: + + * :ref:`php_ini` + * :ref:`php_fpm_conf` + * :ref:`apache_conf` + * :ref:`nginx_conf` + * :ref:`my_cnf` + +Data changes +------------ + +You also have to be aware that all database services (e.g.: MySQL, PostgreSQL, MongoDB, etc) use +a per version data directory. If you change the database version you might find that you have an +empty database when starting another version. + +This is simply a pre-caution to prevent newer versions from upgrading the database files and +accidentally making them incompatible for older versions. + +If you want to take your data along, do a backup before switching the version and then re-import +after the switch: + +.. seealso:: + + * :ref:`backup_and_restore_mysql` + * :ref:`backup_and_restore_pgsql` + * :ref:`backup_and_restore_mongo` + + +Examples +======== + +Change PHP version +------------------ + +Stop the Devilbox +^^^^^^^^^^^^^^^^^ + +Shut down the Devilbox in case it is still running: + +.. code-block:: bash + + # Navigate to the Devilbox directory + host> cd path/to/devilbox + + # Stop all container + host> docker-compose stop + +Edit the ``.env`` file +^^^^^^^^^^^^^^^^^^^^^^ + +Open the ``.env`` file with your favourite editor and navigate to the ``PHP_SERVER`` section. +It will look something like this: + +.. code-block:: bash + :caption: .env + :emphasize-lines: 6 + + #PHP_SERVER=5.3 + #PHP_SERVER=5.4 + #PHP_SERVER=5.5 + #PHP_SERVER=5.6 + #PHP_SERVER=7.0 + PHP_SERVER=7.1 + #PHP_SERVER=7.2 + #PHP_SERVER=7.3 + +As you can see, all available values are already there, but commented. Only one is uncommented. +In this example it is ``7.1``, which is the PHP version that will be started, once the Devilbox +starts. + +To change this, simply uncomment your version of choice and save this file. Do not forget to comment +(disable) any other version. + +In order to enable PHP 5.5, you would change the ``.env`` file like this: + +.. code-block:: bash + :caption: .env + :emphasize-lines: 3 + + #PHP_SERVER=5.3 + #PHP_SERVER=5.4 + PHP_SERVER=5.5 + #PHP_SERVER=5.6 + #PHP_SERVER=7.0 + #PHP_SERVER=7.1 + #PHP_SERVER=7.2 + #PHP_SERVER=7.3 + +Start the Devilbox +^^^^^^^^^^^^^^^^^^ + +Now save the file and you can start the Devilbox again. + +.. code-block:: bash + + # Navigate to the Devilbox directory + host> cd path/to/devilbox + + # Stop all container + host> docker-compose up php httpd bind + +.. seealso:: :ref:`start_the_devilbox` + + +Change web server version +------------------------- + +Stop the Devilbox +^^^^^^^^^^^^^^^^^ + +Shut down the Devilbox in case it is still running: + +.. code-block:: bash + + # Navigate to the Devilbox directory + host> cd path/to/devilbox + + # Stop all container + host> docker-compose stop + +Edit the ``.env`` file +^^^^^^^^^^^^^^^^^^^^^^ + +Open the ``.env`` file with your favourite editor and navigate to the ``HTTPD_SERVER`` section. +It will look something like this: + +.. code-block:: bash + :caption: .env + :emphasize-lines: 3 + + #HTTPD_SERVER=apache-2.2 + #HTTPD_SERVER=apache-2.4 + HTTPD_SERVER=nginx-stable + #HTTPD_SERVER=nginx-mainline + +As you can see, all available values are already there, but commented. Only one is uncommented. +In this example it is ``nginx-stable``, which is the web server version that will be started, +once the Devilbox starts. + +To change this, simply uncomment your version of choice and save this file. Do not forget to comment +(disable) any other version. + +In order to enable Apache 2.2, you would change the ``.env`` file like this: + +.. code-block:: bash + :caption: .env + :emphasize-lines: 1 + + HTTPD_SERVER=apache-2.2 + #HTTPD_SERVER=apache-2.4 + #HTTPD_SERVER=nginx-stable + #HTTPD_SERVER=nginx-mainline + +Start the Devilbox +^^^^^^^^^^^^^^^^^^ + +Now save the file and you can start the Devilbox again. + +.. code-block:: bash + + # Navigate to the Devilbox directory + host> cd path/to/devilbox + + # Stop all container + host> docker-compose up php httpd bind + +.. seealso:: :ref:`start_the_devilbox` + + +Change whatever version +----------------------- + +When you have read how to change the PHP or web server version, it should be fairly simple to +change any service version. It behaves in the exact same way. + +The variable names of all available services with changable versions are in the following format: +``_SERVER``. Just look through the :ref:`env_file`. + +.. seealso:: + The following variables control service versions: + :ref:`env_php_server`, :ref:`env_httpd_server`, + :ref:`env_mysql_server`, :ref:`env_pgsql_server`, :ref:`env_redis_server`, + :ref:`env_memcd_server`, :ref:`env_mongo_server` + + +Gotchas +======= + +If two versions are uncommented at the same time, always the last one takes precedence. + +Consider this ``.env`` file: + +.. code-block:: bash + :caption: .env + :emphasize-lines: 3,5 + + #PHP_SERVER=5.3 + #PHP_SERVER=5.4 + PHP_SERVER=5.5 + #PHP_SERVER=5.6 + PHP_SERVER=7.0 + #PHP_SERVER=7.1 + #PHP_SERVER=7.2 + #PHP_SERVER=7.3 + +Both, PHP 5.5 and PHP 7.0 are uncommented, however, when you start the Devilbox, it will use +PHP 7.0 as this value overwrites any previous ones. + + +Checklist +========= + +1. Stop the Devilbox +2. Uncomment version of choice in ``.env`` +3. Start the Devilbox + +.. seealso:: :ref:`troubleshooting` diff --git a/docs/getting-started/create-your-first-project.rst b/docs/getting-started/create-your-first-project.rst index ae81f363..2cd74a32 100644 --- a/docs/getting-started/create-your-first-project.rst +++ b/docs/getting-started/create-your-first-project.rst @@ -21,11 +21,14 @@ Create your first project Step 1: visit Intranet vhost page ================================= -Before starting, have a look at the vhost page at http://localhost/vhosts.php +Before starting, have a look at the vhost page at http://localhost/vhosts.php or +http://127.0.0.1/vhosts.php + +.. seealso:: :ref:`howto_find_docker_toolbox_ip_address` It should look like the screenshot below and will actually already provide the information needed to create a new project. -.. image:: /_static/img/devilbox-vhosts-empty.png +.. include:: /_includes/figures/devilbox/devilbox-intranet-vhosts-empty.rst Step 2: create a project directory @@ -50,7 +53,7 @@ In your Devilbox git directory, navigate to ``./data/www`` and create a new dire Visit the vhost page again and see what has changed: http://localhost/vhosts.php -.. image:: /_static/img/devilbox-vhosts-directory.png +.. include:: /_includes/figures/devilbox/devilbox-intranet-vhosts-missing-htdocs.rst **So what has happened?** @@ -78,16 +81,17 @@ Navigate to your newly created project directory and create a directory named `h Vist the vhost page again and see what has changed: http://localhost/vhosts.php -.. image:: /_static/img/devilbox-vhosts-dns.png +.. include:: /_includes/figures/devilbox/devilbox-intranet-vhosts-missing-dns.rst **So what has happened?** -By having created the docroot directory, the web server is now able to serve your files. However it has noticed, that you have no way yet, to actually visit your project url, as no DNS record for it exists yet. +By having created the docroot directory, the web server is now able to serve your files. However +it has noticed, that you have no way yet, to actually visit your project url, as no DNS record for +it exists yet. -The intranet already gives you the exact string that you can simply copy into your ``/etc/hosts`` file on your host operating system to solve this issue. - -.. important:: - This will only work on **native Docker** for Linux or MacOS. Read up on the next section to also find out how to do that on **Docker Toolbox** and Windows. +The intranet already gives you the exact string that you can simply copy into your ``/etc/hosts`` +(or ``C:\Windows\System32\drivers\etc`` for Windows) file on your host operating system to solve +this issue. .. _getting_started_create_your_first_project_dns_entry: @@ -100,11 +104,8 @@ Step 4: create a DNS entry DNS entries to your host computer, but is outside the scope of this *getting started tutorial*. -Add DNS for Linux and MacOS (native Docker) -------------------------------------------- - -On Linux and MacOS (when using the native Docker), this step is fairly simple. The intranet provides -you the exact string you need to paste into your ``/etc/hosts`` file on your host operating system. +When using native Docker, the Devilbox intranet will provide you the exact string you need to paste +into your ``/etc/hosts`` (or ``C:\Windows\System32\drivers\etc`` for Windows). .. code-block:: bash @@ -114,53 +115,15 @@ you the exact string you need to paste into your ``/etc/hosts`` file on your hos 127.0.0.1 project-1.loc -Add DNS for Windows (native Docker) ------------------------------------ +.. seealso:: -On Windows (when using the native Docker), you can also copy paste the command provided by the intranet, -however the destination file is different. You have to add this string into: ``C:\Windows\System32\drivers\etc``. + * :ref:`howto_add_project_hosts_entry_on_mac` + * :ref:`howto_add_project_hosts_entry_on_win` -Open ``C:\Windows\System32\drivers\etc`` with admistrative privileges and add the following entry - -.. code-block:: bash - - 127.0.0.1 project-1.loc - -Add DNS for 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, let's assume the virtual machine is running on ``192.16.0.1``, then the DNS record you will -have to add instead on your host operating system is: - -**Docker Toolbox on MacOS** - -.. code-block:: bash - - host> sudo vi /etc/hosts - - 192.16.0.1 project-1.loc - -**Docker Toolbox on Windows** - -Open ``C:\Windows\System32\drivers\etc`` with admistrative privileges and add the following entry - -.. code-block:: bash - - 192.16.0.1 project-1.loc - -Back to intranet ----------------- Vist the vhost page again and see what has changed: http://localhost/vhosts.php -.. image:: /_static/img/devilbox-vhosts-finished.png +.. include:: /_includes/figures/devilbox/devilbox-intranet-vhosts-working.rst **So what has happened?** @@ -168,13 +131,13 @@ By having created the DNS record, the Devilbox intranet is aware that everything gives you a link to your new project. -Step 5: Visit your project +Step 5: visit your project ========================== On the intranet, click on your project link. This will open your project in a new Browser tab or visit http://project-1.loc -.. image:: /_static/img/devilbox-project-no-files.png +.. include:: /_includes/figures/devilbox/devilbox-project-missing-index.rst **So what has happened?** @@ -183,8 +146,8 @@ Everything is setup now, however the webserver is trying to find a ``index.php`` So all is left for you to do is to add your HTML or PHP files. -Step 6: Create a hello world -============================ +Step 6: create a hello world file +================================= Navigate to your docroot directory within your project and create a ``index.php`` file with some output. @@ -207,7 +170,7 @@ Alternatively create an ``index.php`` file in ``data/www/project-1/htdocs`` with Visit your project url again and see what has changed: http://project-1.loc -.. image:: /_static/img/devilbox-project-hello-world.png +.. include:: /_includes/figures/devilbox/devilbox-project-hello-world.rst Checklist @@ -217,3 +180,36 @@ Checklist 2. Docroot directory is created 3. DNS entry is added to the host operating system 4. PHP files are added to your docroot directory + +.. seealso:: :ref:`troubleshooting` + + +Further examples +================ + +If you already want to know how to setup specific frameworks on the Devilbox, jump directly to +their articles: + +.. seealso:: + + **Well tested frameworks on the Devilbox** + + * :ref:`example_setup_cakephp` + * :ref:`example_setup_codeigniter` + * :ref:`example_setup_drupal` + * :ref:`example_setup_joomla` + * :ref:`example_setup_laravel` + * :ref:`example_setup_phalcon` + * :ref:`example_setup_photon_cms` + * :ref:`example_setup_shopware` + * :ref:`example_setup_symfony` + * :ref:`example_setup_typo3` + * :ref:`example_setup_wordpress` + * :ref:`example_setup_yii` + * :ref:`example_setup_zend` + +.. seealso:: + + **Generic information for all unlisted frameworks** + + * :ref:`example_setup_other_frameworks` diff --git a/docs/getting-started/the-intranet.rst b/docs/getting-started/devilbox-intranet.rst similarity index 75% rename from docs/getting-started/the-intranet.rst rename to docs/getting-started/devilbox-intranet.rst index ed236c29..64d4e12f 100644 --- a/docs/getting-started/the-intranet.rst +++ b/docs/getting-started/devilbox-intranet.rst @@ -1,9 +1,13 @@ -************ -The Intranet -************ +.. include:: /_includes/all.rst -The intranet is your command & control center showing all kinds of information and settings -currently in effect. It also offers third-party projects to do all sorts of database +.. _devilbox_intranet: + +***************** +Devilbox intranet +***************** + +The Devilbox intranet is your command & control center showing all kinds of information and +settings currently in effect. It also offers third-party projects to do all sorts of database manipulation. @@ -22,7 +26,7 @@ The start page is there to check if everything works as expected. It shows all d containers you wanted to start and if they succeeded, as well as their ports, mount points and special settings applied via ``.env``. -.. image:: /_static/img/devilbox-index.png +.. include:: /_includes/figures/devilbox/devilbox-intranet-index.rst Virtual hosts @@ -31,7 +35,7 @@ Virtual hosts The virtual host page displays all available projects and let's you know if their configuration is correct, such as DNS settings or document root. -.. image:: /_static/img/devilbox-vhosts.png +.. include:: /_includes/figures/devilbox/devilbox-intranet-vhosts.rst Emails @@ -40,7 +44,7 @@ Emails The email page displays all emails that would have been sent, but were caught by the integrated email catch-all functionality. -.. image:: /_static/img/devilbox-emails.png +.. include:: /_includes/figures/devilbox/devilbox-intranet-emails.rst Databases @@ -51,7 +55,7 @@ what is currently in place, how many databases/schemas and or recors and what si The following example shows the database page for MySQL: -.. image:: /_static/img/devilbox-database.png +.. include:: /_includes/figures/devilbox/devilbox-intranet-mysql-databases.rst Info pages @@ -62,11 +66,11 @@ currently applied. The following example shows you the info page for PHP. -.. image:: /_static/img/devilbox-info-php.png +.. include:: /_includes/figures/devilbox/devilbox-intranet-php-info.rst The following example shows you the info page for MySQL: -.. image:: /_static/img/devilbox-info-mysql.png +.. include:: /_includes/figures/devilbox/devilbox-intranet-mysql-info.rst Third-party tools @@ -75,7 +79,7 @@ Third-party tools phpMyAdmin ---------- -`phpMyAdmin `_ is a free software tool written in PHP, +|ext_lnk_tool_phpmyadmin| is a free software tool written in PHP, intended to handle the administration of MySQL over the Web. phpMyAdmin supports a wide range of operations on MySQL and MariaDB. Frequently used operations (managing databases, tables, columns, relations, indexes, users, permissions, etc) can be performed via the user interface, @@ -85,7 +89,7 @@ while you still have the ability to directly execute any SQL statement. Adminer ------- -`Adminer `_ (formerly phpMinAdmin) is a full-featured database +|ext_lnk_tool_adminer| (formerly phpMinAdmin) is a full-featured database management tool written in PHP. Conversely to phpMyAdmin, it consist of a single file ready to deploy to the target server. Adminer is available for MySQL, MariaDB, PostgreSQL, SQLite, MS SQL, Oracle, Firebird, SimpleDB, Elasticsearch and MongoDB. @@ -94,7 +98,7 @@ Oracle, Firebird, SimpleDB, Elasticsearch and MongoDB. OpcacheGUI ---------- -`OpcacheGui `_ is a clean and responsive interface for +|ext_lnk_tool_opcachegui| is a clean and responsive interface for Zend OPcache information, showing statistics, settings and cached files, and providing a real-time update for the information (using jQuery and React). @@ -134,3 +138,5 @@ Checklist 1. You know what tools are provided by the Devilbox intranet 2. You know how to password protect the Devilbox intranet 3. You know how to disable the Devilbox intranet + +.. seealso:: :ref:`troubleshooting` diff --git a/docs/getting-started/enter-the-php-container.rst b/docs/getting-started/enter-the-php-container.rst index f822ddb7..3d3cb7bd 100644 --- a/docs/getting-started/enter-the-php-container.rst +++ b/docs/getting-started/enter-the-php-container.rst @@ -2,7 +2,7 @@ Enter the PHP container *********************** -Another core feature of the Devilbox is, to be totally independent of what you have or have not +Another core feature of the Devilbox, is to be totally independent of what you have or have not installed on your host operating system. The Devilbox already ships with many common developer tools which are installed inside each PHP @@ -100,7 +100,7 @@ automatically pushed to Docker hub to ensure versions are outdated at a maximum The only thing you have to do, is to update the Docker images itself, simply by pulling a new version. -.. seealso:: :ref:`getting_started_update_the_docker_images` +.. seealso:: :ref:`update_the_devilbox_update_the_docker_images` Advanced @@ -109,7 +109,7 @@ Advanced This is just a short overview about the possibility to work inside the container. If you want to dig deeper into this topic there is also a more advanced tutorial available: -.. seealso:: :ref:`tutorial_work_inside_the_php_container` +.. seealso:: :ref:`work_inside_the_php_container` Checklist @@ -119,3 +119,5 @@ Checklist * You know how to become ``root`` inside the PHP container * You know what tools are available inside the PHP container * You know how to update the tools by pulling new versions of the Docker images + +.. seealso:: :ref:`troubleshooting` diff --git a/docs/getting-started/install-the-devilbox.rst b/docs/getting-started/install-the-devilbox.rst index 5aeac207..e8a71aa2 100644 --- a/docs/getting-started/install-the-devilbox.rst +++ b/docs/getting-started/install-the-devilbox.rst @@ -1,10 +1,13 @@ +.. include:: /_includes/all.rst + +.. _install_the_devilbox: + ******************** Install the Devilbox ******************** .. important:: - :ref:`read_first` - Ensure you have read this document to understand how this documentation works. + Ensure you have read and followed the :ref:`prerequisites` **Table of Contents** @@ -12,108 +15,45 @@ Install the Devilbox .. contents:: :local: -Supported OS -============ - -The devilbox runs on all operating systems that provide ``Docker`` and ``Docker Compose``. - -+------------+------------+------------+ -| |logo_lin| | |logo_win| | |logo_osx| | -+------------+------------+------------+ - -.. |logo_lin| image:: https://raw.githubusercontent.com/cytopia/icons/master/64x64/linux.png -.. |logo_osx| image:: https://raw.githubusercontent.com/cytopia/icons/master/64x64/osx.png -.. |logo_win| image:: https://raw.githubusercontent.com/cytopia/icons/master/64x64/windows.png - - -Requirements -============ - -The only requirements for the devilbox is to have ``Docker`` and ``Docker Compose`` installed, -everything else is bundled and provided withing the Docker container. -The minimum required versions are listed below: - -* ``Docker``: 1.12.0+ -* ``Docker Compose``: 1.9.0+ - - -Additionally you will require ``git`` in order to clone the devilbox project. - -.. warning:: - :ref:`docker_toolbox` - Use **native Docker** and do not use the **Docker Toolbox**. If you still have to use the - Docker Toolbox (e.g. for Windows 7 or older Macs) read up on this section. - -.. warning:: - Docker itself requires super user privileges which is granted to a system wide group - called ``docker``. After having installed Docker on your system, ensure that your local - user is assigned to the ``docker`` group. Check this via ``groups`` or ``id`` command. - -.. seealso:: - :ref:`install_docker` - Have a look at this page to help you install ``Docker`` for your operating system. - :ref:`install_docker_compose` - Have a look at this page to help you install ``Docker Compose`` for your operating system. - - -Download the devilbox +Download the Devilbox ===================== -The devilbox does not need to be installed. The only thing that is required is its git directory. +The Devilbox does not need to be installed. The only thing that is required is its git directory. To download that, open a terminal and copy/paste the following command. .. code-block:: bash host> git clone https://github.com/cytopia/devilbox +.. seealso:: -Checkout a different release ----------------------------- - -You now have the devilbox downloaded at the latest version (``git master branch``). This is also recommended as it receives -bugfixes frequently. If you however want to stay on a stable release, you need to check out a -specific ``git tag``. - -Lets say you want your devilbox setup to be at release ``0.12.1``, all you have to do is to check out -this specific git tag. - -.. code-block:: bash - - host> cd path/to/devilbox - host> git checkout 0.12.1 - - -.. warning:: - Whenever you check out a different version, make sure that your ``.env`` file is up-to-date - with the bundled ``env-example`` file. Different Devilbox releases might require different - settings to be available inside the ``.env`` file. Refer to the next section for how to - create the ``.env`` file. + * :ref:`howto_open_terminal_on_mac` + * :ref:`howto_open_terminal_on_win` + * :ref:`checkout-different-devilbox-release` Create ``.env`` file ==================== -Inside the cloned devilbox git directory, you will find a file called ``env-example``. This file -acts as a template with sane defaults for ``Docker Compose``. In order to use it, it must be -copied to a file named ``.env``. (Note the leading dot). +Inside the cloned Devilbox git directory, you will find a file called ``env-example``. This file +is the main configuration with sane defaults for Docker Compose. In order to use it, it must be +copied to a file named ``.env``. (Pay attention to the leading dot). .. code-block:: bash host> cp env-example .env -The ``.env`` file does nothing else then providing environment variables for ``Docker Compose`` -and in this case it is used as the main configuration file for the devilbox by providing all kinds +The ``.env`` file does nothing else then providing environment variables for Docker Compose +and in this case it is used as the main configuration file for the Devilbox by providing all kinds of settings (such as which version to start up). .. seealso:: - `Docker Compose env file `_ - Official Docker documentation about the ``.env`` file - :ref:`env_file` - All available Devilbox ``.env`` values and their description + * |ext_lnk_docker_compose_env_file| + * :ref:`env_file` -Adjust ``.env`` file -==================== +Set uid and gid +=============== To get you started, there are only two variables that need to be adjusted: @@ -152,22 +92,20 @@ Open the ``.env`` file with your favorite text editor and adjust those values: NEW_UID=1001 NEW_GID=1002 -.. warning:: - Make sure that you use the values provided by ``id -u`` and ``id -g``. - .. seealso:: - :ref:`syncronize_container_permissions` - Read up more on the general problem of trying to have syncronized permissions between - the host system and a running Docker container. + * |ext_lnk_uid| + * :ref:`howto_find_uid_and_gid_on_mac` + * :ref:`howto_find_uid_and_gid_on_win` + * :ref:`syncronize_container_permissions` Checklist ========= -1. ``Docker`` and ``Docker Compose`` are installed at minimum required version -2. Your user is part of the ``docker`` group -3. ``Devilbox`` is cloned -4. ``.env`` file is created -5. User and group id have been set in ``.env`` file +1. Devilbox is cloned +2. ``.env`` file is created +3. User and group id have been set in ``.env`` file That's it, you have finished the first section and have a working Devilbox ready to be started. + +.. seealso:: :ref:`troubleshooting` diff --git a/docs/getting-started/prerequisites.rst b/docs/getting-started/prerequisites.rst new file mode 100644 index 00000000..e8a12480 --- /dev/null +++ b/docs/getting-started/prerequisites.rst @@ -0,0 +1,235 @@ +.. include:: /_includes/all.rst + +.. _prerequisites: + +************* +Prerequisites +************* + +.. important:: + :ref:`read_first` + Ensure you have read this document to understand how this documentation works. + + +**Table of Contents** + +.. contents:: :local: + + +Supported host OS +================= + +The Devilbox runs on all major operating systems which provide ``Docker`` and ``Docker Compose``. +See the matrix below for supported versions: + ++----------------+---------------------+--------------------------------+-------------+ +| OS | Version | Type | Recommended | ++================+=====================+================================+=============+ +| |img_logo_lin| | Any | |ext_lnk_prereq_docker_lin| | yes | ++----------------+---------------------+--------------------------------+-------------+ +| | | | | ++----------------+---------------------+--------------------------------+-------------+ +| |img_logo_mac| | Any | |ext_lnk_prereq_docker_mac| | yes | +| | +--------------------------------+-------------+ +| | | |ext_lnk_prereq_docker_mac_tb| | | ++----------------+---------------------+--------------------------------+-------------+ +| | | | | ++----------------+---------------------+--------------------------------+-------------+ +| |img_logo_win| | Windows 7 | |ext_lnk_prereq_docker_win_tb| | yes | +| +---------------------+--------------------------------+-------------+ +| | Windows 10 | |ext_lnk_prereq_docker_win| | yes | +| | +--------------------------------+-------------+ +| | | |ext_lnk_prereq_docker_win_tb| | | +| +---------------------+--------------------------------+-------------+ +| | Windows Server 2016 | |ext_lnk_prereq_docker_win_ee| | yes | ++----------------+---------------------+--------------------------------+-------------+ + + +Required software +================= + +The only requirements for the Devilbox is to have ``Docker`` and ``Docker Compose`` installed, +everything else is bundled and provided withing the Docker container. +The minimum required versions are listed below: + +* ``Docker``: 1.12.0+ +* ``Docker Compose``: 1.9.0+ + + +Additionally you will require ``git`` in order to clone the devilbox project. + +.. seealso:: + + * |ext_lnk_install_docker| + * |ext_lnk_docker_compose_install| + * |ext_lnk_download_git_win| + * :ref:`howto_find_docker_and_docker_compose_version` + + +Docker installation +=================== + +Linux +----- + +|img_logo_lin| + +Docker on Linux requires super user privileges which is granted to a system +wide group called ``docker``. After having installed Docker on your system, +ensure that your local user is a member of the ``docker`` group. + +.. code-block:: bash + + host> id + + uid=1000(cytopia) gid=1000(cytopia) groups=1000(cytopia),999(docker) + +.. seealso:: + + * |ext_lnk_install_docker_centos| + * |ext_lnk_install_docker_debian| + * |ext_lnk_install_docker_fedora| + * |ext_lnk_install_docker_ubuntu| + * |ext_lnk_install_docker_linux_post_steps| (covers ``docker`` group) + +Mac +--- + +|img_logo_mac| + +On MacOS Docker is available in two different forms: **Docker for Mac** +and **Docker Toolbox**. + +Docker for Mac +^^^^^^^^^^^^^^ + +Docker for Mac is the native and recommended version to choose when using the +Devilbox. + +Docker for Mac requires super user privileges which is granted to a system +wide group called ``docker``. After having installed Docker on your system, +ensure that your local user is a member of the ``docker`` group. + +.. code-block:: bash + + host> id + + uid=502(cytopia) gid=20(staff) groups=20(staff),999(docker) + +.. seealso:: + + Docker for Mac + * |ext_lnk_install_docker_mac| + * |ext_lnk_install_docker_mac_get_started| + +Docker Toolbox +^^^^^^^^^^^^^^ + +If you still want to use Docker Toolbox, ensure you have read its +drawbacks in the below provided links. + +.. seealso:: + + Docker Toolbox + * |ext_lnk_install_docker_toolbox_mac| + * |ext_lnk_install_docker_toolbox_mac_native_vs_toolbox| + * |ext_link_docker_machine| + +.. important:: :ref:`howto_docker_toolbox_and_the_devilbox` + +Windows +------- + +|img_logo_win| + +On Windows Docker is available in two different forms: **Docker for Windows** +and **Docker Toolbox**. + +Docker for Windows +^^^^^^^^^^^^^^^^^^ + +Docker for Windows is the native and recommended version to choose when using +the Devilbox. This however is only available since **Windows 10**. + +Docker for Windows requires administrative privileges which is granted to a system +wide group called ``docker-users``. After having installed Docker on your system, +ensure that your local user is a member of the ``docker-users`` group. + +.. seealso:: + + Docker for Windows + * |ext_lnk_install_docker_win| + * |ext_lnk_install_docker_win_get_started| + +Docker Toolbox +^^^^^^^^^^^^^^ + +If you are on **Windows 7** or still want to use Docker Toolbox, ensure you +have read its drawbacks in the below provided links. + +.. seealso:: + + Docker Toolbox + * |ext_lnk_install_docker_toolbox_win| + * |ext_link_docker_machine| + +.. important:: :ref:`howto_docker_toolbox_and_the_devilbox` + + +Post installation +================= + +Read the Docker documentation carefully and follow all **install** and **post-install** steps. +Below are a few stumbling blocks to check that might or might not apply depending on your host +operating system and your Docker version. + +.. seealso:: :ref:`troubleshooting` + +User settings +------------- + +Some versions of Docker require your local user to be in the ``docker`` group +(or ``docker-users`` on Windows). + +Shared drives +------------- + +Some versions of Docker require you to correctly setup shared drives. Ensure the desired locations +are being made available to Docker and the correct credentials are applied. + +Network and firewall +-------------------- + +On Windows, ensure your firewall allows access to shared drives. + +SE Linux +-------- + +Make sure to read any shortcomings when SE Linux is enabled. + +General +------- + +It could also help to do a full system restart after the installation has been finished. + + +Optional previous knowledge +=========================== + +In order to easily work with the Devilbox you should already be familiar with the following: + +* Navigate on the command line +* Docker Compose commands (|ext_lnk_docker_compose_cmd_up|, |ext_lnk_docker_compose_cmd_stop|, + |ext_lnk_docker_compose_cmd_kill|, |ext_lnk_docker_compose_cmd_rm|, + |ext_lnk_docker_compose_cmd_logs| and |ext_lnk_docker_compose_cmd_pull|) +* Docker Compose ``.env`` file +* Know how to use ``git`` + + + + +.. seealso:: + + * |ext_lnk_docker_compose_cmd_reference| + * |ext_lnk_docker_compose_env_file| + * :ref:`troubleshooting` diff --git a/docs/getting-started/start-the-devilbox.rst b/docs/getting-started/start-the-devilbox.rst index 280c8f56..de6880e6 100644 --- a/docs/getting-started/start-the-devilbox.rst +++ b/docs/getting-started/start-the-devilbox.rst @@ -1,19 +1,22 @@ +.. include:: /_includes/all.rst + .. _start_the_devilbox: ****************** Start the Devilbox ****************** -Congratulations, when you have reached this page everything has been set up and you can now get your -hands dirty. +Congratulations, when you have reached this page everything has been set up and you can now get +your hands dirty. .. note:: - Starting and stopping containers is done via ``docker-compose``. If you have never worked with - it before, have a look at their documentation for an - `overview `_, - `up `_ and - `stop `_ commands. + Starting and stopping containers is done via ``docker-compose``. If you have never worked with + it before, have a look at their documentation for + |ext_lnk_docker_compose_cmd_overview|, |ext_lnk_docker_compose_cmd_up|, + |ext_lnk_docker_compose_cmd_stop|, |ext_lnk_docker_compose_cmd_kill|, + |ext_lnk_docker_compose_cmd_rm|, |ext_lnk_docker_compose_cmd_logs| and + |ext_lnk_docker_compose_cmd_pull| commands. **Table of Contents** @@ -21,11 +24,44 @@ hands dirty. .. contents:: :local: +The Devilbox startup explained +============================== + +To gain a brief understanding about what is happening under the hood during startup, +read ahead or skip directly to: :ref:`start_the_devilbox_start_all_container`. + + +Startup operations with the same configuration are idempotent, thus consecutive startups will not +introduce any new changes. The following shows the brief startup steps: + +* Docker Compose will automatically pull all necessary Docker images if they do not + exist locally. +* Once the HTTPD container start, it will automatically create a Certificate Authority to be used + for https connections and will place it in the ``ca/`` directory. +* The HTTPD container will then look for already available projects and create virtual hosts + configurations, apply vhost-gen templates as well as CA-signed HTTPS certificates. +* Once the Bind container start, it will create a wildcard DNS zone for the given + :ref:`env_tld_suffix` +* In case MySQL or PgSQL container start, they will populate itself with their required default + databases. + +.. note:: + Docker images are only pulled if they do not exist. They are not updated automatically. + If you want to update to new Docker images read on: :ref:`update_the_devilbox`. + + +.. _start_the_devilbox_start_all_container: + Start all container =================== -If you want all provided services to be available (as defined in ``docker-compose.yml``), -just start them all via: +If you want all provided docker container to be available (as defined in ``docker-compose.yml``), +start them all by not explicitly specifying any image name. + +Foreground +---------- + +For the first startup, foreground start is recommended to see any errors that might occur: .. code-block:: bash @@ -34,12 +70,27 @@ just start them all via: * If you want to gracefully stop all container, hit ``Ctrl + c`` * If you want to kill all container, hit ``Ctrl + c`` twice +Background +---------- + +For consecutive startups you can send them into background (``-d``): + +.. code-block:: bash + + host> docker-compose up -d + +* If you want to gracefully stop all container, enter ``docker-compose stop`` +* If you want to kill all container, enter ``docker-compose kil`` + Start some container ==================== -If you don't require all services to be up and running and let's say just ``PHP``, ``HTTPD`` and -``MYSQL``, enter the following command: +If you don't require all container to be up and running and let's say just ``PHP``, ``HTTPD`` and +``MYSQL``, you must explicitly specify the image names to start: + +Foreground +---------- .. code-block:: bash @@ -48,6 +99,16 @@ If you don't require all services to be up and running and let's say just ``PHP` * If you want to gracefully stop all started container, hit ``Ctrl + c`` * If you want to kill all started container, hit ``Ctrl + c`` twice +Background +---------- + +.. code-block:: bash + + host> docker-compose up -d httpd php mysql + +* If you want to gracefully stop all container, enter ``docker-compose stop`` +* If you want to kill all container, enter ``docker-compose kil`` + .. seealso:: :ref:`available_container` Have a look at this page to get an overview about all available container and by what name @@ -63,18 +124,21 @@ http://127.0.0.1. The Intranet start page will also show you all running and failed containers: -.. image:: /_static/img/devilbox-dash-full.png -.. image:: /_static/img/devilbox-dash-selective.png -.. warning:: - :ref:`docker_toolbox` - When you are using ``Docker Toolbox`` the Devilbox Web server port will not be available on - your host computer. You have to forward the virtual machines port to your host computer. - Read more about it on this guide. +.. include:: /_includes/figures/devilbox/devilbox-intranet-dash-all.rst +.. include:: /_includes/figures/devilbox/devilbox-intranet-dash-selective.rst + +.. important:: + :ref:`howto_find_docker_toolbox_ip_address` + When you are using ``Docker Toolbox`` the Devilbox web server port will not be available on + your host computer. You first have to find out on which IP address the Docker Toolbox machine + is serving and use this one instead. Checklist ========= 1. Docker container are started successfully with ``docker-compose up`` -2. Intranet is reachable via ``http://localhost`` or ``http://127.0.0.1`` +2. Intranet is reachable via ``http://localhost``, ``http://127.0.0.1`` or Docker Toolbox IP address + +.. seealso:: :ref:`troubleshooting` diff --git a/docs/howto/devilbox/find-docker-and-docker-compose-version.rst b/docs/howto/devilbox/find-docker-and-docker-compose-version.rst new file mode 100644 index 00000000..421ce825 --- /dev/null +++ b/docs/howto/devilbox/find-docker-and-docker-compose-version.rst @@ -0,0 +1,23 @@ +:orphan: + +.. _howto_find_docker_and_docker_compose_version: + +************************************** +Find Docker and Docker Compose version +************************************** + +Open a terminal and type the following: + +.. code-block:: bash + + # Get Docker version + host> docker --version + + # Get Docker Compose version + host> docker-compose --version + + +.. seealso:: + + * :ref:`howto_open_terminal_on_mac` + * :ref:`howto_open_terminal_on_win` diff --git a/docs/howto/devilbox/move-projects-to-different-directory.rst b/docs/howto/devilbox/move-projects-to-different-directory.rst new file mode 100644 index 00000000..902321a0 --- /dev/null +++ b/docs/howto/devilbox/move-projects-to-different-directory.rst @@ -0,0 +1,87 @@ +:orphan: + +.. _howto_move_projects_to_a_different_directory: + +************************************** +Move projects to a different directory +************************************** + +No matter if your projects are already in a different location or if you want to move them out of +the Devilbox git directory now, you can do that in a few simple steps. + +**Table of Contents** + +.. contents:: :local: + +Projects in an absolute path +============================ + +So let’s assume all of your projects are already in place under ``/home/user/workspace/web/``. +Now you decide to use the Devilbox, but still want to keep your projects where they are at the +moment. + +All you have to to is to adjust the path of :ref:`env_httpd_datadir` in the ``.env`` file. + +.. code-block:: bash + + # Navigate to Devilbox git directory + host> cd path/to/devilbox + + # Open the .env file with your favourite editor + host> vim .env + +Now Adjust the value of :ref:`env_httpd_datadir` + +.. code-block:: bash + :caption: .env + :emphasize-lines: 1 + + HOST_PATH_HTTPD_DATADIR=/home/user/workspace/web + +That's it, whenever you start up the Devilbox, ``/home/user/workspace/web/`` will be mounted into +the PHP and the web server container into ``/shared/httpd/``. + + +Projects adjacent to Devilbox directory +======================================= + +Consider the following directory setup: + +.. code-block:: bash + + | + +- devilbox/ + | + +- projects/ + | + + project1/ + | | + | + htdocs/ + | + + project2/ + | + + htdocs/ + +Independently of where the Devilbox directory is located, you can achieve this structure via +relative path settings. + +All you have to to is to adjust the path of :ref:`env_httpd_datadir` in the ``.env`` file. + +.. code-block:: bash + + # Navigate to Devilbox git directory + host> cd path/to/devilbox + + # Open the .env file with your favourite editor + host> vim .env + +Now Adjust the value of :ref:`env_httpd_datadir` + +.. code-block:: bash + :caption: .env + :emphasize-lines: 1 + + HOST_PATH_HTTPD_DATADIR=../projects + +That's it, whenever you start up the Devilbox, your project directory will be mounted into +the PHP and the web server container into ``/shared/httpd/``. diff --git a/docs/howto/dns/add-custom-dns-server-on-android.rst b/docs/howto/dns/add-custom-dns-server-on-android.rst new file mode 100644 index 00000000..c2fe04a1 --- /dev/null +++ b/docs/howto/dns/add-custom-dns-server-on-android.rst @@ -0,0 +1,53 @@ +:orphan: + +.. include:: /_includes/all.rst + +.. _howto_add_custom_dns_server_on_android: + +******************************** +Add custom DNS server on Android +******************************** + +Adding custom DNS server on Android works out of the box for each connected Wi-Fi network +separately. There is no need to install external Apps. + + +**Table of Contents** + +.. contents:: :local: + + +Change DNS server in Android directly +===================================== + +1. Navigate to **Settings -> Wi-Fi** +2. **Press and hold** on the Wi-Fi network you want to change +3. Choose **Modify network** + + .. include:: /_includes/figures/dns-server/android/android-wifi-list.rst + +4. Scroll down and click on **Advanced options** + + .. include:: /_includes/figures/dns-server/android/android-wifi-advanced-options.rst + +5. Scroll down and click on **DHCP** + + .. include:: /_includes/figures/dns-server/android/android-wifi-select-dhcp-options.rst + +6. Click on **Static** + + .. include:: /_includes/figures/dns-server/android/android-wifi-select-dhcp-options-static.rst + +7. Scroll down and change the DNS server IP for **DNS 1** (the first DNS server in the list) + + .. include:: /_includes/figures/dns-server/android/android-wifi-set-dns-server.rst + + +Change DNS server with Third-Party App +====================================== + +If the above does not work for you or you just want another App that makes it even easier to change +DNS settings, you can search the Playstore for many available DNS changer Apps. They also work +on non-rooted Androids. + +.. seealso:: |ext_lnk_app_android_dns_changer| diff --git a/docs/howto/dns/add-custom-dns-server-on-iphone.rst b/docs/howto/dns/add-custom-dns-server-on-iphone.rst new file mode 100644 index 00000000..28aafc9b --- /dev/null +++ b/docs/howto/dns/add-custom-dns-server-on-iphone.rst @@ -0,0 +1,49 @@ +:orphan: + +.. include:: /_includes/all.rst + +.. _howto_add_custom_dns_server_on_iphone: + +******************************* +Add custom DNS server on iPhone +******************************* + +Adding custom DNS server on iPhone works out of the box for each connected Wi-Fi network +separately. There is no need to install external Apps. + + +**Table of Contents** + +.. contents:: :local: + + +Change DNS server in iPhone directly +==================================== + +1. Navigate to **Settings -> Wi-Fi** +2. Tap on your active Wi-Fi connection + + .. include:: /_includes/figures/dns-server/iphone/iphone-wifi-list.rst + +3. Scroll down and tap on **Configure DNS** + + .. include:: /_includes/figures/dns-server/iphone/iphone-wifi-settings.rst + +4. Select **Manual** + + .. include:: /_includes/figures/dns-server/iphone/iphone-wifi-select-manual.rst + +5. Add your DNS server IP (ensure it is the first in the list) + + .. include:: /_includes/figures/dns-server/iphone/iphone-wifi-set-dns-server.rst + + + +Change DNS server with Third-Party App +====================================== + +If the above does not work for you or you just want another App that makes it even easier to change +DNS settings, you can search the AppStore for many available DNS changer Apps. They also work +on non-rooted iPhones. + +.. seealso:: |ext_lnk_app_iphone_dns_override| diff --git a/docs/howto/dns/add-custom-dns-server-on-linux.rst b/docs/howto/dns/add-custom-dns-server-on-linux.rst new file mode 100644 index 00000000..61406cfb --- /dev/null +++ b/docs/howto/dns/add-custom-dns-server-on-linux.rst @@ -0,0 +1,128 @@ +:orphan: + +.. include:: /_includes/all.rst + +.. _howto_add_custom_dns_server_on_linux: + +****************************** +Add custom DNS server on Linux +****************************** + +On Linux the DNS settings can be controlled by various different methods. Two of them are via +Network Manager and systemd-resolved. Choose on of the methods depending on your local setup. + + +**Table of Contents** + +.. contents:: :local: + + +Assumption +========== + +This tutorial is using ``127.0.0.1`` as the DNS server IP address, as it is the method to setup +Auto DNS for your local Devilbox. + + +Non permanent solution +======================= + +When you just want to try out to add a new DNS server without permanent settings, you should use +this option. + +.. note:: + Non permanent means, the settings will be gone when your DHCP release will be renewed, + reconnecting to the network, restarting the network service, logging out or + rebooting your machine. + +1. Open ``/etc/resolv.conf`` with root or sudo privileges with your favourite editor on your + host operating sustem: + + .. code-block:: bash + + host> sudo vi /etc/resolv.conf + +2. Add your new ``nameserver`` directive **above** all existing nameserver directives: + + .. code-block:: bash + :caption: /etc/resolv.conf + :emphasize-lines: 3 + + # Generated by NetworkManager + search intranet + nameserver 127.0.0.1 + nameserver 192.168.0.10 + +3. It will work instantly after saving the file + + +Network Manager +=============== + +*(This is a permanent solution and needs to be reverted when you don't need it anymore)* + +Edit ``/etc/dhcp/dhclient.conf`` with root or sudo privileges and add an instruction, which tells +your local DHCP client that whenever any of your DNS servers are changed, you always want to have +an additional entry, which is the one from the Devilbox (``127.0.0.1``). + +Add the following line to to the very beginning to ``/etc/dhcp/dhclient.conf``: + +.. code-block:: bash + :caption: /etc/dhcp/dhclient.conf + + prepend domain-name-servers 127.0.0.1; + +When you do that for the first time, you need to restart the ``network-manager`` service. + +.. code-block:: bash + + # Via service command + host> sudo service network-manager restart + + # Or the systemd way + host> sudo systemctl restart network-manager + +This will make sure that whenever your /etc/resolv.conf is deployed, you will have ``127.0.0.1`` +as the first entry and also make use of any other DNS server which are deployed via the LAN's DHCP +server. + +If the Devilbox DNS server is not running, it does not affect the name resolution, because you will +still have other entries in ``/etc/resolv.conf``. + + +systemd-resolved +================ + +*(This is a permanent solution and needs to be reverted when you don't need it anymore)* + +In case you are using systemd-resolved instead of NetworkManager, add the following line to +the very beginning to ``/etc/resolv.conf.head``: + +.. code-block:: bash + :caption: /etc/resolv.conf.head + + nameserver 127.0.0.1 + +Prevent NetworkManager from modifying ``/etc/resolv.conf`` and leave everything to +systemd-resolved by adding the following line under the ``[main]`` section of +``/etc/NetworkManager/NetworkManager.conf`` + +.. code-block:: bash + :caption: /etc/NetworkManager/NetworkManager.conf + + dns=none + +As a last step you will have to restart ``systemd-resolved``. + +.. code-block:: bash + + host> sudo systemctl stop systemd-resolved + host> sudo systemctl start systemd-resolved + +Once done, you can verify if the new DNS settings are effective: + +.. code-block:: bash + + host> systemd-resolve --status + +.. seealso:: |ext_lnk_dns_archlinux_wiki_resolv_conf| diff --git a/docs/howto/dns/add-custom-dns-server-on-mac.rst b/docs/howto/dns/add-custom-dns-server-on-mac.rst new file mode 100644 index 00000000..134115a2 --- /dev/null +++ b/docs/howto/dns/add-custom-dns-server-on-mac.rst @@ -0,0 +1,31 @@ +:orphan: + +.. _howto_add_custom_dns_server_on_mac: + +****************************** +Add custom DNS server on MacOS +****************************** + +**Table of Contents** + +.. contents:: :local: + + +Assumption +========== + +This tutorial is using ``127.0.0.1`` as the DNS server IP address, as it is the method to setup +Auto DNS for your local Devilbox. + + +Network preferences +=================== + +1. Open System Preferences +2. Go to **Network** +3. Select your **active** connected interface +4. Click on **DNS** tab +5. Add new DNS server by clicking the **+** sign +6. Add ``127.0.0.1`` as the first entry + +.. include:: /_includes/figures/dns-server/mac/mac-network-settings.rst diff --git a/docs/howto/dns/add-custom-dns-server-on-win.rst b/docs/howto/dns/add-custom-dns-server-on-win.rst new file mode 100644 index 00000000..1f292869 --- /dev/null +++ b/docs/howto/dns/add-custom-dns-server-on-win.rst @@ -0,0 +1,31 @@ +:orphan: + +.. _howto_add_custom_dns_server_on_win: + +******************************** +Add custom DNS server on Windows +******************************** + +**Table of Contents** + +.. contents:: :local: + + +Assumption +========== + +This tutorial is using ``127.0.0.1`` as the DNS server IP address, as it is the method to setup +Auto DNS for your local Devilbox. + + +Network preferences +=================== + +On Windows, you need to change your active network adapter. See the following screenshots +for how to do it. + +.. include:: /_includes/figures/dns-server/windows//win-network-connections.rst +.. include:: /_includes/figures/dns-server/windows//win-ethernet-properties.rst +.. include:: /_includes/figures/dns-server/windows//win-internet-protocol-properties.rst + +In the last screenshot, you will have to add ``127.0.0.1`` as your ``Preferred DNS server``. diff --git a/docs/howto/dns/add-project-dns-entry-on-linux.rst b/docs/howto/dns/add-project-dns-entry-on-linux.rst new file mode 100644 index 00000000..7dca4293 --- /dev/null +++ b/docs/howto/dns/add-project-dns-entry-on-linux.rst @@ -0,0 +1,65 @@ +:orphan: + +.. _howto_add_project_hosts_entry_on_linux: + +******************************** +Add project hosts entry on Linux +******************************** + +On Linux, custom DNS entries can be added to the ``/etc/hosts`` and will take precedence over the +same entries provided by any DNS server. + + +**Table of Contents** + +.. contents:: :local: + + +Assumption +========== + +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 :ref:`env_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`` | ++-------------------+------------+--------------------------+-----------------------+ + +Step by step +------------ + +When using Docker on Linux you can use ``127.0.0.1`` for the IP address. + +1. Open ``/etc/hosts`` with root privileges or via ``sudo`` with your favorite editor + + .. code-block:: bash + + host> sudo vi /etc/hosts + +2. Add DNS records for the above listed examples: + + .. code-block:: bash + :caption: /etc/hosts + + 127.0.0.1 project-1.loc + 127.0.0.1 www.project-1.loc + +3. Safe the file and verify the DNS entries with the ``ping`` command + + .. 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 diff --git a/docs/howto/dns/add-project-dns-entry-on-mac.rst b/docs/howto/dns/add-project-dns-entry-on-mac.rst new file mode 100644 index 00000000..6356973c --- /dev/null +++ b/docs/howto/dns/add-project-dns-entry-on-mac.rst @@ -0,0 +1,107 @@ +:orphan: + +.. _howto_add_project_hosts_entry_on_mac: + +******************************** +Add project hosts entry on MacOS +******************************** + +On MacOS, custom DNS entries can be added to the ``/etc/hosts`` and will take precedence over the +same entries provided by any DNS server. + + +**Table of Contents** + +.. contents:: :local: + + +Assumption +========== + +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 :ref:`env_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`` | ++-------------------+------------+--------------------------+-----------------------+ + +Docker for Mac +-------------- + +When using Docker for Mac you can use ``127.0.0.1`` for the IP address. + +1. Open ``/etc/hosts`` with admistrative privileges or via ``sudo`` with your favorite editor + + .. code-block:: bash + + host> sudo vi /etc/hosts + +2. Add DNS records for the above listed examples: + + .. code-block:: bash + :caption: /etc/hosts + + 127.0.0.1 project-1.loc + 127.0.0.1 www.project-1.loc + +3. Safe the file and verify the DNS entries with the ``ping`` command + + .. 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 + + +Docker Toolbox +-------------- + +When using the Docker Toolbox, you cannot use ``127.0.0.1`` for DNS entries, but rather need to +use the IP address of the Docker Toolbox machine instead. + +.. seealso:: :ref:`howto_find_docker_toolbox_ip_address` + +For this example we will assume the Docker Toolbox IP address is ``192.168.99.100``. + + +1. Open ``/etc/hosts`` with admistrative privileges or via ``sudo`` with your favorite editor + + .. code-block:: bash + + host> sudo vi /etc/hosts + +2. Add DNS records for the above listed examples: + + .. code-block:: bash + :caption: /etc/hosts + + 192.168.99.100 project-1.loc + 192.168.99.100 www.project-1.loc + +3. Safe the file and verify the DNS entries with the ``ping`` command + + .. code-block:: bash + + host> ping -c1 project-1.loc + + PING project-1.loc (192.168.99.100) 56(84) bytes of data. + 64 bytes from localhost (192.168.99.100): icmp_seq=1 ttl=64 time=0.066 ms + + .. code-block:: bash + + host> ping -c1 www.project-1.loc + + PING www.project-1.loc (192.168.99.100) 56(84) bytes of data. + 64 bytes from localhost (192.168.99.100): icmp_seq=1 ttl=64 time=0.066 ms diff --git a/docs/howto/dns/add-project-dns-entry-on-win.rst b/docs/howto/dns/add-project-dns-entry-on-win.rst new file mode 100644 index 00000000..f77fee4c --- /dev/null +++ b/docs/howto/dns/add-project-dns-entry-on-win.rst @@ -0,0 +1,101 @@ +:orphan: + +.. _howto_add_project_hosts_entry_on_win: + +********************************** +Add project hosts entry on Windows +********************************** + +On Windows, custom DNS entries can be added to the ``C:\Windows\System32\drivers\etc`` and will +take precedence over the same entries provided by any DNS server. + + +**Table of Contents** + +.. contents:: :local: + + +Assumption +========== + +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 :ref:`env_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`` | ++-------------------+------------+--------------------------+-----------------------+ + +Docker for Windows +------------------ + +When using Docker for Windows you can use ``127.0.0.1`` for the IP address. + +1. Open ``C:\Windows\System32\drivers\etc`` with admistrative privileges via ``notepad.exe`` or + any other text editor. + +2. Add DNS records for the above listed examples: + + .. code-block:: bash + :caption: C:\Windows\System32\drivers\etc + + 127.0.0.1 project-1.loc + 127.0.0.1 www.project-1.loc + +3. Safe the file and verify the DNS entries with the ``ping`` command + + .. 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 + + +Docker Toolbox +-------------- + +When using the Docker Toolbox, you cannot use ``127.0.0.1`` for DNS entries, but rather need to +use the IP address of the Docker Toolbox machine instead. + +.. seealso:: :ref:`howto_find_docker_toolbox_ip_address` + +For this example we will assume the Docker Toolbox IP address is ``192.168.99.100``. + + +1. Open ``C:\Windows\System32\drivers\etc`` with admistrative privileges via ``notepad.exe`` or + any other text editor. + +2. Add DNS records for the above listed examples: + + .. code-block:: bash + :caption: C:\Windows\System32\drivers\etc + + 192.168.99.100 project-1.loc + 192.168.99.100 www.project-1.loc + +3. Safe the file and verify the DNS entries with the ``ping`` command + + .. code-block:: bash + + host> ping -c1 project-1.loc + + PING project-1.loc (192.168.99.100) 56(84) bytes of data. + 64 bytes from localhost (192.168.99.100): icmp_seq=1 ttl=64 time=0.066 ms + + .. code-block:: bash + + host> ping -c1 www.project-1.loc + + PING www.project-1.loc (192.168.99.100) 56(84) bytes of data. + 64 bytes from localhost (192.168.99.100): icmp_seq=1 ttl=64 time=0.066 ms diff --git a/docs/howto/docker-toolbox/docker-toolbox-and-the-devilbox.rst b/docs/howto/docker-toolbox/docker-toolbox-and-the-devilbox.rst new file mode 100644 index 00000000..357b468d --- /dev/null +++ b/docs/howto/docker-toolbox/docker-toolbox-and-the-devilbox.rst @@ -0,0 +1,173 @@ +:orphan: + +.. include:: /_includes/all.rst + +.. _howto_docker_toolbox_and_the_devilbox: + +******************************* +Docker Toolbox and the Devilbox +******************************* + +Docker Toolbox is a legacy solution to bring Docker to systems which don’t natively support Docker. +This is achieved by starting a virtualized Linux instance (e.g.: inside VirtualBox) and have +Docker run inside this machine. + +You don’t have to take care about setting up the virtual machine, this is done automatically with +the provided setup file (Windows and MacOS). + +However, there are a few stumbling blocks you need to pay attention to in order to use the Devilbox +at its full potential. + +.. seealso:: + + Docker Toolbox + * |ext_lnk_install_docker_toolbox_win| + * |ext_lnk_install_docker_toolbox_mac| + * |ext_lnk_install_docker_toolbox_mac_native_vs_toolbox| + * |ext_link_docker_machine| + + +**Table of Contents** + +.. contents:: :local: + + +Devilbox listening address configuration +======================================== + +First thing you need to make sure is that the ``LOCAL_LISTEN_ADDR`` variable from your ``.env`` +file is empty. When it is empty all services bind to all IP addresses inside the virtual machine +and thus being able to be seen from outside the virtual machine (your host operating system). + +You can verifiy that the variable is actually empty by checking your ``.env`` file: + +.. code-block:: bash + + host> grep ^LOCAL_LISTEN_ADDR .env + + LOCAL_LISTEN_ADDR= + +.. important:: The variable should exist, but there should not be any value after the equal sign. + +.. seealso:: :ref:`env_file` + + +Find the Docker Toolbox IP address +================================== + +The Devilbox intranet will not be available under ``127.0.0.1`` or ``localhost`` as it does not run +on your host operating system, but on a virtualized Linux machine which has a different IP address. + +To find out the IP address on which Docker Toolbox is running you have to use the +``docker-machine`` command. Open a terminal and type the following: + +.. code-block:: bash + + host> docker-machine ip default + 192.168.99.100 + +The above example outputs ``192.168.99.100``, but this might be different on your machine. + +In this example I would then paste ``http://192.168.99.100`` in the web browsers address bar to +reach the Devilbox intranet. + +.. seealso:: + + * :ref:`howto_open_terminal_on_mac` + * :ref:`howto_open_terminal_on_win` + * :ref:`howto_find_docker_toolbox_ip_address` + + +Project DNS record pitfalls +=========================== + +When creating manual DNS records per project, you have to keep in mind that you cannot use +``127.0.0.1`` for the IP address part. You have to use the IP address of the Docker Toolbox +virtual machine as was shown in the above example. + + +Assuming the Docker Toolbox IP address is: ``192.168.99.100``, you have to create DNS records as +follows: + +.. code-block:: bash + :caption: /etc/resolv.conf or C:\\Windows\\System32\\drivers\\etc + + 192.168.99.100 project.loc + +.. seealso:: + + * :ref:`howto_add_project_hosts_entry_on_mac` + * :ref:`howto_add_project_hosts_entry_on_win` + * :ref:`howto_find_docker_toolbox_ip_address` + + +Auto-DNS via port forwarding +============================ + +In order to make Auto-DNS for projects work as it does for native Docker implementations you will +have to do some prior configuration. + +How does Auto-DNS work? +----------------------- + +Auto-DNS is a catch-all DNS resolver for your chosen :ref:`env_tld_suffix` that will redirect any +domain to ``127.0.0.1``. Unfortunately Docker Toolbox does not listen on that IP address. + +How to fix it for Docker Toolbox +-------------------------------- + +To overcome this problem, you will have to create three port forwards on your host operating system +from the Docker machine IP address for ``DNS`` (port 53), ``http`` (port 80) and ``https`` +(port 443) to ``127.0.0.1`` on your host os. + +Assuming the Docker Toolbox IP address is ``192.168.99.100`` the three port forwards must be as +follows: + ++----------------+-----------+-----------+---------+ +| From IP | From port | To IP | To port | ++================+===========+===========+=========+ +| 192.168.99.100 | 53 | 127.0.0.1 | 53 | ++----------------+-----------+-----------+---------+ +| 192.168.99.100 | 80 | 127.0.0.1 | 80 | ++----------------+-----------+-----------+---------+ +| 192.168.99.100 | 443 | 127.0.0.1 | 443 | ++----------------+-----------+-----------+---------+ + +.. seealso:: + + * :ref:`howto_find_docker_toolbox_ip_address` + * :ref:`howto_ssh_port_forward_on_docker_toolbox_from_host` + * :ref:`setup_auto_dns` + + +Mount shared folders +==================== + +Docker Toolbox will automatically set up a shared directory between your host operating system and +the virtual Linux machine. Only files and directories within this shared directory can be used to +be mounted into Docker container. If you plan to mount files or directories outside of this default +path you have to create a new shared directory as described below. + +MacOS +----- + +When you want to have your projects reside not somewhere in the ``/Users`` directory, ensure you +have read, understood and applied the following: + + "By default, Toolbox only has access to the ``/Users`` directory and mounts it into the VMs at + ``/Users``. If your project lives elsewhere or needs access to other directories on the host + filesystem, you can add them." + +.. seealso:: |ext_lnk_install_docker_toolbox_mac_shared_directory| + +Windows +------- + +When you want to have your projects reside not somewhere in the ``C:\Users`` directory, ensure you +have read, understood and applied the following: + + "By default, Toolbox only has access to the ``C:\Users`` directory and mounts it into the VMs + at ``/c/Users``. If your project lives elsewhere or needs access to other directories on the + host filesystem, you can add them, using the VirtualBox UI." + +.. seealso:: |ext_lnk_install_docker_toolbox_win_shared_directory| diff --git a/docs/howto/docker-toolbox/find-docker-toolbox-ip-address.rst b/docs/howto/docker-toolbox/find-docker-toolbox-ip-address.rst new file mode 100644 index 00000000..8156d650 --- /dev/null +++ b/docs/howto/docker-toolbox/find-docker-toolbox-ip-address.rst @@ -0,0 +1,48 @@ +:orphan: + +.. _howto_find_docker_toolbox_ip_address: + +****************************** +Find Docker Toolbox IP address +****************************** + +**Table of Contents** + +.. contents:: :local: + + +Get IP address +============== + +1. Open an environment prepared Terminal + +2. Enter the following command to get the IP address of the Docker Toolbox virtual machine: + + .. code-block:: bash + + host> docker-machine ip default + + 192.168.99.100 + +The above example outputs ``192.168.99.100``, but this might be a different IP address on your +machine. + +.. seealso:: + + * :ref:`howto_open_terminal_on_mac` + * :ref:`howto_open_terminal_on_win` + + +What to do with it +================== + +The Docker Toolbox IP address is the address where the Devilbox intranet as well as all of its +projects will be available at. + +* Use it to access the intranet via your browser (``http://192.168.99.100`` in this example) +* Use it for manual DNS entries + +.. seealso:: + + * :ref:`howto_add_project_hosts_entry_on_mac` + * :ref:`howto_add_project_hosts_entry_on_win` diff --git a/docs/howto/docker-toolbox/ssh-into-docker-toolbox.rst b/docs/howto/docker-toolbox/ssh-into-docker-toolbox.rst new file mode 100644 index 00000000..7b59cd4e --- /dev/null +++ b/docs/howto/docker-toolbox/ssh-into-docker-toolbox.rst @@ -0,0 +1,137 @@ +:orphan: + +.. include:: /_includes/all.rst + +.. _howto_ssh_into_docker_toolbox: + +*********************** +SSH into Docker Toolbox +*********************** + +**Table of Contents** + +.. contents:: :local: + + +Requirements +============ + +You shell must have an SSH client (the ``ssh`` command or equivalent). + +.. seealso:: + * :ref:`howto_open_terminal_on_mac` + * :ref:`howto_open_terminal_on_win` + * :ref:`howto_find_docker_toolbox_ip_address` + + +Manual +====== + +Before going to use the automated approach, you should understand how to fetch all required +information via the ``docker-machine`` command. + + +Gather all information +---------------------- + +1. Get active Toolbox machine name + + .. code-block:: bash + + host> docker-machine active + default + +2. Print all information + + .. code-block:: bash + + host> docker-machine -D ssh default + Host : localhost + Port : 51701 + User : docker + Key : .docker\machine\machines\default\id_rsa + + +Gather specific information +--------------------------- + +1. Get active Toolbox machine name + + .. code-block:: bash + + host> docker-machine active + default + +2. Get SSH username (Using machine name ``default`` from above) + + .. code-block:: bash + + host> docker-machine inspect default --format={{.Driver.SSHUser}} + docker + +3. Get SSH public key (Using machine name ``default`` from above) + + .. code-block:: bash + + host> docker-machine inspect default --format={{.Driver.SSHKeyPath}} + .docker\machine\machines\default\id_rsa + +4. Get local SSH port (Using machine name ``default`` from above) + + .. code-block:: bash + + host> docker-machine inspect default --format={{.Driver.SSHPort}} + 51701 + +5. Get Docker Toolbox IP address (Using machine name ``default`` from above) + + .. code-block:: bash + + host> docker-machine ip default + 192.168.99.100 + + +SSH into Docker Toolbox +----------------------- + +Now with the above gathered information you can ssh into Docker Toolbox in two different ways: + +1. via local port-forwarded ssh port (automatically forwarded by Docker Toolbox) + + .. code-block:: bash + + host> ssh -i .docker\machine\machines\default\id_rsa -p 51701 docker@127.0.0.1 + +2. via Docker Toolbox IP address + + .. code-block:: bash + + host> ssh -i .docker\machine\machines\default\id_rsa docker@192.168.99.100 + + +Automated +========= + +Instead of typing all of the above manually each time, you can also create a small bash script +to automate this. + +1. Create a file ``ssh-docker.sh`` and add the following to it: + + .. code-block:: bash + :caption: ssh-docker.sh + + #!/bin/bash + docker_machine_name=$(docker-machine active) + docker_ssh_user=$(docker-machine inspect $docker_machine_name --format={{.Driver.SSHUser}}) + docker_ssh_key=$(docker-machine inspect $docker_machine_name --format={{.Driver.SSHKeyPath}}) + docker_ssh_port=$(docker-machine inspect $docker_machine_name --format={{.Driver.SSHPort}}) + + ssh -i $docker_ssh_key -p $docker_ssh_port $docker_ssh_user@localhost + +2. Run it: + + .. code-block:: bash + + host> bash ssh-docker.sh + +.. seealso:: |ext_lnk_stackoverflow_ssh_into_docker_machine| diff --git a/docs/howto/docker-toolbox/ssh-port-forward-on-docker-toolbox-from-host.rst b/docs/howto/docker-toolbox/ssh-port-forward-on-docker-toolbox-from-host.rst new file mode 100644 index 00000000..f1c6043a --- /dev/null +++ b/docs/howto/docker-toolbox/ssh-port-forward-on-docker-toolbox-from-host.rst @@ -0,0 +1,111 @@ +:orphan: + +.. include:: /_includes/all.rst + +.. _howto_ssh_port_forward_on_docker_toolbox_from_host: + +******************************************** +SSH port-forward on Docker Toolbox from host +******************************************** + +.. note:: This is a **Local SSH port-forward** (``ssh -L``) + + +**Table of Contents** + +.. contents:: :local: + + +Requirements +============ + +You **host operating system** must have an **SSH server** installed, up and running. + +.. seealso:: + * :ref:`howto_open_terminal_on_mac` + * :ref:`howto_open_terminal_on_win` + * :ref:`howto_find_docker_toolbox_ip_address` + * :ref:`howto_ssh_into_docker_toolbox` + * |ext_lnk_ssh_tunnelling_for_fun_and_profit| + + +Overview +======== + +This is a **local** SSH port-forward (``ssh -L``). In other words, the Docker Toolbox machine +will make a port **locally available** from somewhere else. Therefore the process must be initiated +on the Docker Toolbox machine. + +General command +--------------- + +The following represents the general structure of a local ssh port-forward: + +.. code-block:: bash + + ssh -L :: @ + ++--------------------------+-----------------------------------------------------------------------------+ +| ```` | The port on the Docker Toolbox machine the service should be made available | ++--------------------------+-----------------------------------------------------------------------------+ +| ```` | The IP address on the host os, where the service is currently listening | ++--------------------------+-----------------------------------------------------------------------------+ +| ```` | The port on the host os, where the service is bound to | ++--------------------------+-----------------------------------------------------------------------------+ +| ```` | The username of the host os SSH server for the connection | ++--------------------------+-----------------------------------------------------------------------------+ +| ```` | The IP address of the host at which the SSH server is reachable | ++--------------------------+-----------------------------------------------------------------------------+ + +Command example +--------------- + +Making ``127.0.0.1:10000`` from host os available on ``0.0.0.0:8080`` on Docker Toolbox machine: + +.. code-block:: bash + + ssh -L 8080:127.0.0.1:10000 user@172.16.0.1 + ++--------------------------+-----------------------------------------------------------------------------+ +| ``8080`` | Docker Toolbox should make the port available on itself on this port | ++--------------------------+-----------------------------------------------------------------------------+ +| ``127.0.0.1`` | The service currently listens on that IP address on the host os | ++--------------------------+-----------------------------------------------------------------------------+ +| ``10000`` | The service is currently bound to that port on the host os | ++--------------------------+-----------------------------------------------------------------------------+ +| ``user`` | The username of the host os SSH server for the connection | ++--------------------------+-----------------------------------------------------------------------------+ +| ``172.16.0.1`` | The IP address of the host at which the SSH server is reachable | ++--------------------------+-----------------------------------------------------------------------------+ + + +Examples +======== + +For this example we assume the following information: + +* Docker Toolbox IP address is ``192.168.99.100`` +* Host os IP address where SSH server is listening is ``172.16.0.1`` +* Host SSH username is ``user`` + +Make host-based MySQL available on Docker Toolbox +------------------------------------------------- + +1. Gather the IP address on your host os where the SSH server is listening +2. SSH into the Docker Toolbox machine +3. Forward: ``127.0.0.1:3306`` from host os to ``0.0.0.0:3306`` on Docker Toolbox + + .. code-block:: bash + + toolbox> ssh -L 3306:127.0.0.1:3306 user@172.16.0.1 + +Make host-based PgSQL available on Docker Toolbox +------------------------------------------------- + +1. Gather the IP address on your host os where the SSH server is listening +2. SSH into the Docker Toolbox machine +3. Forward: ``127.0.0.1:5432`` from host os to ``0.0.0.0:5432`` on Docker Toolbox + + .. code-block:: bash + + toolbox> ssh -L 5432:127.0.0.1:5432 user@172.16.0.1 diff --git a/docs/howto/docker-toolbox/ssh-port-forward-on-host-to-docker-toolbox.rst b/docs/howto/docker-toolbox/ssh-port-forward-on-host-to-docker-toolbox.rst new file mode 100644 index 00000000..bcf0e752 --- /dev/null +++ b/docs/howto/docker-toolbox/ssh-port-forward-on-host-to-docker-toolbox.rst @@ -0,0 +1,107 @@ +:orphan: + +.. include:: /_includes/all.rst + +.. _howto_ssh_port_forward_on_host_to_docker_toolbox: + +****************************************** +SSH port-forward on host to Docker Toolbox +****************************************** + +.. note:: This is a **Remote SSH port-forward** (``ssh -R``) + +**Table of Contents** + +.. contents:: :local: + + +Requirements +============ + +You shell must have an **SSH client** (the ``ssh`` command or equivalent). + +.. seealso:: + * :ref:`howto_open_terminal_on_mac` + * :ref:`howto_open_terminal_on_win` + * :ref:`howto_find_docker_toolbox_ip_address` + * :ref:`howto_ssh_into_docker_toolbox` + * |ext_lnk_ssh_tunnelling_for_fun_and_profit| + + +Overview +======== + +This is a **remote** SSH port-forward (``ssh -R``). In other words, the host os will make the port +**remotely availabl** on the Docker Toolbox machine. Therefore the process must be initiated +on the host os. + +General command +--------------- + +The following represents the general structure of a remote ssh port-forward: + +.. code-block:: bash + + ssh -R :: @ + ++------------------------------+-----------------------------------------------------------------------------+ +| ```` | The port on the Docker Toolbox machine the service should be made available | ++------------------------------+-----------------------------------------------------------------------------+ +| ```` | The IP address on the host os, where the service is currently listening | ++------------------------------+-----------------------------------------------------------------------------+ +| ```` | The port on the host os, where the service is bound to | ++------------------------------+-----------------------------------------------------------------------------+ +| ```` | The username of the host os SSH server for the connection | ++------------------------------+-----------------------------------------------------------------------------+ +| ```` | The IP address of the host at which the SSH server is reachable | ++------------------------------+-----------------------------------------------------------------------------+ + +Command example +--------------- + +Making ``127.0.0.1:10000`` from host os available on ``0.0.0.0:8080`` on Docker Toolbox machine: + +.. code-block:: bash + + ssh -R 8080:127.0.0.1:10000 docker@192.168.99.100 + ++--------------------------+-----------------------------------------------------------------------------+ +| ``8080`` | Docker Toolbox should make the port available on itself on this port | ++--------------------------+-----------------------------------------------------------------------------+ +| ``127.0.0.1`` | The service currently listens on that IP address on the host os | ++--------------------------+-----------------------------------------------------------------------------+ +| ``10000`` | The service is currently bound to that port on the host os | ++--------------------------+-----------------------------------------------------------------------------+ +| ``docker`` | The username of the Docker Toolbox SSH server for the connection | ++--------------------------+-----------------------------------------------------------------------------+ +| ``192.168.99.100`` | The IP address of the Docker Toolbox at which the SSH server is reachable | ++--------------------------+-----------------------------------------------------------------------------+ + + +Examples +======== + +For this example we assume the following information: + +* Docker Toolbox IP address is ``192.168.99.100`` +* Docker Toolbox SSH username is ``docker`` + +Make host-based MySQL available on Docker Toolbox +------------------------------------------------- + +1. Open a terminal on your host os +2. Forward: ``127.0.0.1:3306`` from host os to ``0.0.0.0:3306`` on Docker Toolbox + + .. code-block:: bash + + toolbox> ssh -R 3306:127.0.0.1:3306 docker@192.168.99.100 + +Make host-based PgSQL available on Docker Toolbox +------------------------------------------------- + +1. Open a terminal on your host os +2. Forward: ``127.0.0.1:5432`` from host os to ``0.0.0.0:5432`` on Docker Toolbox + + .. code-block:: bash + + toolbox> ssh -R 5432:127.0.0.1:5432 docker@192.168.99.100 diff --git a/docs/howto/terminal/open-terminal-on-mac.rst b/docs/howto/terminal/open-terminal-on-mac.rst new file mode 100644 index 00000000..e1cb3770 --- /dev/null +++ b/docs/howto/terminal/open-terminal-on-mac.rst @@ -0,0 +1,95 @@ +:orphan: + +.. include:: /_includes/all.rst + +.. _howto_open_terminal_on_mac: + +************************ +Open a terminal on MacOS +************************ + +.. seealso:: :ref:`howto_open_terminal_on_win` + + +**Table of Contents** + +.. contents:: :local: + + +Docker for Mac +============== + +Docker for Mac (the native Docker implementation) does not have any special requirements for +initial environment variable setup. Simply open your terminal of choice from the **Launchpad** +(``Terminal.app`` or ``iTerm.app``). + +.. seealso:: |ext_lnk_install_docker_mac| + +Docker Toolbox +============== + +Docker Toolbox provides a launcher to open an environment prepared terminal, but you can also do +it manually with a terminal of your choice. + +Via Launcher +------------ + +1. Open the **Launchpad** and locate the Docker Quickstart Terminal icon. + +.. include:: /_includes/figures/terminal/docker-toolbox-terminal-mac-quickstart-launchpad.rst + +2. Click the icon to launch a Docker Quickstart Terminal window. + + The terminal does a number of things to set up Docker Quickstart Terminal for you. + + +.. code-block:: bash + + Last login: Sat Jul 11 20:09:45 on ttys002 + bash '/Applications/Docker Quickstart Terminal.app/Contents/Resources/Scripts/start.sh' + Get http:///var/run/docker.sock/v1.19/images/json?all=1&filters=%7B%22dangling%22%3A%5B%22true%22%5D%7D: dial unix /var/run/docker.sock: no such file or directory. Are you trying to connect to a TLS-enabled daemon without TLS? + Get http:///var/run/docker.sock/v1.19/images/json?all=1: dial unix /var/run/docker.sock: no such file or directory. Are you trying to connect to a TLS-enabled daemon without TLS? + -bash: lolcat: command not found + + mary at meepers in ~ + $ bash '/Applications/Docker Quickstart Terminal.app/Contents/Resources/Scripts/start.sh' + Creating Machine dev... + Creating VirtualBox VM... + Creating SSH key... + Starting VirtualBox VM... + Starting VM... + To see how to connect Docker to this machine, run: docker-machine env dev + Starting machine dev... + Setting environment variables for machine dev... + + ## . + ## ## ## == + ## ## ## ## ## === + /"""""""""""""""""\___/ === + ~~~ {~~ ~~~~ ~~~ ~~~~ ~~~ ~ / ===- ~~~ + \______ o __/ + \ \ __/ + \____\_______/ + + The Docker Quick Start Terminal is configured to use Docker with the "default" VM. + + +You can now use this terminal window to apply all your Docker and Devilbox related commands. + + +Different terminal +------------------ + +If you rather want to use a different terminal, you can accomplish the same behaviour. + +1. Open your terminal of choice +2. Type the following to prepare environment variables + +.. code-block:: bash + + $(docker-machine env default) + +You can now use this terminal window to apply all your Docker and Devilbox related commands. + + +.. seealso:: |ext_lnk_install_docker_toolbox_mac| diff --git a/docs/howto/terminal/open-terminal-on-win.rst b/docs/howto/terminal/open-terminal-on-win.rst new file mode 100644 index 00000000..ca46387f --- /dev/null +++ b/docs/howto/terminal/open-terminal-on-win.rst @@ -0,0 +1,56 @@ +:orphan: + +.. include:: /_includes/all.rst + +.. _howto_open_terminal_on_win: + +************************** +Open a terminal on Windows +************************** + +.. seealso:: :ref:`howto_open_terminal_on_mac` + + +**Table of Contents** + +.. contents:: :local: + + +Docker for Windows +================== + +Docker for Windows (the native Docker implementation) does not have any special requirements for +initial environment variable setup. Simply open either + +* Command Prompt +* PowerShell + + +.. important:: Do not open **PowerShell ISE** + +.. seealso:: |ext_lnk_install_docker_win| + + +Docker Toolbox +============== + +1. On your Desktop, find the Docker QuickStart Terminal icon. + +.. include:: /_includes/figures/terminal/docker-toolbox-terminal-win-quickstart-shortcut.rst + +2. Click the Docker QuickStart icon to launch a pre-configured Docker Toolbox terminal. + + If the system displays a **User Account Control** prompt to allow VirtualBox to make changes to + your computer. Choose **Yes**. + +.. include:: /_includes/figures/terminal/docker-toolbox-terminal-win-quickstart-terminal.rst + +.. + + The terminal runs a special bash environment instead of the standard Windows command prompt. + The bash environment is required by Docker. + + +You can now use this terminal window to apply all your Docker and Devilbox related commands. + +.. seealso:: |ext_lnk_install_docker_toolbox_win| diff --git a/docs/howto/uid-and-gid/find-uid-and-gid-on-mac.rst b/docs/howto/uid-and-gid/find-uid-and-gid-on-mac.rst new file mode 100644 index 00000000..6be1fda1 --- /dev/null +++ b/docs/howto/uid-and-gid/find-uid-and-gid-on-mac.rst @@ -0,0 +1,51 @@ +:orphan: + +.. _howto_find_uid_and_gid_on_mac: + +*************************************** +Find your user id and group id on MacOS +*************************************** + +**Table of Contents** + +.. contents:: :local: + + +Docker for Mac vs Docker Toolbox +================================ + +Docker for Mac +-------------- + +On Docker for Mac (native Docker) you can open up any terminal you prefer, there are no other +requirements. + +Docker Toolbox +-------------- + +On Docker Toolbox it is important that you open up a Docker environment prepared terminal window. + +.. seealso:: + + * :ref:`howto_open_terminal_on_mac` + + +Find uid and gid +================ + +Open the correct terminal as described above and type the following commands: + +Find your user id (``uid``) +--------------------------- + +.. code-block:: bash + + host> id -u + + +Find your group id (``gid``) +---------------------------- + +.. code-block:: bash + + host> id -g diff --git a/docs/howto/uid-and-gid/find-uid-and-gid-on-win.rst b/docs/howto/uid-and-gid/find-uid-and-gid-on-win.rst new file mode 100644 index 00000000..1f8e38ed --- /dev/null +++ b/docs/howto/uid-and-gid/find-uid-and-gid-on-win.rst @@ -0,0 +1,51 @@ +:orphan: + +.. _howto_find_uid_and_gid_on_win: + +***************************************** +Find your user id and group id on Windows +***************************************** + +**Table of Contents** + +.. contents:: :local: + + +Docker for Windows +================== + +On Docker for Windows it is **not necessary** to change uid and gid in your ``.env`` file. + +.. note:: + Docker for Windows is internally using network shares (SMB) to mount Docker volumes. + This does not require to syncronize file and directoriy permissions via uid and gid. + + +Docker Toolbox +============== + +On Docker Toolbox it is important that you open up a Docker environment prepared terminal window. + +.. seealso:: + + * :ref:`howto_open_terminal_on_win` + + +Find your user id (``uid``) +--------------------------- + +Type the following command to retrieve the correct ``uid``. + +.. code-block:: bash + + host> id -u + + +Find your group id (``gid``) +---------------------------- + +Type the following command to retrieve the correct ``gid``. + +.. code-block:: bash + + host> id -g diff --git a/docs/howto/xdebug/host-address-alias-an-mac.rst b/docs/howto/xdebug/host-address-alias-an-mac.rst new file mode 100644 index 00000000..b21f103b --- /dev/null +++ b/docs/howto/xdebug/host-address-alias-an-mac.rst @@ -0,0 +1,50 @@ +:orphan: + +.. include:: /_includes/all.rst + +.. _howto_host_address_alias_on_mac: + +*************************** +Host address alias on MacOS +*************************** + +In order for Xdebug to work on Docker for MacOS, the container needs a well known IP address +for its Xdebug remote host. This is achieved by adding an alias to the loopback device. + +**Table of Contents** + +.. contents:: :local: + + +One-time alias +============== + +In order to create this alias for testing purposes, which does not survive reboots, you can +issue the command manually with ``sudo`` or root privileges. + +.. code-block:: bash + + host> sudo ifconfig lo0 alias 10.254.254.254 + + +Boot persistent alias +===================== + +If you want to have this alias persistent across reboot, you need to download and enable a +``plist`` file: + + +.. code-block:: bash + + # Download the plist into the correct location + host> sudo curl -o \ + /Library/LaunchDaemons/org.devilbox.docker_10254_alias.plist \ + https://raw.githubusercontent.com/devilbox/xdebug/master/osx/org.devilbox.docker_10254_alias.plist + + # Enable without reboot + host> sudo launchctl load /Library/LaunchDaemons/org.devilbox.docker_10254_alias.plist + +.. seealso:: + * :ref:`configure_php_xdebug` + * |ext_lnk_github_devilbox_xdebug_on_mac| + * |ext_lnk_github_original_xdebug_on_mac| diff --git a/docs/img/devilbox-banner.png b/docs/img/devilbox-banner.png deleted file mode 100644 index 7ed3dbeb..00000000 Binary files a/docs/img/devilbox-banner.png and /dev/null differ diff --git a/docs/img/devilbox_01-setup-and-workflow.png b/docs/img/devilbox_01-setup-and-workflow.png deleted file mode 100644 index fd4aea11..00000000 Binary files a/docs/img/devilbox_01-setup-and-workflow.png and /dev/null differ diff --git a/docs/img/devilbox_02-email-catch-all.png b/docs/img/devilbox_02-email-catch-all.png deleted file mode 100644 index 02c3a5a1..00000000 Binary files a/docs/img/devilbox_02-email-catch-all.png and /dev/null differ diff --git a/docs/img/logo_fw/cake.png b/docs/img/logo_fw/cake.png deleted file mode 100644 index bc9531d2..00000000 Binary files a/docs/img/logo_fw/cake.png and /dev/null differ diff --git a/docs/img/logo_fw/drupal.png b/docs/img/logo_fw/drupal.png deleted file mode 100644 index 44764cf8..00000000 Binary files a/docs/img/logo_fw/drupal.png and /dev/null differ diff --git a/docs/img/logo_fw/joomla.png b/docs/img/logo_fw/joomla.png deleted file mode 100644 index d0e298f8..00000000 Binary files a/docs/img/logo_fw/joomla.png and /dev/null differ diff --git a/docs/img/logo_fw/laravel.png b/docs/img/logo_fw/laravel.png deleted file mode 100644 index 71a4cb3b..00000000 Binary files a/docs/img/logo_fw/laravel.png and /dev/null differ diff --git a/docs/img/logo_fw/phalcon.png b/docs/img/logo_fw/phalcon.png deleted file mode 100644 index f5c48566..00000000 Binary files a/docs/img/logo_fw/phalcon.png and /dev/null differ diff --git a/docs/img/logo_fw/symfony.png b/docs/img/logo_fw/symfony.png deleted file mode 100644 index 6ce67a78..00000000 Binary files a/docs/img/logo_fw/symfony.png and /dev/null differ diff --git a/docs/img/logo_fw/wordpress.png b/docs/img/logo_fw/wordpress.png deleted file mode 100644 index 85813149..00000000 Binary files a/docs/img/logo_fw/wordpress.png and /dev/null differ diff --git a/docs/img/logo_fw/yii.png b/docs/img/logo_fw/yii.png deleted file mode 100644 index 86242ac2..00000000 Binary files a/docs/img/logo_fw/yii.png and /dev/null differ diff --git a/docs/img/logo_fw/zend.png b/docs/img/logo_fw/zend.png deleted file mode 100644 index 4e5c6ad0..00000000 Binary files a/docs/img/logo_fw/zend.png and /dev/null differ diff --git a/docs/img/logo_tools/composer.png b/docs/img/logo_tools/composer.png deleted file mode 100644 index cb76aed5..00000000 Binary files a/docs/img/logo_tools/composer.png and /dev/null differ diff --git a/docs/img/logo_tools/drupal-console.png b/docs/img/logo_tools/drupal-console.png deleted file mode 100644 index b3c841a5..00000000 Binary files a/docs/img/logo_tools/drupal-console.png and /dev/null differ diff --git a/docs/img/logo_tools/drush.png b/docs/img/logo_tools/drush.png deleted file mode 100644 index 40e659d0..00000000 Binary files a/docs/img/logo_tools/drush.png and /dev/null differ diff --git a/docs/img/logo_tools/git.png b/docs/img/logo_tools/git.png deleted file mode 100644 index 12b606a7..00000000 Binary files a/docs/img/logo_tools/git.png and /dev/null differ diff --git a/docs/img/logo_tools/mysqldump-secure.png b/docs/img/logo_tools/mysqldump-secure.png deleted file mode 100644 index 3940b5b5..00000000 Binary files a/docs/img/logo_tools/mysqldump-secure.png and /dev/null differ diff --git a/docs/img/logo_tools/nodejs.png b/docs/img/logo_tools/nodejs.png deleted file mode 100644 index 21192351..00000000 Binary files a/docs/img/logo_tools/nodejs.png and /dev/null differ diff --git a/docs/img/logo_tools/npm.png b/docs/img/logo_tools/npm.png deleted file mode 100644 index a08983f9..00000000 Binary files a/docs/img/logo_tools/npm.png and /dev/null differ diff --git a/docs/img/logo_tools/wp-cli.png b/docs/img/logo_tools/wp-cli.png deleted file mode 100644 index c3c2cf3c..00000000 Binary files a/docs/img/logo_tools/wp-cli.png and /dev/null differ diff --git a/docs/img/screenshots/01_intranet_home.png b/docs/img/screenshots/01_intranet_home.png deleted file mode 100644 index 0d9443fb..00000000 Binary files a/docs/img/screenshots/01_intranet_home.png and /dev/null differ diff --git a/docs/img/screenshots/02_intranet_vhosts.png b/docs/img/screenshots/02_intranet_vhosts.png deleted file mode 100644 index 205185f1..00000000 Binary files a/docs/img/screenshots/02_intranet_vhosts.png and /dev/null differ diff --git a/docs/img/screenshots/03_intranet_databases.png b/docs/img/screenshots/03_intranet_databases.png deleted file mode 100644 index 43b8284c..00000000 Binary files a/docs/img/screenshots/03_intranet_databases.png and /dev/null differ diff --git a/docs/img/screenshots/04_intranet_emails.png b/docs/img/screenshots/04_intranet_emails.png deleted file mode 100644 index 7e72a8cc..00000000 Binary files a/docs/img/screenshots/04_intranet_emails.png and /dev/null differ diff --git a/docs/index.rst b/docs/index.rst index 4d6d2481..e5d74ee9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,9 +1,12 @@ -********************** -devilbox documentation -********************** .. :hidden: -.. image:: img/banner.png +.. include:: /_includes/all.rst + +********************** +Devilbox documentation +********************** + +|img_banner| The Devilbox is a modern dockerized LAMP and MEAN stack for local development on Linux, MacOS and Windows. @@ -19,91 +22,102 @@ host is ready to be served with your custom domain. .. important:: :ref:`read_first` - Ensure you have read this document to understand how this documentation works. + Ensure you have read this document to understand how this documentation works. .. toctree:: :maxdepth: 2 - :caption: About - about/read-first - about/features + read-first + features + devilbox-purpose + .. toctree:: + :caption: Getting started :maxdepth: 2 :numbered: - :caption: Getting started + getting-started/prerequisites getting-started/install-the-devilbox - getting-started/update-the-devilbox getting-started/start-the-devilbox + getting-started/devilbox-intranet getting-started/directory-overview getting-started/create-your-first-project - getting-started/read-log-files - getting-started/email-catch-all getting-started/enter-the-php-container - getting-started/the-intranet - getting-started/best-practice + getting-started/change-container-versions + + +.. toctree:: + :caption: Intermediate + :maxdepth: 2 + :numbered: + + intermediate/setup-auto-dns + intermediate/setup-valid-https + intermediate/configure-php-xdebug + intermediate/enable-disable-php-modules + intermediate/read-log-files + intermediate/email-catch-all + intermediate/add-custom-environment-variables + intermediate/work-inside-the-php-container + intermediate/source-code-analysis + intermediate/best-practice + + +.. toctree:: + :caption: Advanced + :maxdepth: 2 + :numbered: + + advanced/customize-php-globally + advanced/customize-webserver-globally + advanced/connect-to-host-os + advanced/connect-to-other-docker-container + advanced/connect-to-external-hosts + advanced/add-custom-cname-records + advanced/add-your-own-docker-image + advanced/overwrite-existing-docker-image + + +.. toctree:: + :caption: vhost-gen + :maxdepth: 2 + :numbered: + + vhost-gen/customize-specific-virtual-host + vhost-gen/example-add-subdomains +.. + vhost-gen/customize-all-virtual-hosts-globally + + +.. toctree:: + :caption: Corporate Usage + :maxdepth: 2 + :numbered: + + corporate-usage/shared-devilbox-server-in-lan + corporate-usage/use-external-databases +.. + corporate-usage/deploy-devilbox-via-ansible + corporate-usage/access-colleagues-devilbox + corporate-usage/access-devilbox-from-android + corporate-usage/access-devilbox-from-iphone .. toctree:: :caption: Maintenance :maxdepth: 2 + maintenance/checkout-different-devilbox-release + maintenance/remove-stopped-container + maintenance/update-the-devilbox + maintenance/remove-the-devilbox maintenance/backup-and-restore-mysql maintenance/backup-and-restore-pgsql maintenance/backup-and-restore-mongo -.. toctree:: - :maxdepth: 2 - :caption: Tutorials - - tutorials/communicating-with-external-hosts - tutorials/add-your-own-docker-image - tutorials/overwrite-existing-docker-image - tutorials/adding-subdomains - tutorials/change-container-versions - tutorials/work-inside-the-container - tutorials/enable-xdebug - tutorials/custom-environment-variables - tutorials/static-code-analysis - - -.. toctree:: - :maxdepth: 2 - :caption: Examples - - examples/setup-cakephp - examples/setup-codeigniter - examples/setup-drupal - examples/setup-joomla - examples/setup-laravel - examples/setup-phalcon - examples/setup-photon-cms - examples/setup-symfony - examples/setup-wordpress - examples/setup-yii - examples/setup-zend - examples/setup-other-frameworks - - -.. toctree:: - :caption: Project configuration - :maxdepth: 2 - - configuration-project/dns-records - configuration-project/custom-vhost - - -.. toctree:: - :caption: Global configuration - :maxdepth: 2 - - configuration-global/https-ssl - configuration-global/auto-dns - - .. toctree:: :caption: Configuration files :maxdepth: 2 @@ -120,27 +134,40 @@ host is ready to be served with your custom domain. .. toctree:: - :caption: Readings :maxdepth: 2 + :caption: Examples - installation/docker-installation - installation/docker-toolbox - readings/available-container - readings/available-tools - readings/remove-stopped-container - readings/syncronize-container-permissions + examples/setup-cakephp + examples/setup-codeigniter + examples/setup-drupal + examples/setup-joomla + examples/setup-laravel + examples/setup-phalcon + examples/setup-photon-cms + examples/setup-shopware + examples/setup-symfony + examples/setup-typo3 + examples/setup-wordpress + examples/setup-yii + examples/setup-zend + examples/setup-other-frameworks .. toctree:: - :caption: Advanced + :caption: Readings :maxdepth: 2 + readings/syncronize-container-permissions + readings/available-container + readings/available-tools + .. toctree:: :caption: Support - :maxdepth: 2 + :maxdepth: 1 - support/faq - support/troubleshooting - support/blogs-videos-and-use-cases support/artwork + support/blogs-videos-and-use-cases + support/troubleshooting + support/faq + support/howto diff --git a/docs/installation/docker-installation.rst b/docs/installation/docker-installation.rst deleted file mode 100644 index afca6c28..00000000 --- a/docs/installation/docker-installation.rst +++ /dev/null @@ -1,72 +0,0 @@ -************************* -Docker and Docker Compose -************************* - -This section gives you some detail about installing ``Docker`` and ``Docker Compose`` on your -operating system. - -.. contents:: :local: - -.. _install_docker: - -Install Docker -============== - -.. seealso:: - :ref:`docker_toolbox` - Note, this section refers to **native Docker**, which is the recommended version. If however, - you need to install **Docker Toolbox** (such as on Windows 7 or older Macs), have a look at this page. - -.. warning:: - The minimum required ``Docker`` version is ``1.12.0``. Make sure not to install older versions. - - -Docker on Linux ---------------- - -Refer to the official `Docker for Linux documentation `_ for how to install ``Docker`` on your specific Linux distribution. - -Docker on Windows ------------------ - -Refer to the official `Docker for Windows documentation `_ for how to install ``Docker`` on Windows. - -Docker on MacOS ---------------- - -Refer to the official `Docker for Mac documentation `_ for how to install ``Docker`` on MacOS. - -``docker`` user group ---------------------- - -Docker itself requires super user privileges which is granted to a system wide group -called ``docker``. After having installed Docker on your system, ensure that your local -user is assigned to the ``docker`` group. Check this via ``groups`` or ``id`` command. - - -.. code-block:: bash - - host> id - - uid=1000(cytopia) gid=1000(cytopia) groups=1000(cytopia),999(docker) - - - -.. _install_docker_compose: - -Install Docker Compose -====================== - -.. warning:: - The minimum required ``Docker Compose`` version is ``1.9.0``. Make sure not to install older versions. - -The Docker documentation provides various ways to install ``Docker Compose`` for all supported -operating systems and is quite extensive and straight forward. -Follow their steps here: `Install Docker Compose `_. - -Checklist -========= - -1. ``Docker`` is installed at the minimum required version -2. Your user is part of the ``docker`` group -3. ``Docker Compose`` is installed at the minimum required version diff --git a/docs/installation/docker-toolbox.rst b/docs/installation/docker-toolbox.rst deleted file mode 100644 index 059c42ee..00000000 --- a/docs/installation/docker-toolbox.rst +++ /dev/null @@ -1,93 +0,0 @@ -.. _docker_toolbox: - -************** -Docker Toolbox -************** - -.. contents:: :local: - - -Installation -============ - -.. warning:: - The minimum required ``Docker Toolbox`` version is ``1.12.0``. Make sure not to install older versions. - -Docker Toolbox on Windows -------------------------- - -Refer to the official `Docker Toolbox on Windows documentation `_ for how to install ``Docker Toolbox`` on Windows. - -Docker Toolbox on MacOS -------------------------- - -Refer to the official `Docker Toolbox on MacOS documentation `_ for how to install ``Docker Toolbox`` on MacOS. - -Docker Compose --------------- - -When installing ``Docker Compose``, make sure you do that **inside the virtual machine**. - -.. seealso:: - :ref:`install_docker_compose` - Have a look at this page to help you install ``Docker Compose`` for your operating system. - - -Additional steps -================ - -``Docker Toolbox`` is a legacy solution to bring ``Docker`` to systems which don't natively support -Docker itself. This is achieved by starting a virtualized Linux (e.g.: on VirtualBox) and have Docker -run inside. - -You don't have to take care about setting up the virtual machine, this is done automatically with the provided -setup file (Windows and MacOS). - -This however has several disadvantages as the forwarded Docker ports are only visible inside the -virtualized Linux and not on the host computer. Therefore the web server port cannot be reached on -your host machine and you are not able to view any projects. - -Listening address ------------------ - -First thing you need to make sure is that the ``LOCAL_LISTEN_ADDR`` variable from your ``.env`` file is -empty. When it is empty all services bind to all IP addresses inside the virtual machine and thus -being able to be seen from outside (your host operating system). - - -You can verifiy that the variable is actually empty by checking your ``.env`` file: - -.. code-block:: bash - - host> grep ^LOCAL_LISTEN_ADDR .env - - LOCAL_LISTEN_ADDR= - -Port forwarding ---------------- - -Additionally I would suggest that you port-forward the virtual machines port 80 (which itself -points to the docker container inside) to your host computers ``127.0.0.1`` address. This way you -can reach the devilbox via ``http://127.0.0.1`` or ``http://localhost``. - -If you do not port-forward it to your host machines localhost, you will have to adjust all project -DNS entries that are described in this documentation to go to ``127.0.0.1`` to the IP address of -your virtual machine. - -.. _docker_toolbox_auto_dns: - -Auto-DNS --------- - -I am currently not aware that Auto-DNS will work with ``Docker Toolbox``. If you are willing to -spent some time there, let me know. There is currently an open ticket which is addressing this: -https://github.com/cytopia/devilbox/issues/101 - - - -Checklist -========= - -1. ``Docker Toolbox`` is installed at minimum required version -2. ``Docker Compose`` is installed inside the virtual machine at minimum required version -3. ``LOCAL_LISTEN_ADDR`` is empty in the ``.env`` file diff --git a/docs/tutorials/custom-environment-variables.rst b/docs/intermediate/add-custom-environment-variables.rst similarity index 90% rename from docs/tutorials/custom-environment-variables.rst rename to docs/intermediate/add-custom-environment-variables.rst index 4e8e1d9d..20e8dfe1 100644 --- a/docs/tutorials/custom-environment-variables.rst +++ b/docs/intermediate/add-custom-environment-variables.rst @@ -1,8 +1,8 @@ -.. _tutorial_custom_environment_variables: +.. _add_custom_environment_variables: -**************************** -Custom environment variables -**************************** +******************************** +Add custom environment variables +******************************** If your application requires a variable to determine if it is run under development or production, you can easily add it and make PHP aware of it. diff --git a/docs/getting-started/best-practice.rst b/docs/intermediate/best-practice.rst similarity index 85% rename from docs/getting-started/best-practice.rst rename to docs/intermediate/best-practice.rst index e9a20185..96d2a7ac 100644 --- a/docs/getting-started/best-practice.rst +++ b/docs/intermediate/best-practice.rst @@ -1,12 +1,11 @@ -.. _getting_started_best_practice: +.. _best_practice: ************* Best practice ************* -If you have already read all documents in the Getting started guide, you should be ready to fully -operate the Devilbox. This section builds on top of that and gives you some best-practices as well -as tips and tricks. +If you have already operate the Devilbox, this guide is a must have. It will cover common +best-practice topics as well as some tips and tricks you will want to apply. **Table of Contents** @@ -29,30 +28,9 @@ where you want to store your projects. Projects -------- -So let's assume all of your projects are already in place under ``/home/user/workspace/web/``. Now -you decide to use the Devilbox, but still want to keep your projects where they are at the moment. - -All you have to to is to adjust the path of :ref:`env_httpd_datadir` in the ``.env`` file. - -.. code-block:: bash - - # Navigate to Devilbox git directory - host> cd path/to/devilbox - - # Open the .env file with your favourite editor - host> vim .env - -Now Adjust the value of :ref:`env_httpd_datadir` - -.. code-block:: bash - :caption: .env - :emphasize-lines: 1 - - HOST_PATH_HTTPD_DATADIR=/home/user/workspace/web - -That's it, whenever you start up the Devilbox ``/home/user/workspace/web/`` will be mounted into -the PHP and the web server container into ``/shared/httpd/``. - +.. seealso:: + :ref:`howto_move_projects_to_a_different_directory` + Follow this guide to keep your projects separated from the Devilbox git directory. Databases --------- @@ -229,7 +207,7 @@ or IP address of the MySQL server to ``127.0.0.1``: mysql_pass = 'somepassword'; ?> -.. seealso:: :ref:`tutorial_work_inside_the_php_container` +.. seealso:: :ref:`work_inside_the_php_container` Timezone diff --git a/docs/intermediate/configure-php-xdebug.rst b/docs/intermediate/configure-php-xdebug.rst new file mode 100644 index 00000000..d8354993 --- /dev/null +++ b/docs/intermediate/configure-php-xdebug.rst @@ -0,0 +1,101 @@ +.. _configure_php_xdebug: + +******************** +Configure PHP Xdebug +******************** + +This section explains in depth how to enable and use PHP Xdebug with the Devilbox. + + +**Table of Contents** + +.. contents:: :local: + + +Introduction +============ + +In order to have a working Xdebug, you need to ensure two things: + +1. **PHP Xdebug** must be configured and enabled in PHP itself +2. Your **IDE/editor** must be configured and requires a way talk to PHP + +Configuring PHP Xdebug will slightly differ when configuring it for a dockerized environment. +This is due to the fact that Docker versions on different host os have varying implementations of +how they connect back to the host. + +Most IDE or editors will also require different configurations for how they talk to PHP Xdebug. +This is at least most likely the case for ``xdebug.idekey``. + + +Configure PHP container for Xdebug +================================== + +.. toctree:: + :glob: + :maxdepth: 1 + :hidden: + + /intermediate/configure-php-xdebug/php-xdebug-options + /intermediate/configure-php-xdebug/xdebug-* + +The following gives you a step-by-step guide on how to setup PHP Xdebug for the Devilbox depending +on what host operating system you are using. + +Be reminded that PHP configuration is always done per version, i.e. having it configured for +PHP 7.2, does not enable it for any other versions. + +.. seealso:: + * :ref:`configure_php_xdebug_options` + * :ref:`configure_php_xdebug_lin` + * :ref:`configure_php_xdebug_mac` + * :ref:`configure_php_xdebug_win` + * :ref:`configure_php_xdebug_docker_toolbox` (Mac or Windows) + + +Configure your IDE/editor for Xdebug +==================================== + +After you have setup PHP Xdebug as referenced above, you can continue to configure your currently +used IDE/editor. + +Most IDE/editors will usually be configured in a very similar way, which comes down to two main +settings; + +Path mapping +------------ + +The path mapping is a mapping between the file path on your host operating system and the one +inside the PHP Docker container. + +The path on your host operating system is the one you have set in :ref:`env_httpd_datadir`. +In case you have set a relative path in ``.env``, ensure to retrieve the absolute path of it when +setting up your IDE config. + +The path inside the PHP Docker container is always ``/shared/httpd``. + +.. important:: + Even though your path in ``.env`` for :ref:`env_httpd_datadir` might be relative (e.g. ``./data/www``), + you need to get the actualy absolute path of it, when setting up your IDE. + +IDE key +------- +This is the value you have set in ``xdebug.ini`` for ``xdebug.idekey``. In the example of this +tutorial, the value was set to ``PHPSTORM``. + + +.. toctree:: + :glob: + :maxdepth: 1 + :hidden: + + /intermediate/configure-php-xdebug/editor-* + +Configuration +------------- + +.. seealso:: + * :ref:`configure_php_xdebug_editor_atom` + * :ref:`configure_php_xdebug_editor_phpstorm` + * :ref:`configure_php_xdebug_editor_sublime3` + * :ref:`configure_php_xdebug_editor_vscode` diff --git a/docs/intermediate/configure-php-xdebug/editor-atom.rst b/docs/intermediate/configure-php-xdebug/editor-atom.rst new file mode 100644 index 00000000..c80b7d10 --- /dev/null +++ b/docs/intermediate/configure-php-xdebug/editor-atom.rst @@ -0,0 +1,74 @@ +:orphan: + +.. include:: /_includes/all.rst + +.. _configure_php_xdebug_editor_atom: + +************************* +Configure Xdebug for Atom +************************* + +**Table of Contents** + +.. contents:: :local: + + +Prerequisites +============= + +Ensure that ``xdebug.idekey`` is set to ``xdebug.atom`` in your PHP Xdebug configuration. + +.. seealso:: + * :ref:`configure_php_xdebug_lin` + * :ref:`configure_php_xdebug_mac` + * :ref:`configure_php_xdebug_win` + * :ref:`configure_php_xdebug_docker_toolbox` + + +Assumption +========== + +For the sake of this example, we will assume the following paths: + ++------------------------------+------------------------------------------+ +| Directory | Path | ++==============================+==========================================+ +| Devilbox git directory | ``/home/cytopia/repo/devilbox`` | ++------------------------------+------------------------------------------+ +| :ref:`env_httpd_datadir` | ``./data/www`` | ++------------------------------+------------------------------------------+ +| Resulting local project path | ``/home/cytopia/repo/devilbox/data/www`` | ++------------------------------+------------------------------------------+ + +The **Resulting local project path** is the path where all projects are stored locally on your +host operating system. No matter what this path is, the equivalent remote path (inside the Docker +container) is always ``/shared/httpd``. + +.. important:: Remember this, when it comes to path mapping in your IDE/editor configuration. + + +Configuration +============= + +**1. Install php-debug for Atom** + + .. seealso:: |ext_lnk_xdebug_ide_atom_php_debug| + +**2. Configure path mapping in config.cson or ui** + + .. code-block:: js + :caption: config.cson + :emphasize-lines: 6 + + "php-debug": + { + ServerPort: 9000 + PathMaps: [ + "remotepath;localpath" + "/shared/httpd;/home/cytopia/repo/devilbox/data/www" + ] + } + + .. important:: + On Windows you have to use ``\\`` as directory separators for the local path mapping. + E.g.: ``C:\\Users\\projects``. diff --git a/docs/intermediate/configure-php-xdebug/editor-phpstorm.rst b/docs/intermediate/configure-php-xdebug/editor-phpstorm.rst new file mode 100644 index 00000000..74213037 --- /dev/null +++ b/docs/intermediate/configure-php-xdebug/editor-phpstorm.rst @@ -0,0 +1,69 @@ +:orphan: + +.. include:: /_includes/all.rst + +.. _configure_php_xdebug_editor_phpstorm: + +***************************** +Configure Xdebug for PhpStorm +***************************** + +**Table of Contents** + +.. contents:: :local: + + +Prerequisites +============= + +Ensure that ``xdebug.idekey`` is set to ``PHPSTORM`` in your PHP Xdebug configuration. + +.. seealso:: + * :ref:`configure_php_xdebug_lin` + * :ref:`configure_php_xdebug_mac` + * :ref:`configure_php_xdebug_win` + * :ref:`configure_php_xdebug_docker_toolbox` + + +Assumption +========== + +For the sake of this example, we will assume the following paths: + ++------------------------------+------------------------------------------+ +| Directory | Path | ++==============================+==========================================+ +| Devilbox git directory | ``/home/cytopia/repo/devilbox`` | ++------------------------------+------------------------------------------+ +| :ref:`env_httpd_datadir` | ``./data/www`` | ++------------------------------+------------------------------------------+ +| Resulting local project path | ``/home/cytopia/repo/devilbox/data/www`` | ++------------------------------+------------------------------------------+ + +The **Resulting local project path** is the path where all projects are stored locally on your +host operating system. No matter what this path is, the equivalent remote path (inside the Docker +container) is always ``/shared/httpd``. + +.. important:: Remember this, when it comes to path mapping in your IDE/editor configuration. + + +Configuration +============= + +**1. Ensure Xdebug port is set to 9000** + + .. include:: /_includes/figures/xdebug/phpstorm-settings.rst + +**2. Set path mapping** + + Create a new PHP server and set a path mapping. This tutorial assumes your local Devilbox projects + to be in ``./data/www`` of the Devilbox git directory: + + .. include:: /_includes/figures/xdebug/phpstorm-path-mapping.rst + + .. important:: + Recall the path mapping! + +**3. Ensure DBGp proxy settings are configured** + + .. include:: /_includes/figures/xdebug/phpstorm-dbgp-proxy.rst diff --git a/docs/intermediate/configure-php-xdebug/editor-sublime3.rst b/docs/intermediate/configure-php-xdebug/editor-sublime3.rst new file mode 100644 index 00000000..c7add5e6 --- /dev/null +++ b/docs/intermediate/configure-php-xdebug/editor-sublime3.rst @@ -0,0 +1,79 @@ +:orphan: + +.. include:: /_includes/all.rst + +.. _configure_php_xdebug_editor_sublime3: + +*********************************** +Configure Xdebug for Sublime Text 3 +*********************************** + +**Table of Contents** + +.. contents:: :local: + + +Prerequisites +============= + +Ensure that ``xdebug.idekey`` is set to ``PHPSTORM`` in your PHP Xdebug configuration. + +.. seealso:: + * :ref:`configure_php_xdebug_lin` + * :ref:`configure_php_xdebug_mac` + * :ref:`configure_php_xdebug_win` + * :ref:`configure_php_xdebug_docker_toolbox` + + +Assumption +========== + +For the sake of this example, we will assume the following paths: + ++------------------------------+------------------------------------------+ +| Directory | Path | ++==============================+==========================================+ +| Devilbox git directory | ``/home/cytopia/repo/devilbox`` | ++------------------------------+------------------------------------------+ +| :ref:`env_httpd_datadir` | ``./data/www`` | ++------------------------------+------------------------------------------+ +| Resulting local project path | ``/home/cytopia/repo/devilbox/data/www`` | ++------------------------------+------------------------------------------+ + +The **Resulting local project path** is the path where all projects are stored locally on your +host operating system. No matter what this path is, the equivalent remote path (inside the Docker +container) is always ``/shared/httpd``. + +.. important:: Remember this, when it comes to path mapping in your IDE/editor configuration. + + +Configuration +============= + +**1. Install Xdebug Client** + + Use Sublime's Package Control to search for and install ``Xdebug Client``. + + .. seealso:: |ext_lnk_xdebug_ide_sublime_xdebug_client| + +**2. Configure Xdebug.sublime-settings** + + * Navigate to ``Tools`` -> ``Xdebug`` -> ``Settings - User`` in the menu + * This will open the configuration file in Sublime + + .. code-block:: json + :caption: Xdebug-sublime-settings + :emphasize-lines: 3,6 + + { + "path_mapping": { + "/shared/httpd" : "/home/cytopia/repo/devilbox/data/www" + }, + "url": "", + "ide_key": "PHPSTORM", + "host": "0.0.0.0", + "port": 9000 + } + + .. important:: + Recall the path mapping! diff --git a/docs/intermediate/configure-php-xdebug/editor-vscode.rst b/docs/intermediate/configure-php-xdebug/editor-vscode.rst new file mode 100644 index 00000000..6fb4b7d8 --- /dev/null +++ b/docs/intermediate/configure-php-xdebug/editor-vscode.rst @@ -0,0 +1,86 @@ +:orphan: + +.. include:: /_includes/all.rst + +.. _configure_php_xdebug_editor_vscode: + +*************************************** +Configure Xdebug for Visual Studio Code +*************************************** + +**Table of Contents** + +.. contents:: :local: + + +Prerequisites +============= + +Ensure that ``xdebug.idekey`` is set to ``PHPSTORM`` in your PHP Xdebug configuration. + +.. seealso:: + * :ref:`configure_php_xdebug_lin` + * :ref:`configure_php_xdebug_mac` + * :ref:`configure_php_xdebug_win` + * :ref:`configure_php_xdebug_docker_toolbox` + + +Assumption +========== + +For the sake of this example, we will assume the following paths: + ++------------------------------+------------------------------------------+ +| Directory | Path | ++==============================+==========================================+ +| Devilbox git directory | ``/home/cytopia/repo/devilbox`` | ++------------------------------+------------------------------------------+ +| :ref:`env_httpd_datadir` | ``./data/www`` | ++------------------------------+------------------------------------------+ +| Resulting local project path | ``/home/cytopia/repo/devilbox/data/www`` | ++------------------------------+------------------------------------------+ + +The **Resulting local project path** is the path where all projects are stored locally on your +host operating system. No matter what this path is, the equivalent remote path (inside the Docker +container) is always ``/shared/httpd``. + +.. important:: Remember this, when it comes to path mapping in your IDE/editor configuration. + + +Configuration +============= + +**1. Install vscode-php-debug** + + + .. seealso:: |ext_lnk_xdebug_ide_vscode_php_debug| + +**2. Configure launch.json** + + .. code-block:: json + :caption: launch.json + :emphasize-lines: 9,10 + + { + "version": "0.2.0", + "configurations": [ + { + "name": "Listen for Xbebug", + "type": "php", + "request": "launch", + "port": 9000, + "serverSourceRoot": "/shared/httpd", + "localSourceRoot": "/home/cytopia/repo/devilbox/data/www" + }, { + "name": "Launch currently open script", + "type": "php", + "request": "launch", + "program": "${file}", + "cwd": "${fileDirname}", + "port": 9000 + } + ] + } + + .. important:: + Recall the path mapping! diff --git a/docs/intermediate/configure-php-xdebug/php-xdebug-options.rst b/docs/intermediate/configure-php-xdebug/php-xdebug-options.rst new file mode 100644 index 00000000..bd69ee0f --- /dev/null +++ b/docs/intermediate/configure-php-xdebug/php-xdebug-options.rst @@ -0,0 +1,80 @@ +:orphan: + +.. include:: /_includes/all.rst + +.. _configure_php_xdebug_options: + +************************ +Xdebug options explained +************************ + +**Table of Contents** + +.. contents:: :local: + + +Example +======= + +Consider the following ``xdebug.ini`` as an example: + +.. code-block:: ini + :caption: xdebug.ini + + xdebug.default_enable=1 + xdebug.remote_enable=1 + xdebug.remote_handler=dbgp + xdebug.remote_port=9000 + xdebug.remote_autostart=1 + xdebug.idekey="PHPSTORM" + xdebug.remote_log=/var/log/php/xdebug.log + +.. seealso:: |ext_lnk_xdebug_settings| + +default_enable +-------------- +By enabling this, stacktraces will be shown by default on an error event. +It is advisable to leave this setting set to 1. + +remote_enable +------------- +This switch controls whether Xdebug should try to contact a debug client which is listening on the +host and port as set with the settings ``xdebug.remote_host`` and ``xdebug.remote_port``. +If a connection can not be established the script will just continue as if this setting was 0. + +remote_handler +-------------- +Can be either ``'php3'`` which selects the old PHP 3 style debugger output, ``'gdb'`` which enables +the GDB like debugger interface or ``'dbgp'`` - the debugger protocol. The DBGp protocol is the only +supported protocol. + +**Note:** Xdebug 2.1 and later only support ``'dbgp'`` as protocol. + +remote_port +----------- +The port to which Xdebug tries to connect on the remote host. Port ``9000`` is the default for both +the client and the bundled debugclient. As many clients use this port number, it is best to leave +this setting unchanged. + +remote_autostart +---------------- +Normally you need to use a specific HTTP GET/POST variable to start remote debugging (see +|ext_lnk_xdebug_remote_debugging|). When this setting is set to ``1``, Xdebug will always attempt +to start a remote debugging session and try to connect to a client, even if the GET/POST/COOKIE +variable was not present. + +idekey +------ +Controls which IDE Key Xdebug should pass on to the DBGp debugger handler. The default is based on +environment settings. First the environment setting DBGP_IDEKEY is consulted, then USER and as last +USERNAME. The default is set to the first environment variable that is found. If none could be found +the setting has as default ''. If this setting is set, it always overrides the environment variables. + +.. important:: + Many IDE/editors require a specific value for ``xdebug.idekey``. Make sure you pay + special attention to that variable when it comes to configuring your IDE/editor. + +remote_log +---------- +Keep the exact path of ``/var/log/php/xdebug.log``. You will then have the log file available +in the Devilbox log directory of the PHP version for which you have configured Xdebug. diff --git a/docs/intermediate/configure-php-xdebug/xdebug-docker-toolbox.rst b/docs/intermediate/configure-php-xdebug/xdebug-docker-toolbox.rst new file mode 100644 index 00000000..aaf4a191 --- /dev/null +++ b/docs/intermediate/configure-php-xdebug/xdebug-docker-toolbox.rst @@ -0,0 +1,99 @@ +:orphan: + +.. include:: /_includes/all.rst + +.. _configure_php_xdebug_docker_toolbox: + +******************************** +Configure Xdebug: Docker Toolbox +******************************** + +Docker Toolbox regardless of running on MacOS or Windows requires an additional port-forward +from your host operating system to the Docker Toolbox machine. + +**Table of Contents** + +.. contents:: :local: + + +Prerequisites +============= + +Ensure you know how to customize ``php.ini`` values for the Devilbox. + +.. seealso:: + * :ref:`php_ini` + * :ref:`configure_php_xdebug_options` + + +Configure php.ini +================= + +The following example show how to configure PHP Xdebug for PHP 5.6: + +**1. Forward host port 9000 to Docker Toolbox machine** + + Your IDE/editor will open up port ``9000`` on your host operating system. PHP Xdebug requires + this port to connect to in order to send Xdebug events. + As Docker Toolbox itself runs in a virtual machine, you need to forward traffic from the same + port in that virtual machine back to your host operating system. + + .. seealso:: + * :ref:`howto_ssh_port_forward_on_docker_toolbox_from_host` + * :ref:`howto_ssh_port_forward_on_host_to_docker_toolbox` + +**2. Create xdebug.ini** + + .. code-block:: bash + + # Navigate to the Devilbox git directory + host> cd path/to/devilbox + + # Navigate to PHP 5.6 ini configuration directory + host> cd cfg/php-ini-5.6/ + + # Create and open debug.ini file + host> vi xdebug.ini + +**3. Paste the following content into xdebug.ini** + + Once the por-forward is up, the configuration matches the one for Docker on Linux + + .. seealso:: + * CNAME for :ref:`connect_to_host_os_docker_on_linux` + + .. code-block:: ini + :caption: xdebug.ini + :emphasize-lines: 6-7,11 + + # Defaults + xdebug.remote_enable=1 + xdebug.remote_port=9000 + + # The Docker Toolbox way + xdebug.remote_connect_back=0 + xdebug.remote_host=docker.for.lin.host.internal + + # idekey value is specific to each editor + # Verify with your IDE/editor documentation + xdebug.idekey=PHPSTORM + + # Optional: Set to true to auto-start xdebug + xdebug.remote_autostart=false + +**4. Configure your IDE/editor** + + .. seealso:: + * :ref:`configure_php_xdebug_editor_atom` + * :ref:`configure_php_xdebug_editor_phpstorm` + * :ref:`configure_php_xdebug_editor_sublime3` + * :ref:`configure_php_xdebug_editor_vscode` + + .. important:: + Depending on your IDE/editor, you might have to adjust ``xdebug.idekey`` in the above + configured ``xdebug.ini``. + + +**5. Restart the Devilbox** + + Restarting the Devilbox is important in order for it to read the new PHP settings. diff --git a/docs/intermediate/configure-php-xdebug/xdebug-lin.rst b/docs/intermediate/configure-php-xdebug/xdebug-lin.rst new file mode 100644 index 00000000..895490ea --- /dev/null +++ b/docs/intermediate/configure-php-xdebug/xdebug-lin.rst @@ -0,0 +1,85 @@ +:orphan: + +.. include:: /_includes/all.rst + +.. _configure_php_xdebug_lin: + +********************************* +Configure Xdebug: Docker on Linux +********************************* + +Docker on Linux allows Xdebug to automatically connect back to the host system without the need +of an explicit IP address. + +**Table of Contents** + +.. contents:: :local: + + +Prerequisites +============= + +Ensure you know how to customize ``php.ini`` values for the Devilbox. + +.. seealso:: + * :ref:`php_ini` + * :ref:`configure_php_xdebug_options` + + +Configure php.ini +================= + +Configuring Xdebug for Docker on Linux is straight forward and you must only pay attention to +two variables highlighted below. + +The following example show how to configure PHP Xdebug for PHP 5.6: + +**1. Create xdebug.ini** + + .. code-block:: bash + + # Navigate to the Devilbox git directory + host> cd path/to/devilbox + + # Navigate to PHP 5.6 ini configuration directory + host> cd cfg/php-ini-5.6/ + + # Create and open debug.ini file + host> vi xdebug.ini + +**2. Paste the following content into xdebug.ini** + + .. code-block:: ini + :caption: xdebug.ini + :emphasize-lines: 6,10 + + # Defaults + xdebug.remote_enable=1 + xdebug.remote_port=9000 + + # The Linux way + xdebug.remote_connect_back=1 + + # idekey value is specific to each editor + # Verify with your IDE/editor documentation + xdebug.idekey=PHPSTORM + + # Optional: Set to true to auto-start xdebug + xdebug.remote_autostart=false + +**3. Configure your IDE/editor** + + .. seealso:: + * :ref:`configure_php_xdebug_editor_atom` + * :ref:`configure_php_xdebug_editor_phpstorm` + * :ref:`configure_php_xdebug_editor_sublime3` + * :ref:`configure_php_xdebug_editor_vscode` + + .. important:: + Depending on your IDE/editor, you might have to adjust ``xdebug.idekey`` in the above + configured ``xdebug.ini``. + + +**4. Restart the Devilbox** + + Restarting the Devilbox is important in order for it to read the new PHP settings. diff --git a/docs/intermediate/configure-php-xdebug/xdebug-mac.rst b/docs/intermediate/configure-php-xdebug/xdebug-mac.rst new file mode 100644 index 00000000..2767500d --- /dev/null +++ b/docs/intermediate/configure-php-xdebug/xdebug-mac.rst @@ -0,0 +1,173 @@ +:orphan: + +.. include:: /_includes/all.rst + +.. _configure_php_xdebug_mac: + +******************************** +Configure Xdebug: Docker for Mac +******************************** + +Docker for MacOS requires a well known IP address in order to connect to the host operating system. +This can be achieved with two different approaches described below. + +.. seealso:: https://forums.docker.com/t/ip-address-for-xdebug/10460/32 + + +**Table of Contents** + +.. contents:: :local: + + +Prerequisites +============= + +Ensure you know how to customize ``php.ini`` values for the Devilbox and Xdebug is enabled. + +.. seealso:: + * :ref:`php_ini` + * :ref:`configure_php_xdebug_options` + + +Configure php.ini: CNAME alias +============================== + +**Option 1:** This option is the easiest to setup, but was also very fragile on many Docker versions. + +Docker for Mac received many default CNAMEs throughout its versions. The most recent and active +one is ``host.docker.internal``. Use this CNAME as the remote address for Xdebug to connect to your +IDE/editor on your host os. + +.. seealso:: + CNAME for :ref:`connect_to_host_os_docker_for_mac` + In case ``host.docker.internal`` is not resolvable, read on here for alternative CNAME's + on Docker for Mac + +.. important:: + + Before you try this approach, verify that the PHP Docker container is actually able to resolve + ``host.docker.internal``: + + .. code-block:: bash + + host> cd path/to/devilbox + host> ./shell.sh + php> ping host.docker.internal + + In case it is not resolvable, stick to the host alias address approach. + +The following example show how to configure PHP Xdebug for PHP 5.6: + +**1. Create xdebug.ini** + + .. code-block:: bash + + # Navigate to the Devilbox git directory + host> cd path/to/devilbox + + # Navigate to PHP 5.6 ini configuration directory + host> cd cfg/php-ini-5.6/ + + # Create and open debug.ini file + host> vi xdebug.ini + +**2. Paste the following content into xdebug.ini** + + .. code-block:: ini + :caption: xdebug.ini + :emphasize-lines: 6-7,11 + + # Defaults + xdebug.remote_enable=1 + xdebug.remote_port=9000 + + # The MacOS way (CNAME) + xdebug.remote_connect_back=0 + xdebug.remote_host=host.docker.internal + + # idekey value is specific to each editor + # Verify IDE/editor documentation + xdebug.idekey=PHPSTORM + + # Optional: Set to true to auto-start xdebug + xdebug.remote_autostart=false + +**3. Configure your IDE/editor** + + .. seealso:: + * :ref:`configure_php_xdebug_editor_atom` + * :ref:`configure_php_xdebug_editor_phpstorm` + * :ref:`configure_php_xdebug_editor_sublime3` + * :ref:`configure_php_xdebug_editor_vscode` + + .. important:: + Depending on your IDE/editor, you might have to adjust ``xdebug.idekey`` in the above + configured ``xdebug.ini``. + + +**4. Restart the Devilbox** + + Restarting the Devilbox is important in order for it to read the new PHP settings. + +Configure php.ini: Host alias +============================= + +**Option 2:** This is the most general option that should work with any Docker version on MacOS, +it does however require a few changes in your system. + +.. important:: + Ensure you have created an :ref:`howto_host_address_alias_on_mac` and + ``10.254.254.254`` is aliased to your localhost. + +The following example show how to configure PHP Xdebug for PHP 5.6: + +**1. Create xdebug.ini** + + .. code-block:: bash + + # Navigate to the Devilbox git directory + host> cd path/to/devilbox + + # Navigate to PHP 5.6 ini configuration directory + host> cd cfg/php-ini-5.6/ + + # Create and open debug.ini file + host> vi xdebug.ini + +**2. Paste the following content into xdebug.ini** + + .. code-block:: ini + :caption: xdebug.ini + :emphasize-lines: 6-7,11 + + # Defaults + xdebug.remote_enable=1 + xdebug.remote_port=9000 + + # The MacOS way (host alias) + xdebug.remote_connect_back=0 + xdebug.remote_host=10.254.254.254 + + # idekey value is specific to each editor + # Verify with your IDE/editor documentation + xdebug.idekey=PHPSTORM + + # Optional: Set to true to auto-start xdebug + xdebug.remote_autostart=false + +**3. Configure your IDE/editor** + + .. seealso:: + * :ref:`configure_php_xdebug_editor_atom` + * :ref:`configure_php_xdebug_editor_phpstorm` + * :ref:`configure_php_xdebug_editor_sublime3` + * :ref:`configure_php_xdebug_editor_vscode` + + .. important:: + Depending on your IDE/editor, you might have to adjust ``xdebug.idekey`` in the above + configured ``xdebug.ini``. + + +**4. Restart the Devilbox** + + Restarting the Devilbox is important in order for it to read the new PHP settings. diff --git a/docs/intermediate/configure-php-xdebug/xdebug-win.rst b/docs/intermediate/configure-php-xdebug/xdebug-win.rst new file mode 100644 index 00000000..5095ca56 --- /dev/null +++ b/docs/intermediate/configure-php-xdebug/xdebug-win.rst @@ -0,0 +1,175 @@ +:orphan: + +.. include:: /_includes/all.rst + +.. _configure_php_xdebug_win: + +************************************ +Configure Xdebug: Docker for Windows +************************************ + +Docker for Windows requires a well known IP address in order to connect to the host operating system. +This can be achieved with two different approaches described below. + +**Table of Contents** + +.. contents:: :local: + + +Prerequisites +============= + +Ensure you know how to customize ``php.ini`` values for the Devilbox and Xdebug is enabled. + +.. seealso:: + * :ref:`php_ini` + * :ref:`configure_php_xdebug_options` + + +Configure php.ini: CNAME alias +============================== + +**Option 1:** This option is the easiest to setup, but was also very fragile on many Docker versions. + +Docker for Windows received many default CNAMEs throughout its versions. The most recent and active +one is ``host.docker.internal``. Use this CNAME as the remote address for Xdebug to connect to your +IDE/editor on your host os. + +.. seealso:: + CNAME for :ref:`connect_to_host_os_docker_for_win` + In case ``host.docker.internal`` is not resolvable, read on here for alternative CNAME's + on Docker for Windows + +.. important:: + + Before you try this approach, verify that the PHP Docker container is actually able to resolve + ``host.docker.internal``: + + .. code-block:: bash + + C:\> cd path\to\devilbox + C:\> shell.bat + php> ping host.docker.internal + + In case it is not resolvable, stick to the host alias address approach. + +The following example show how to configure PHP Xdebug for PHP 5.6: + +**1. Create xdebug.ini** + + 1. Navigate to the Devilbox directory + 2. Navigate to ``cfg\php-ini-5.6\`` directory + 3. Create a new file named ``xdebug.ini`` + + .. important:: + Pay attention that windows is not adding ``.txt`` as a file extension. + +**2. Paste the following content into xdebug.ini** + + .. code-block:: ini + :caption: xdebug.ini + :emphasize-lines: 6-7,11 + + # Defaults + xdebug.remote_enable=1 + xdebug.remote_port=9000 + + # The Windows way (CNAME) + xdebug.remote_connect_back=0 + xdebug.remote_host=host.docker.internal + + # idekey value is specific to each editor + # Verify IDE/editor documentation + xdebug.idekey=PHPSTORM + + # Optional: Set to true to auto-start xdebug + xdebug.remote_autostart=false + +**3. Configure your IDE/editor** + + .. seealso:: + * :ref:`configure_php_xdebug_editor_atom` + * :ref:`configure_php_xdebug_editor_phpstorm` + * :ref:`configure_php_xdebug_editor_sublime3` + * :ref:`configure_php_xdebug_editor_vscode` + + .. important:: + Depending on your IDE/editor, you might have to adjust ``xdebug.idekey`` in the above + configured ``xdebug.ini``. + +**4. Restart the Devilbox** + + Restarting the Devilbox is important in order for it to read the new PHP settings. + + +Configure php.ini: Get IP manually +================================== + +**Option 2:** This is the most general option that should work with any Docker version on Windows. +it does however require a small manual step. + +The following example show how to configure PHP Xdebug for PHP 5.6: + +**1. Gather IP address for Xdebug** + + On Windows you will have to manually gather the IP address and add it to ``xdebug.remote_host``. + + 1. Open command line + 2. Enter ``ipconfig`` + 3. Look for the IP4 address in ``DockerNAT`` (e.g.: ``192.168.246.1``) + + .. seealso:: :ref:`howto_open_terminal_on_win` + + .. important:: + ``192.168.246.1`` is meant as an example and will eventually differ on your system. + Ensure you substitute it with the correct IP address. + +**2. Create xdebug.ini** + + 1. Navigate to the Devilbox directory + 2. Navigate to ``cfg\php-ini-5.6\`` directory + 3. Create a new file named ``xdebug.ini`` + + .. important:: + Pay attention that windows is not adding ``.txt`` as a file extension. + +**3. Paste the following content into xdebug.ini** + + .. code-block:: ini + :caption: xdebug.ini + :emphasize-lines: 6-7,11 + + # Defaults + xdebug.remote_enable=1 + xdebug.remote_port=9000 + + # The Windows way (IP address) + xdebug.remote_connect_back=0 + xdebug.remote_host=192.168.246.1 + + # idekey value is specific to each editor + # Verify IDE/editor documentation + xdebug.idekey=PHPSTORM + + # Optional: Set to true to auto-start xdebug + xdebug.remote_autostart=false + + .. important:: + ``192.168.246.1`` is meant as an example and will eventually differ on your system. + Ensure you substitute it with the correct IP address. + +**4. Configure your IDE/editor** + + .. seealso:: + * :ref:`configure_php_xdebug_editor_atom` + * :ref:`configure_php_xdebug_editor_phpstorm` + * :ref:`configure_php_xdebug_editor_sublime3` + * :ref:`configure_php_xdebug_editor_vscode` + + .. important:: + Depending on your IDE/editor, you might have to adjust ``xdebug.idekey`` in the above + configured ``xdebug.ini``. + +**5. Restart the Devilbox** + + Restarting the Devilbox is important in order for it to read the new PHP settings. diff --git a/docs/getting-started/email-catch-all.rst b/docs/intermediate/email-catch-all.rst similarity index 87% rename from docs/getting-started/email-catch-all.rst rename to docs/intermediate/email-catch-all.rst index 4c1a17de..e861915f 100644 --- a/docs/getting-started/email-catch-all.rst +++ b/docs/intermediate/email-catch-all.rst @@ -1,4 +1,4 @@ -.. _getting_started_email_catch_all: +.. _email_catch_all: *************** Email catch-all @@ -11,7 +11,7 @@ all outgoing mails and puts them into a local mailbox by the user ``devilbox``. In order to view sent emails open up the devilbox intranet http://localhost/mail.php. There you can also test email sending and verify that they really stay locally. -.. image:: /_static/img/devilbox-email-catch-all.png +.. include:: /_includes/figures/devilbox/devilbox-intranet-emails.rst In the above image from the intranet you can see that all emails sent to whatever recipient have been caught by the Devilbox and are available to be read. diff --git a/docs/intermediate/enable-disable-php-modules.rst b/docs/intermediate/enable-disable-php-modules.rst new file mode 100644 index 00000000..50ef7946 --- /dev/null +++ b/docs/intermediate/enable-disable-php-modules.rst @@ -0,0 +1,64 @@ +.. _enable_disable_php_modules: + +************************** +Enable/disable PHP modules +************************** + +**Table of Contents** + +.. contents:: :local: + +.. seealso:: + https://github.com/devilbox/docker-php-fpm#user-content-php-modules + Follow the link to see all available PHP modules for each different PHP-FPM server version. + + +Enabled PHP modules +=================== + +At the moment all PHP modules are enabled by default except `ioncube `_, +So this one is the only one you can currently enable. To do so follow the steps provided below: + +1. Stop the Devilbox +2. Enable modules in ``.env`` under ``PHP_MODULES_ENABLE`` + + .. code-block:: bash + :caption: .env + + # Enable Ioncube + PHP_MODULES_ENABLE=ioncube + +3. Start the Devilbox + +.. seealso:: :ref:`env_file_php_modules_enable` + + +Disable PHP modules +=================== + +If you feel there are currently too many modules loaded and you want to unload some of them by +default, you can do so via a comma separated list in ``.env``. + +1. Stop the Devilbox +2. Disable modules in ``.env`` under ``PHP_MODULES_DISABLE`` + + .. code-block:: bash + :caption: .env + + # Disable Xdebug, Imagick and Swoole + PHP_MODULES_DISABLE=xdebug,imagick,swoole + +3. Start the Devilbox + +.. seealso:: :ref:`env_file_php_modules_disable` + + +Roadmap +======= + +.. todo:: + In order to create a performent, secure and sane default PHP-FPM server, only really required + modules should be enabled by default. The rest is up to the user to enable others as needed. + + The current discussion about default modules can be found at the following Github issue. + Please participate and give your ideas: https://github.com/cytopia/devilbox/issues/299 diff --git a/docs/getting-started/read-log-files.rst b/docs/intermediate/read-log-files.rst similarity index 98% rename from docs/getting-started/read-log-files.rst rename to docs/intermediate/read-log-files.rst index f5f31d59..872e06c5 100644 --- a/docs/getting-started/read-log-files.rst +++ b/docs/intermediate/read-log-files.rst @@ -1,4 +1,4 @@ -.. _getting_started_read_log_files: +.. _read_log_files: ************** Read log files diff --git a/docs/intermediate/setup-auto-dns.rst b/docs/intermediate/setup-auto-dns.rst new file mode 100644 index 00000000..5400602e --- /dev/null +++ b/docs/intermediate/setup-auto-dns.rst @@ -0,0 +1,151 @@ +.. _setup_auto_dns: + +************** +Setup Auto DNS +************** + +If you don't want to add host records manually for every project, you can also use the bundled +DNS server and use it's DNS catch-all feature to have all DNS records automatically available. + +.. important:: + By default, the DNS server is set to listen on ``1053`` to avoid port collisions during startup. + You need to change it to ``53`` in ``.env`` via :ref:`env_host_port_bind`. + + +**Table of Contents** + +.. contents:: :local: + + +Native Docker +============= + +The webserver as well as the DNS server must be available on ``127.0.0.1`` or on all interfaces +on ``0.0.0.0``. Additionally the DNS server port must be set to ``53`` (it is not by default). + +* Ensure :ref:`env_local_listen_addr` is set accordingly +* Ensure :ref:`env_host_port_bind` is set accordingly +* No other DNS resolver should listen on ``127.0.0.1:53`` + + +Prerequisites +------------- + +First ensure that :ref:`env_local_listen_addr` is either empty or listening on ``127.0.0.1``. + +.. code-block:: bash + :caption: .env + :emphasize-lines: 3 + + host> cd path/to/devilbox + host> vi .env + LOCAL_LISTEN_ADDR= + +Then you need to ensure that :ref:`env_host_port_bind` is set to ``53``. + +.. code-block:: bash + :caption: .env + :emphasize-lines: 3 + + host> cd path/to/devilbox + host> vi .env + HOST_PORT_BIND=53 + +Before starting up the Devilbox, ensure that port ``53`` is not already used on ``127.0.0.1``. + +.. code-block:: bash + :emphasize-lines: 2 + + host> netstat -an | grep -E 'LISTEN\s*$' + tcp 0 0 127.0.0.1:53 0.0.0.0:* LISTEN + tcp 0 0 127.0.0.1:43477 0.0.0.0:* LISTEN + tcp 0 0 127.0.0.1:50267 0.0.0.0:* LISTEN + +If you see port ``53`` already being used as in the above example, ensure to stop any +DNS resolver, otherwise it does not work. + +The output should look like this (It is only important that there is no ``:53``. + +.. code-block:: bash + + host> netstat -an | grep -E 'LISTEN\s*$' + tcp 0 0 127.0.0.1:43477 0.0.0.0:* LISTEN + tcp 0 0 127.0.0.1:50267 0.0.0.0:* LISTEN + + +Docker on Linux +--------------- + +Your DNS server IP address is ``127.0.0.1``. + +.. seealso:: :ref:`howto_add_custom_dns_server_on_linux` + + +Docker for Mac +-------------- + +Your DNS server IP address is ``127.0.0.1``. + +.. seealso:: :ref:`howto_add_custom_dns_server_on_mac` + + +Docker for Windows +------------------ + +Your DNS server IP address is ``127.0.0.1``. + +.. seealso:: :ref:`howto_add_custom_dns_server_on_win` + + +Docker Toolbox +============== + +.. seealso:: :ref:`howto_docker_toolbox_and_the_devilbox` + +This part applies equally for Docker Toolbox on MacOS and on Windows: + +Prerequisites +------------- + +* :ref:`env_local_listen_addr` must be empty in order to listen on all interfaces +* :ref:`env_host_port_bind` must be set to ``53`` + +You need to create three port-forwards to make the DNS and web server available on your host os: + +* Port ``80`` from the Docker Toolbox virtual machine must be port-forwarded to ``127.0.0.1:80`` on your host os +* Port ``443`` from the Docker Toolbox virtual machine must be port-forwarded to ``127.0.0.1:443`` on your host os +* Port ``53`` from the Docker Toolbox virtual machine must be port-forwarded to ``127.0.0.1:53`` on your host os + +Assuming the Docker Toolbox IP is ``192.168.99.100`` your forwards must be as follows: + ++----------------+-----------+-----------+---------+ +| From IP | From port | To IP | To port | ++================+===========+===========+=========+ +| 192.168.99.100 | 53 | 127.0.0.1 | 53 | ++----------------+-----------+-----------+---------+ +| 192.168.99.100 | 80 | 127.0.0.1 | 80 | ++----------------+-----------+-----------+---------+ +| 192.168.99.100 | 443 | 127.0.0.1 | 443 | ++----------------+-----------+-----------+---------+ + +.. seealso:: + * :ref:`howto_ssh_port_forward_on_docker_toolbox_from_host` + * :ref:`howto_find_docker_toolbox_ip_address` + + +Actual setup +------------ + +.. important:: + After settings this up, follow the above guides for **Docker for Mac** or **Docker for Windows** + to finish the setup. + +.. + Access for other network devices + +.. + seealso:: + * :ref:`access_devilbox_from_android` + * :ref:`access_devilbox_from_iphone` + * :ref:`access_colleagues_devilbox` + * :ref:`shared_devilbox_server_in_lan` diff --git a/docs/configuration-global/https-ssl.rst b/docs/intermediate/setup-valid-https.rst similarity index 67% rename from docs/configuration-global/https-ssl.rst rename to docs/intermediate/setup-valid-https.rst index 8f6209ae..8729b830 100644 --- a/docs/configuration-global/https-ssl.rst +++ b/docs/intermediate/setup-valid-https.rst @@ -1,8 +1,10 @@ -.. _configuration_https_ssl: +.. include:: /_includes/all.rst -*********** -HTTPS (SSL) -*********** +.. _setup_valid_https: + +***************** +Setup valid HTTPS +***************** This page shows you how to use the Devilbox on https and how to import the Certificate Authority into your browser once, so that you always and automatically get valid SSL certificates for all new @@ -10,7 +12,7 @@ projects. SSL certificates are generated automatically and there is nothing to do from your side. -.. image:: /_static/img/global-configuration/https-ssl-address-bar.png +.. include:: /_includes/figures/https/https-ssl-address-bar.rst **Table of Contents** @@ -30,8 +32,8 @@ Certificate Authority --------------------- When the Devilbox starts up for the first time, it will generate a -`Certificate Authority `_ and will store its -public and private key in ``./ca/`` within the Devilbox git directory. +|ext_lnk_ssl_certificate_authority| and will store its public and private key in ``./ca/`` within +the Devilbox git directory. The keys are only generated if they don't exist and kept permanently if you don't delete them manually, i.e. they are not overwritten. @@ -51,7 +53,7 @@ SSL Certificates Whenever you create a new project directory, multiple things happen in the background: 1. A new virtual host is created -2. DNS is provided via :ref:`global_configuration_auto_dns` +2. DNS is provided via :ref:`setup_auto_dns` 3. A new SSL certificate is generated for that vhost 4. **The SSL certificate is signed by the Devilbox Certificate Authority** @@ -59,15 +61,15 @@ By having a SSL certificates signed by the provided CA, you will only have to im into your browser ones and all current projects and future projects will automatically have valid and trusted SSL certificates without any further work. + +Import the CA into your browser +=============================== + .. important:: Importing the CA into the browser is also recommended and required for the Devilbox intranet page to work properly. You may also import the CA into your Operating System's Keystore. Information on that - is available at `GFI Root Certificate guide `_ - - -Import the CA into your browser -=============================== + is available at |ext_lnk_ssl_gfi_root_cert_guide|. Chrome / Chromium ----------------- @@ -75,28 +77,28 @@ Chrome / Chromium Open Chrome settings, scroll down to the very bottom and click on ``Advanced`` to expand the advanced settings. -.. image:: /_static/img/global-configuration/https-ssl-01-chrome-settings.png +.. include:: /_includes/figures/https/chrome-settings.rst Find the setting ``Manage certificates`` and open it. -.. image:: /_static/img/global-configuration/https-ssl-02-chrome-advanced-settings.png +.. include:: /_includes/figures/https/chrome-advanced-settings.rst Navigate to the tab setting ``AUTHORITIES`` and click on ``IMPORT``. -.. image:: /_static/img/global-configuration/https-ssl-03-chrome-authorities.png +.. include:: /_includes/figures/https/chrome-manage-certificates.rst Select ``devilbox-ca.crt`` from within the Devilbox ``./ca`` directory: -.. image:: /_static/img/global-configuration/https-ssl-04-import.png +.. include:: /_includes/figures/https/file-manager-import-ca.rst As the last step you are asked what permissions you want to grant the newly importat CA. To make sure it works everywhere, check all options and proceed with ``OK``. -.. image:: /_static/img/global-configuration/https-ssl-05-chrome-set-trust.png +.. include:: /_includes/figures/https/chrome-set-trust.rst Now you are all set and all generated SSL certificates will be valid from now on. -.. image:: /_static/img/global-configuration/https-ssl-address-bar.png +.. include:: /_includes/figures/https/https-ssl-address-bar.rst Firefox @@ -104,28 +106,28 @@ Firefox Open Firefox settings and click on ``Privacy & Security``. -.. image:: /_static/img/global-configuration/https-ssl-01-firefox-settings.png +.. include:: /_includes/figures/https/firefox-preferences.rst At the very bottom click on the button ``View Certificates``. -.. image:: /_static/img/global-configuration/https-ssl-02-firefox-security-settings.png +.. include:: /_includes/figures/https/firefox-privacy-and-security.rst In the ``Authories`` tab, click on ``Import``. -.. image:: /_static/img/global-configuration/https-ssl-03-firefox-authorities.png +.. include:: /_includes/figures/https/firefox-certificate-manager.rst Select ``devilbox-ca.crt`` from within the Devilbox ``./ca`` directory: -.. image:: /_static/img/global-configuration/https-ssl-04-import.png +.. include:: /_includes/figures/https/file-manager-import-ca.rst As the last step you are asked what permissions you want to grant the newly importat CA. To make sure it works everywhere, check all options and proceed with ``OK``. -.. image:: /_static/img/global-configuration/https-ssl-05-firefox-set-trust.png +.. include:: /_includes/figures/https/firefox-set-trust.rst Now you are all set and all generated SSL certificates will be valid from now on. -.. image:: /_static/img/global-configuration/https-ssl-address-bar.png +.. include:: /_includes/figures/https/https-ssl-address-bar.rst Further Reading diff --git a/docs/tutorials/static-code-analysis.rst b/docs/intermediate/source-code-analysis.rst similarity index 89% rename from docs/tutorials/static-code-analysis.rst rename to docs/intermediate/source-code-analysis.rst index fa2a387b..be3a29db 100644 --- a/docs/tutorials/static-code-analysis.rst +++ b/docs/intermediate/source-code-analysis.rst @@ -1,7 +1,9 @@ -.. _tutorial_static_code_analysis: +.. include:: /_includes/all.rst + +.. _source_code_analysis: ******************** -Static Code Analysis +Source Code Analysis ******************** This tutorial gives you a general overview how to do static code analysis from within the PHP @@ -9,7 +11,7 @@ container. .. seealso:: * :ref:`available_tools` - * :ref:`tutorial_work_inside_the_php_container` + * :ref:`work_inside_the_php_container` **Table of Contents** @@ -36,7 +38,7 @@ workspace and its files. You can for example check for: Some of the bundled tools even allow for automatic fixing. -.. seealso:: `awesome-ci `_ +.. seealso:: |ext_lnk_tool_awesome_ci| .. code-block:: bash @@ -75,7 +77,7 @@ PHPCS PHPCS is a code style analyser for PHP. -.. seealso:: `PHPCS `_ +.. seealso:: |ext_lnk_tool_phpcs| .. code-block:: bash @@ -94,7 +96,7 @@ ESLint ESLint is a Javascript static source code analyzer. -.. seealso:: `ESLint `_ +.. seealso:: |ext_lnk_tool_eslint| .. code-block:: bash diff --git a/docs/tutorials/work-inside-the-container.rst b/docs/intermediate/work-inside-the-php-container.rst similarity index 96% rename from docs/tutorials/work-inside-the-container.rst rename to docs/intermediate/work-inside-the-php-container.rst index 9ac5d89d..c30accaf 100644 --- a/docs/tutorials/work-inside-the-container.rst +++ b/docs/intermediate/work-inside-the-php-container.rst @@ -1,8 +1,8 @@ -.. _tutorial_work_inside_the_php_container: +.. _work_inside_the_php_container: -************************* -Work inside the container -************************* +***************************** +Work inside the PHP container +***************************** The Devilbox allows you to completely work inside the PHP container (no matter what version), instead of your host operating system. @@ -229,9 +229,10 @@ sides as the connection to the database is exactly the same locally or within th You could also even switch between the Devilbox and a locally installed LAMP stack and still use the same configuration. -.. warning:: +.. important:: The mapping of ``127.0.0.1`` to your host operating system does not work with - :ref:`docker_toolbox`. + Docker Toolbox out of the box. In order to achieve the same behaviour read up on: + :ref:`howto_docker_toolbox_and_the_devilbox`. Port mappings @@ -266,11 +267,11 @@ All project DNS records are also available from inside the PHP container indepen value of :ref:`env_tld_suffix`. The PHP container is hooked up by default to the bundled DNS server and makes use -:ref:`global_configuration_auto_dns`. +:ref:`setup_auto_dns`. .. seealso:: You can achieve the same on your host operating system by explicitly enabling auto-dns. - See also: :ref:`global_configuration_auto_dns`. + See also: :ref:`setup_auto_dns`. Checklist @@ -283,4 +284,4 @@ Checklist 5. You know that ``127.0.0.1`` is available on your host and inside the PHP container 6. You know that ports are the same inside the container and on your host os 7. You know that project urls are available inside the container and on your host -8. You know about the limitations of :ref:`docker_toolbox` +8. You know about the limitations of :ref:`howto_docker_toolbox_and_the_devilbox` diff --git a/docs/linkcheck.sh b/docs/linkcheck.sh new file mode 100755 index 00000000..24c744f6 --- /dev/null +++ b/docs/linkcheck.sh @@ -0,0 +1,307 @@ +#!/usr/bin/env bash + +# Bestrict +set -e +set -u +set -o pipefail + + +############################################################ +# Overwritable global variables +############################################################ + + +### +### In what path to look for files +### +SEARCH_PATH="." + + +### +### Comma separated list of file extensions to scan for urls +### +EXTENSIONS="" + + +### +### Regex to exclude URLs from being tested +### +URL_REGEX_EXCLUDE="^http(s)?:\/\/(127\.0\.0\.1)|(localhost)|(.+\.loc).*$" + + +### +### Timeout in seconds to see if a site is alive +### +TIMEOUT=10 + + +### +### How many times to probe one URL to see if it is alive +### +RETRIES=3 + + +### +### Comma separated list of acceptable http status codes +### to define that the URL is alive +### +STATUS_CODES=200 + + + +############################################################ +# Functions +############################################################ + +### +### Usage +### +print_usage() { + echo "Usage: linkcheck [-e -i -t -r -c] []" + echo " linkcheck --version" + echo " linkcheck --help" + echo + echo + echo "Options:" + echo + echo "-e Limit search to those file extensions." + echo " Defaults to limiting on non-binary files." + echo " Accepts comma separated string of extensions:" + echo " -e txt" + echo " -e txt,rst" + echo " -e sh,py.c,h" + echo + echo "-i Ignore all URLs matching the specified regex." + echo ' Defaults to: ^http(s)?:\/\/(127\.0\.0\.1)|(localhost)|(.+\.loc).*$' + echo " Accepts a single regex string:" + echo " -i '^http(?):\/\/my-comapny.com.*$'" + echo + echo "-t Specify curl timeout in seconds, after which probing stops for one url." + echo " Defaults to 10 seconds." + echo " Accepts a positive integer:" + echo " -t 5" + echo " -t 10" + echo + echo "-r Specify how many time to retry probing a single URL, before giving up." + echo " Defaults to 3 times." + echo " Accepts a positive integer:" + echo " -r 5" + echo " -r 10" + echo + echo "-c Specify HTTP status codes that are valid for success." + echo " Any code not specified in here will produce an error for the given URL." + echo " Defaults to '200'." + echo " Accepts comma separated string of http status codes:" + echo " -c '200'" + echo " -c '200,301'" + echo " -c '200,301,302'" + echo + echo + echo "--version Show version and exit." + echo "--help Show this help screen." + echo + echo + echo "Optional arguments:" + echo + echo " Specify what directory to scan files for URLs." + echo " Defaults to current directory." + echo + echo +} + + +### +### Version +### +print_version() { + echo "linkcheck v0.1 by cytopia" + echo "https://github.com/cytopia/linkcheck" +} + + +### +### Set value (used to store stdout and stderr in two different variables) +### +setval() { + printf -v "$1" "%s" "$(cat)"; + declare -p "$1"; +} + + +### +### Gather URLs from files +### +gather_urls() { + local path="${1}" + local extensions="${2}" + local reg_exclude="${3}" + + local url_regex="http(s)?:\/\/[-=?:,._/#0-9a-zA-Z]+" + local find_ext= + local find_cmd= + + if [ -n "${extensions}" ]; then + find_ext="\( -iname \*.${extensions//,/ -o -iname \\*.} \)" + fi + + find_cmd="find ${path} ${find_ext} -type f -exec grep --binary-files=without-match -Eo '${url_regex}' '{}' \;" + >&2 echo "\$ ${find_cmd}" + + # Loop through uniqued URLs + for url in $(eval "${find_cmd}" 2>/dev/null | sort -u); do + # Ignore any 'Binary file...' results + if echo "${url}" | grep -Eq '^htt'; then + # Remove any trailing: [,.] + url="$( echo "${url}" | sed 's/[,.]$//g')" + + # Ignore URLs excluded by regex + if ! echo "${url}" | grep -qE "${reg_exclude}"; then + echo "${url}" + fi + fi + done +} + + +### +### Probe URLs for availability +### +probe_urls() { + local urls="${1}" + local timeout="${2}" + local retries="${3}" + local status_codes="${4}" + local ret_code=0 + + status_codes="${status_codes//,/|}" # comma to | + status_codes="${status_codes//[[:space:]]/}" # remove whitespace + + for url in ${urls}; do + + # Try to curl multiple times in case host is currently not reachable + i=0; fail=0 + eval "$( curl -SsI --connect-timeout "${timeout}" "${url}" 2> >(setval errval) > >(setval header); <<<"$?" setval retval; )" + while [ "${retval}" != "0" ] ; do + i=$(( i + 1 )) + sleep 2 + if [ "${i}" -ge "${retries}" ]; then + fail=1 + break; + fi + done + + # Curl request failed + if [ "${fail}" = "1" ]; then + printf "\e[0;31m[FAIL]\e[0m %s %s\n" "${url}" "${errval}" + + # Curl request succeeded + else + line="$( echo "${header}" | grep -E '^HTTP/(1|2)' )" + stat="$( echo "${line}" | awk '{print $2}' )" + + #if [ "${stat}" != "200" ]; then + if ! echo "${stat}" | grep -qE "${status_codes}"; then + printf "\e[0;31m[ERR]\e[0m %s %s\n" "${url}" "${line}" + ret_code=1 + else + printf "\e[0;32m[OK]\e[0m %s %s\n" "${url}" "${line}" + fi + fi + done + return ${ret_code} +} + + +############################################################ +# Entrypoint: arguments +############################################################ +#-e -i -t -r -c +while [ $# -gt 0 ]; do + case "${1}" in + + # ---------------------------------------- + -e) + shift + if [ "${#}" -gt "0" ]; then + EXTENSIONS="${1}" + else + >&2 echo "Error, -e requires an argument." + exit 1 + fi + ;; + + # ---------------------------------------- + -i) + shift + if [ "${#}" -gt "0" ]; then + URL_REGEX_EXCLUDE="${1}" + else + >&2 echo "Error, -i requires an argument." + exit 1 + fi + ;; + + # ---------------------------------------- + -t) + shift + if [ "${#}" -gt "0" ]; then + TIMEOUT="${1}" + else + >&2 echo "Error, -t requires an argument." + exit 1 + fi + ;; + + # ---------------------------------------- + -r) + shift + if [ "${#}" -gt "0" ]; then + RETRIES="${1}" + else + >&2 echo "Error, -r requires an argument." + exit 1 + fi + ;; + # ---------------------------------------- + -c) + shift + if [ "${#}" -gt "0" ]; then + STATUS_CODES="${1}" + else + >&2 echo "Error, -c requires an argument." + exit 1 + fi + ;; + + # ---------------------------------------- + --help) + print_usage + exit 0 + ;; + + # ---------------------------------------- + --version) + print_version + exit 0 + ;; + + # ---------------------------------------- + *) + # If it is the last argument, its the path + if [ "${#}" = "1" ]; then + SEARCH_PATH="${1}" + else + echo "Invalid argument: ${1}" + echo "Type 'linkcheck --help' for available options." + exit 1 + fi + ;; + esac + shift +done + + + +MY_URLS="$( gather_urls "${SEARCH_PATH}" "${EXTENSIONS}" "${URL_REGEX_EXCLUDE}" )" + +probe_urls "${MY_URLS}" "${TIMEOUT}" "${RETRIES}" "${STATUS_CODES}" diff --git a/docs/maintenance/backup-and-restore-mongo.rst b/docs/maintenance/backup-and-restore-mongo.rst index 0060fa5b..3aca06f8 100644 --- a/docs/maintenance/backup-and-restore-mongo.rst +++ b/docs/maintenance/backup-and-restore-mongo.rst @@ -1,3 +1,5 @@ +.. include:: /_includes/all.rst + .. _backup_and_restore_mongo: ************************** @@ -24,8 +26,8 @@ Backup mongodump --------- -`mongodump `_ is bundled with -each PHP container and reay to use. To backup all databases follow the below listed example: +|ext_lnk_tool_mongodump| is bundled with each PHP container and reay to use. +To backup all databases follow the below listed example: .. code-block:: bash @@ -38,9 +40,6 @@ each PHP container and reay to use. To backup all databases follow the below lis # Run mongodump devilbox@php-7.1.6 in /shared/httpd $ mongodump --out /shared/backups/mongo -To find out more about the configuration and options of mongodump, visit its project page under: -https://docs.mongodb.com/manual/reference/program/mongodump. - Restore ======= @@ -48,8 +47,8 @@ Restore mongorestore ------------ -`mongorestore `_ is bundled with -each PHP container and ready to use. To restore all MongoDB databases follow the below listed example: +|ext_lnk_tool_mongorestore| is bundled with each PHP container and ready to use. +To restore all MongoDB databases follow the below listed example: .. code-block:: bash @@ -61,6 +60,3 @@ each PHP container and ready to use. To restore all MongoDB databases follow the # Start the restore/import from /shared/backups/mongo devilbox@php-7.1.6 in /shared/httpd $ mongorestore /shared/backups/mongo - -To find out more about the configuration and options of mongorestore, visit its project page under: -https://docs.mongodb.com/manual/reference/program/mongorestore/. diff --git a/docs/maintenance/backup-and-restore-mysql.rst b/docs/maintenance/backup-and-restore-mysql.rst index 3a3093a4..bed6f601 100644 --- a/docs/maintenance/backup-and-restore-mysql.rst +++ b/docs/maintenance/backup-and-restore-mysql.rst @@ -1,3 +1,5 @@ +.. include:: /_includes/all.rst + .. _backup_and_restore_mysql: ************************ @@ -30,8 +32,8 @@ dump date, dump options as well as the server version it came from. Mysqldump-secure ---------------- -`mysqldump-secure `_ is bundled, setup and ready to use in every -PHP container. You can run it without any arguments and it will dump each available database as a +|ext_lnk_tool_mysqldump_secure| is bundled, setup and ready to use in every PHP container. +You can run it without any arguments and it will dump each available database as a separated compressed file. Backups will be located in ``./backups/mysql/`` inside the Devilbox git directory or in ``/shared/backups/mysql/`` inside the PHP container. @@ -185,8 +187,8 @@ occured during backups. Let's have a look at one of them: mysqldump --------- -`mysqldump `_ is bundled with each PHP -container and ready to use. To backup a database named ``my_db_name`` follow the below listed +|ext_lnk_tool_mysqldump| is bundled with each PHP container and ready to use. +To backup a database named ``my_db_name`` follow the below listed example which shows you how to do that from within the PHP container: .. code-block:: bash @@ -201,26 +203,21 @@ example which shows you how to do that from within the PHP container: devilbox@php-7.1.6 in /shared/httpd $ mysqldump -h mysql -u root -p my_db_name > /shared/backups/mysql/my_db_name.sql To find out more about the configuration and options of mysqldump, visit its project page under: -https://dev.mysql.com/doc/refman/5.7/en/mysqldump.html +|ext_lnk_tool_mysqldump| phpMyAdmin ---------- -If you do not like to use the command line for backups, you can use -`phpMyAdmin `_. It comes bundled with the devilbox intranet. - -To find out more about the usage of phpMyAdmin, visit its project page under: -https://www.phpmyadmin.net. +If you do not like to use the command line for backups, you can use |ext_lnk_tool_phpmyadmin|. +It comes bundled with the devilbox intranet. Adminer ------- -If you do not like to use the command line for backups, you can use -`Adminer `_. It comes bundled with the devilbox intranet. - -To find out more about the usage of Adminer, visit its project page under: https://www.adminer.org. +If you do not like to use the command line for backups, you can use |ext_lnk_tool_adminer| . +It comes bundled with the devilbox intranet. Restore @@ -281,7 +278,7 @@ binary. Here are a few examples for different file types: phpMyAdmin ---------- -`phpMyAdmin `_ supports importing many different formats out-of-the-box. +|ext_lnk_tool_phpmyadmin| supports importing many different formats out-of-the-box. Simply select the compressed or uncompressed file and press ``Go`` in the import section of the web interface. @@ -289,6 +286,6 @@ the web interface. Adminer ------- -`Adminer `_ supports importing of plain (``*.sql``) or gzipped compressed +|ext_lnk_tool_adminer| supports importing of plain (``*.sql``) or gzipped compressed (``*.sql.gz``) files out-of-the-box. Simply select the compressed or uncompressed file and press ``Execute`` in the import section of the web interface. diff --git a/docs/maintenance/backup-and-restore-pgsql.rst b/docs/maintenance/backup-and-restore-pgsql.rst index 56a8a3df..d16f22c2 100644 --- a/docs/maintenance/backup-and-restore-pgsql.rst +++ b/docs/maintenance/backup-and-restore-pgsql.rst @@ -1,3 +1,5 @@ +.. include:: /_includes/all.rst + .. _backup_and_restore_pgsql: ***************************** @@ -24,9 +26,8 @@ Backup pg_dump ------- -`pg_dump `_ is bundled with -each PHP container and reay to use. To backup a database named ``my_db_name`` follow the below -listed example: +|ext_lnk_tool_pg_dump| is bundled with each PHP container and reay to use. +To backup a database named ``my_db_name`` follow the below listed example: .. code-block:: bash @@ -39,17 +40,11 @@ listed example: # Run pg_dump devilbox@php-7.1.6 in /shared/httpd $ pg_dump -h pgsql -U postgres -W my_db_name > /shared/backups/pgsql/my_db_name.sql -To find out more about the configuration and options of pg_dump, visit its project page under: -https://www.postgresql.org/docs/current/static/backup-dump.html. - - Adminer ------- -If you do not like to use the command line for backups, you can use -`Adminer `_. It comes bundled with the devilbox intranet. - -To find out more about the usage of Adminer, visit its project page under: https://www.adminer.org. +If you do not like to use the command line for backups, you can use |ext_lnk_tool_adminer|. +It comes bundled with the devilbox intranet. Restore @@ -59,7 +54,7 @@ psql ---- In order to restore or import PostgreSQL databases on the command line, you need to use -`psql `_. +|ext_lnk_tool_pgsql_restore|. Here are a few examples for different file types: ``*.sql`` file @@ -108,6 +103,6 @@ Here are a few examples for different file types: Adminer ------- -`Adminer `_ supports importing of plain (``*.sql``) or gzipped compressed +|ext_lnk_tool_adminer| supports importing of plain (``*.sql``) or gzipped compressed (``*.sql.gz``) files out-of-the-box. Simply select the compressed or uncompressed file and press ``Execute`` in the import section of the web interface. diff --git a/docs/maintenance/checkout-different-devilbox-release.rst b/docs/maintenance/checkout-different-devilbox-release.rst new file mode 100644 index 00000000..01847c80 --- /dev/null +++ b/docs/maintenance/checkout-different-devilbox-release.rst @@ -0,0 +1,26 @@ +.. _checkout-different-devilbox-release: + +*********************************** +Checkout different Devilbox release +*********************************** + +You now have the devilbox downloaded at the latest version (``git master branch``). This is also recommended as it receives +bugfixes frequently. If you however want to stay on a stable release, you need to check out a +specific ``git tag``. + +Lets say you want your devilbox setup to be at release ``0.12.1``, all you have to do is to check out +this specific git tag. + +.. code-block:: bash + + host> cd path/to/devilbox + host> git checkout 0.12.1 + + +.. warning:: + Whenever you check out a different version, make sure that your ``.env`` file is up-to-date + with the bundled ``env-example`` file. Different Devilbox releases might require different + settings to be available inside the ``.env`` file. Refer to the next section for how to + create the ``.env`` file. + + diff --git a/docs/readings/remove-stopped-container.rst b/docs/maintenance/remove-stopped-container.rst similarity index 100% rename from docs/readings/remove-stopped-container.rst rename to docs/maintenance/remove-stopped-container.rst diff --git a/docs/maintenance/remove-the-devilbox.rst b/docs/maintenance/remove-the-devilbox.rst new file mode 100644 index 00000000..7ad21738 --- /dev/null +++ b/docs/maintenance/remove-the-devilbox.rst @@ -0,0 +1,131 @@ +.. _remove_the_devilbox: + +******************* +Remove the Devilbox +******************* + +If you want to completely remove the Devilbox follow this tutorial. + + +**Table of Contents** + +.. contents:: :local: + + +Backups +======= + +Before deleting the Devilbox git directory, ask yourself if you want to make backups of all +customizations you have done so far as well as of all data that may be present within that +directory. + +Dump databases +-------------- + +Before shutting down the Devilbox, do a final backup of all of your databases: + +.. seealso:: + + * :ref:`backup_and_restore_mysql` + * :ref:`backup_and_restore_pgsql` + * :ref:`backup_and_restore_mongo` + +Dumps will end up in ``backups/``. + +Shutdown the Devilbox +--------------------- + +Before attempting to backup any file system data, make sure the Devilbox is properly shutdown. + +.. code-block:: bash + + host> docker-compose stop + +Backup configuration files +-------------------------- + +You should now backup the following configuration files: + +* Backup your customized ``.env`` file +* Backup your customized ``.docker-compose.override.yml`` file +* Backup your customized bash configuration from ``bash/`` +* Backup all custom service configurations from ``cfg/`` +* Backup the Devilbox root certificate from ``ca/`` + +Backup data and dumps +--------------------- + +You should now backup the following data: + +* Backup any backups created in ``backups/`` +* Backup any project or Docker data from ``data/`` + + +Remove the Devilbox +=================== + +If you have followed the backup routine, you can continue deleting all created components. + +Remove Devilbox containers +-------------------------- + +Navigate to the Devilbox git directory and remove all Devilbox container: + + .. code-block:: bash + + host> docker-compose rm -f + +Remove Devilbox network +----------------------- + +1. List all existing Docker networks via + + .. code-block:: bash + + host> docker network ls + + NETWORK ID NAME DRIVER SCOPE + 0069843ff0c3 bridge bridge local + ... + 9c8d4a84cf2d devilbox_app_net bridge local + +2. Find the NETWORK ID of the Devilbox network and delete it: + + .. code-block:: bash + + host> docker network rm 9c8d4a84cf2d + +Remove Devilbox git directory +----------------------------- + +You can simply delete the whole Devilbox git directory + + +Revert your system changes +========================== + +AutoDNS +------- + +Revert any changes you have done for Auto-DNS to work. + +.. seealso:: :ref:`setup_auto_dns` + +Manual DNS entries +------------------ + +Revert any changes you have done in ``/etc/hosts`` (or ``C:\Windows\System32\drivers\etc`` for Windows) + +.. seealso:: + + * :ref:`howto_add_project_hosts_entry_on_mac` + * :ref:`howto_add_project_hosts_entry_on_win` + +Remove Devilbox CA from your browser +------------------------------------ + +Remove the Devilbox CA from your browser + +.. seealso:: + + * :ref:`setup_valid_https` diff --git a/docs/getting-started/update-the-devilbox.rst b/docs/maintenance/update-the-devilbox.rst similarity index 87% rename from docs/getting-started/update-the-devilbox.rst rename to docs/maintenance/update-the-devilbox.rst index 92aa8daa..888f3996 100644 --- a/docs/getting-started/update-the-devilbox.rst +++ b/docs/maintenance/update-the-devilbox.rst @@ -1,4 +1,4 @@ -.. _getting_started_update_the_devilbox: +.. _update_the_devilbox: ******************* Update the Devilbox @@ -59,10 +59,10 @@ If you want to checkout a specific release tag (such as ``0.12.1``), do a ``git Keep ``.env`` file in sync -------------------------- -.. warning:: - Whenever you check out a different version, make sure that your ``.env`` file is up-to-date - with the bundled ``env-example`` file. Different Devilbox releases might require different - settings to be available inside the ``.env`` file. +.. important:: + Whenever you check out a different version, make sure that your ``.env`` file is up-to-date + with the bundled ``env-example`` file. Different Devilbox releases might require different + settings to be available inside the ``.env`` file. You can also compare your current ``.env`` file with the provided ``env-example`` file by using your favorite diff editor: @@ -79,6 +79,14 @@ your favorite diff editor: host> meld .env env-example +Keep ``vhost-gen`` templates in sync +------------------------------------ + +.. important:: + Whenever you check out a different version, make sure that the vhost-gen templates that have + been copied to any virtual hosts are up-to-date with the templates provided in + ``templates/vhost-gen/``. + Recreate container ------------------ @@ -97,7 +105,7 @@ recreated during the next start. :ref:`remove_stopped_container` -.. _getting_started_update_the_docker_images: +.. _update_the_devilbox_update_the_docker_images: Update Docker images ==================== @@ -195,6 +203,7 @@ Checklist git repository 1. Ensure containers are stopped and removed/recreated (``docker-compose stop && docker-compose rm``) 2. Ensure desired branch, tag or commit is checked out or latest changes are pulled 3. Ensure ``.env`` file is in sync with ``env-example`` file +4. Ensure all of your custom applied vhost-gen templates are in sync with the default templates Checklist Docker images diff --git a/docs/about/read-first.rst b/docs/read-first.rst similarity index 83% rename from docs/about/read-first.rst rename to docs/read-first.rst index 117d4619..6d48215b 100644 --- a/docs/about/read-first.rst +++ b/docs/read-first.rst @@ -26,6 +26,15 @@ Shell commands php> command +Examples +======== + +.. note:: + + Most examples to configure your host operating system will be presented for Linux by default, + there will however always be links for how to accomplish the same on Windows and MacOS. + + Checklists ========== diff --git a/docs/readings/available-tools.rst b/docs/readings/available-tools.rst index 5aaee36b..5a1aad25 100644 --- a/docs/readings/available-tools.rst +++ b/docs/readings/available-tools.rst @@ -1,3 +1,5 @@ +.. include:: /_includes/all.rst + .. _available_tools: *************** @@ -7,81 +9,81 @@ Available tools Each PHP container version brings the same tools, so you can safely switch versions without having to worry to have less or more tools available. -.. seealso:: :ref:`tutorial_work_inside_the_php_container` +.. seealso:: :ref:`work_inside_the_php_container` The PHP container is your workhorse and these are your tools: -+----------------------+-----------------------------------------------------------------------------------+ -| Binary | Tool | -+======================+===================================================================================+ -| various binaries | `awesome-ci `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``brew`` | `Linux brew `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``composer`` | `Composer `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``drush`` | `Drush `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``drupal`` | `Drupal Console `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``eslint`` | `ESLint `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``git`` | `Git `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``git-flow`` | `Git flow `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``gulp`` | `Gulp `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``grunt`` | `Grunt `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``jsonlint`` | `JSON lint `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``laravel`` | `Laravel installer `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``mdl`` | `Markdown lint `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``mdlint`` | `MD Linter `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``mongo*`` | Various MongoDB client tools | -+----------------------+-----------------------------------------------------------------------------------+ -| ``mysql*`` | Various MySQL client tools | -+----------------------+-----------------------------------------------------------------------------------+ -| ``mysqldump-secure`` | `mysqldump-secure `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``node`` | `Node `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``npm`` | `NPM `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``pg*`` | Various PostgreSQL client tools | -+----------------------+-----------------------------------------------------------------------------------+ -| ``phalcon`` | `Phalcon DevTools `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``phpcs`` | `PHP CodeSniffer `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``phpcbf`` | `PHP Code Beautifier and Fixer `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``photon`` | `Photon CMS cli `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``redis*`` | Various Redis client tools | -+----------------------+-----------------------------------------------------------------------------------+ -| ``sass`` | `Sass `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``scss-lint`` | `SCSS Lint `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``ssh`` | `OpenSSH `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``symfony`` | `Symfony installer `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``tig`` | `Text-mode Interface for Git `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``webpack`` | `Webpack `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``wp`` | `Wordpress CLI `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``yamllint`` | `Yamllint `_ | -+----------------------+-----------------------------------------------------------------------------------+ -| ``yarn`` | `Yarn `_ | -+----------------------+-----------------------------------------------------------------------------------+ ++----------------------+---------------------------------------+ +| Binary | Tool | ++======================+=======================================+ +| various binaries | |ext_lnk_tool_awesome_ci| | ++----------------------+---------------------------------------+ +| ``brew`` | |ext_lnk_tool_linuxbrew| | ++----------------------+---------------------------------------+ +| ``composer`` | |ext_lnk_tool_composer| | ++----------------------+---------------------------------------+ +| ``drush`` | |ext_lnk_tool_drush| | ++----------------------+---------------------------------------+ +| ``drupal`` | |ext_lnk_tool_drupal_console| | ++----------------------+---------------------------------------+ +| ``eslint`` | |ext_lnk_tool_eslint| | ++----------------------+---------------------------------------+ +| ``git`` | |ext_lnk_tool_git| | ++----------------------+---------------------------------------+ +| ``git-flow`` | |ext_lnk_tool_git_flow| | ++----------------------+---------------------------------------+ +| ``gulp`` | |ext_lnk_tool_gulp| | ++----------------------+---------------------------------------+ +| ``grunt`` | |ext_lnk_tool_grunt| | ++----------------------+---------------------------------------+ +| ``jsonlint`` | |ext_lnk_tool_jsonlint| | ++----------------------+---------------------------------------+ +| ``laravel`` | |ext_lnk_tool_laravel| | ++----------------------+---------------------------------------+ +| ``mdl`` | |ext_lnk_tool_mdl| | ++----------------------+---------------------------------------+ +| ``mdlint`` | |ext_lnk_tool_mdlint| | ++----------------------+---------------------------------------+ +| ``mongo*`` | Various MongoDB client tools | ++----------------------+---------------------------------------+ +| ``mysql*`` | Various MySQL client tools | ++----------------------+---------------------------------------+ +| ``mysqldump-secure`` | |ext_lnk_tool_mysqldump_secure| | ++----------------------+---------------------------------------+ +| ``node`` | |ext_lnk_tool_node| | ++----------------------+---------------------------------------+ +| ``npm`` | |ext_lnk_tool_npm| | ++----------------------+---------------------------------------+ +| ``pg*`` | Various PostgreSQL client tools | ++----------------------+---------------------------------------+ +| ``phalcon`` | |ext_lnk_tool_phalcon| | ++----------------------+---------------------------------------+ +| ``phpcs`` | |ext_lnk_tool_phpcs| | ++----------------------+---------------------------------------+ +| ``phpcbf`` | |ext_lnk_tool_phpcbf| | ++----------------------+---------------------------------------+ +| ``photon`` | |ext_lnk_tool_photon| | ++----------------------+---------------------------------------+ +| ``redis*`` | Various Redis client tools | ++----------------------+---------------------------------------+ +| ``sass`` | |ext_lnk_tool_sass| | ++----------------------+---------------------------------------+ +| ``scss-lint`` | |ext_lnk_tool_scss_lint| | ++----------------------+---------------------------------------+ +| ``ssh`` | |ext_lnk_tool_ssh| | ++----------------------+---------------------------------------+ +| ``symfony`` | |ext_lnk_tool_symfony| | ++----------------------+---------------------------------------+ +| ``tig`` | |ext_lnk_tool_tig| | ++----------------------+---------------------------------------+ +| ``webpack`` | |ext_lnk_tool_webpack| | ++----------------------+---------------------------------------+ +| ``wp`` | |ext_lnk_tool_wp| | ++----------------------+---------------------------------------+ +| ``yamllint`` | |ext_lnk_tool_yamllint| | ++----------------------+---------------------------------------+ +| ``yarn`` | |ext_lnk_tool_yarn| | ++----------------------+---------------------------------------+ .. note:: If you are in need of other tools, open up an issue at @@ -91,4 +93,4 @@ The PHP container is your workhorse and these are your tools: .. seealso:: If you ever feel those tools are out-dated, simply update your Docker images. Docker images are built every night to ensure latest tools and security patches: - :ref:`getting_started_update_the_docker_images` + :ref:`update_the_devilbox_update_the_docker_images` diff --git a/docs/support/blogs-videos-and-use-cases.rst b/docs/support/blogs-videos-and-use-cases.rst index dec0c539..46f660f4 100644 --- a/docs/support/blogs-videos-and-use-cases.rst +++ b/docs/support/blogs-videos-and-use-cases.rst @@ -1,3 +1,5 @@ +.. include:: /_includes/all.rst + .. _blogs_videos_and_use_cases: *************************** @@ -10,11 +12,8 @@ Official videos The official videos might be a bit old, but are still valid and a good start, even if the intranet UI has changed a bit. -.. image:: /_static/img/youtube-setup-and-workflow.png - :target: https://www.youtube.com/watch?v=reyZMyt2Zzo - -.. image:: /_static/img/youtube-email-catch-all.png - :target: https://www.youtube.com/watch?v=e-U-C5WhxGY +.. include:: /_includes/figures/blogs/youtube-setup-and-workflow.rst +.. include:: /_includes/figures/blogs/youtube-email-catch-all.rst Blog posts @@ -22,17 +21,13 @@ Blog posts The following shows a list of blogs that give a nice and objective introduction to the Devilbox. -+------------------------------------------------------------------------------+----------+ -| Title | Language | -+==============================================================================+==========+ -| `Using Devilbox For Local WordPress Development In Docker`_ | English | -+------------------------------------------------------------------------------+----------+ -| `Devilbox: Lokaler Webserver mit Apache, PHP und MySQL im Docker Container`_ | German | -+------------------------------------------------------------------------------+----------+ - -.. _`Using Devilbox For Local WordPress Development In Docker`: https://deliciousbrains.com/devilbox-local-wordpress-development-docker - -.. _`Devilbox: Lokaler Webserver mit Apache, PHP und MySQL im Docker Container`: https://blog.moritzkanzler.de/devilbox-lokaler-webserver-mit-apache-php-und-mysql-im-docker-container/ ++---------------------------------+----------+ +| Title | Language | ++=================================+==========+ +| |ext_lnk_blog_deliciousbrains| | English | ++---------------------------------+----------+ +| |ext_lnk_blog_moritzkanzler| | German | ++---------------------------------+----------+ Use-cases @@ -41,9 +36,8 @@ Use-cases Joomla's Continuous Integration -------------------------------- -Joomla has created a `PR Testing Platform `_ -as their `Google Summer of Code 2017 `_ -project using a modified version of the Devilbox. +Joomla has created a |ext_lnk_blog_joomla_pr_testing_platform| as their +|ext_lnk_blog_joomla_gsoc2017| project using a modified version of the Devilbox. Add your story diff --git a/docs/support/faq.rst b/docs/support/faq.rst index ed33c308..1362e70e 100644 --- a/docs/support/faq.rst +++ b/docs/support/faq.rst @@ -6,7 +6,9 @@ FAQ Find common questions and answers here. -.. seealso:: :ref:`troubleshooting` +.. seealso:: + * :ref:`howto` + * :ref:`troubleshooting` **Table of Contents** @@ -20,7 +22,7 @@ General Are there any differences between native Docker and Docker Toolbox? ------------------------------------------------------------------- -Yes, read :ref:`docker_toolbox` to find out more. +Yes, read :ref:`howto_docker_toolbox_and_the_devilbox` to find out more. .. _faq_data_dir_separated_by_version: @@ -139,7 +141,7 @@ You need a valid DNS entry for every project that points to the Httpd server. As don't exists by default, you will have to create them. However, the Devilbox has a bundled DNS server that can automate this for you. The only thing you have to do for that to work is to add this DNS server's IP address to your ``/etc/resolv.conf``. -See :ref:`global_configuration_auto_dns` for detailed instructions. +See :ref:`setup_auto_dns` for detailed instructions. Compatibility @@ -151,6 +153,12 @@ Does it work with CakePHP? Yes, see :ref:`example_setup_cakephp` +Does it work with Codeigniter? +------------------------------ + +Yes, see :ref:`example_setup_codeigniter` + + Does it work with Drupal? ------------------------- @@ -175,12 +183,30 @@ Does it work with Phalcon? Yes, see :ref:`example_setup_phalcon` +Does it work with Photon CMS? +----------------------------- + +Yes, see :ref:`example_setup_photon_cms` + + +Does it work with Shopware? +--------------------------- + +Yes, see :ref:`example_setup_shopware` + + Does it work with Symfony? -------------------------- Yes, see :ref:`example_setup_symfony` +Does it work with Typo3? +------------------------ + +Yes, see :ref:`example_setup_typo3` + + Does it work with Wordpress? ---------------------------- @@ -197,3 +223,8 @@ Does it work with Zend? ----------------------- Yes, see :ref:`example_setup_zend` + +Does it work with other Frameworks? +----------------------------------- + +Yes, see :ref:`example_setup_other_frameworks` diff --git a/docs/support/howto.rst b/docs/support/howto.rst new file mode 100644 index 00000000..86381efb --- /dev/null +++ b/docs/support/howto.rst @@ -0,0 +1,41 @@ +.. _howto: + +****** +How To +****** + +The How to section gathers information about various topics, that might need to be done at some point throughout the installation and configuration. + +.. seealso:: + * :ref:`faq` + * :ref:`troubleshooting` + +.. toctree:: + :caption: Administration + :maxdepth: 1 + :glob: + + /howto/dns/* + /howto/uid-and-gid/* + +.. toctree:: + :caption: Devilbox + :maxdepth: 1 + :glob: + + /howto/devilbox/* + /howto/xdebug/* + +.. toctree:: + :caption: Docker Toolbox + :maxdepth: 1 + :glob: + + /howto/docker-toolbox/* + +.. toctree:: + :caption: Terminal + :maxdepth: 1 + :glob: + + /howto/terminal/* diff --git a/docs/support/troubleshooting.rst b/docs/support/troubleshooting.rst index b8a08ea1..bc028e47 100644 --- a/docs/support/troubleshooting.rst +++ b/docs/support/troubleshooting.rst @@ -7,7 +7,19 @@ Troubleshooting This section will contain common problems and how to resolve them. It will grow over time once there are more issues reported. -.. seealso:: :ref:`faq` +.. seealso:: + * :ref:`howto` + * :ref:`faq` + +.. important:: + + :ref:`update_the_devilbox` + Issues are constantly being fixed. Before attempting to spend too much time digging into + your issue, make sure you are running the latest git changes and have pulled the latest + Docker images. + + Also keep in mind that configuration files might change, so ensure to diff the default ones + against your currently active ones for added, removed or changed values. **Table of Contents** @@ -15,6 +27,171 @@ It will grow over time once there are more issues reported. .. contents:: :local: +General +======= + +Sudden unexplained problems on Windows +-------------------------------------- + +In case something stopped working for no reason, check out other Docker container. If you +experience similar issues as well, check for any unattended Windows updates or +updates to Docker itself. If those exist, try to revert them and see if that was the cause. + +I heard many bug stories from fellow Windows users so far. +A good contact point for that is the Docker forum itself: https://forums.docker.com/c/docker-for-windows + +A few general things you should always do before attempting to open up issues are: + +**1. Used default settings from env-example** + + Try using the exact settings from ``env-example`` as variables might have been updated in git. + + .. code-block:: bash + + # Ensure everything is stopped + host> cp env-example .env + +**2. Clean, updated and minimal start** + + .. code-block:: bash + + # Ensure everything is stopped + host> docker-compose stop + host> docker-compose kill + host> docker-compose rm -f + + # Ensure everything is updated + host> docker-compose pull + + # Start again + host> docker-compose up php httpd bind + +**3. Reset Docker credentials:** + + As it might sound strange, this fix might indeed solve a lot of problems on Windows. + Go to your Docker settings and reset your credentials. + +**4. Shared volumes:** + + Ensure all your Devilbox data (Devilbox directory and project directory) are within the volumes + that are shared by Docker. If not add those in the Docker settings. + + +Address already in use +---------------------- + +One of the Docker container wants to bind to a port on the host system which is already taken. +Figure out what service is listening on your host system and shut it down or change the port +of the affected service in the Devilbox ``.env`` file. + +Some examples of common error messages: + +.. code-block:: bash + + Error starting userland proxy: Bind for 0.0.0.0:80: unexpected error (Failure EADDRINUSE) + + +Unable to finish Pulling as unauthorized: incorrect username or password +------------------------------------------------------------------------ + +This error might occur if you are already logged into a different Docker repository. +To fix this error, sign out of your currently logged in repository and try again. + +.. seealso:: https://github.com/cytopia/devilbox/issues/223 + + +localhost or 127.0.0.1 not found +-------------------------------- + +If you are using Docker Toolbox, the Devilbox intranet is not available on localhost or 127.0.0.1, +but rather on the IP address of the Docker Toolbox machine. + +.. seealso:: :ref:`howto_find_docker_toolbox_ip_address` + + +ERROR: Version in "./docker-compose.yml" is unsupported +------------------------------------------------------- + +This simply means your Docker and/or Docker Compose versions are outdated. + +.. seealso:: :ref:`prerequisites` + +DNS issues +========== + +zone 'localhost': already exists previous definition +---------------------------------------------------- + +.. code-block:: bash + + bind_1 | /etc/bind/devilbox-wildcard_dns.localhost.conf:1: + zone 'localhost': already exists previous definition: + /etc/bind/named.conf.default-zones:10 + +This error occurs when using ``localhost`` as the :ref:`env_tld_suffix`. + +.. seealso:: + + * :ref:`env_tld_suffix` + * https://github.com/cytopia/devilbox/issues/291 + + +Web server issues +================= + +Warning: DocumentRoot [/var/www/default/htdocs/] does not exist +--------------------------------------------------------------- + +This error is most likely to only occur on Docker for Windows and is just a result of not working +volumes mounts. + +.. seealso:: https://forums.docker.com/t/volume-mounts-in-windows-does-not-work/10693 + + +403 forbidden +------------- + +This error might occur for the Devilbox intranet or custom created projects. + +File and directory permissions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On of the cause could be wrongly set file and directory permissions. + +First ensure the cloned git directory is readable for users, groups and others. + +For the Devilbox intranet, ensure the ``.devilbox/`` directory is readable for users, groups and +others. Also check files and directories within. + +For projects, ensure an ``index.php`` or ``index.html`` exists and that all files and directories +are readable for users, groups and others. + +Shared volumes +^^^^^^^^^^^^^^ + +This might additionally occur on MacOS or Windows due to the Devilbox and/or its projects not +being in the standard location of Docker Shared volumes. + +Check your Docker settings to allow shared volumes for the path of the Devilbox and its projects. + + +504 Gateway timeout +------------------- + +This error occurs when the upstream PHP-FPM server takes longer to execute a script, +than the timeout value set in the web server for PHP-FPM to answer. + +For that to fix one must increase the PHP-FPM/Proxy timeout settings on the virtual host. + +.. seealso:: + + * https://github.com/cytopia/devilbox/issues/280 + * https://github.com/cytopia/devilbox/issues/234 + + +Database issues +=============== + Invalid bind mount spec ----------------------- @@ -26,7 +203,6 @@ Removing the container is sufficient as they will always be created during run i In order to remove the container do the following: - .. code-block:: bash host> cd path/to/devilbox @@ -38,13 +214,12 @@ In order to remove the container do the following: .. seealso:: :ref:`remove_stopped_container` - [Warning] World-writable config file '/etc/mysql/docker-default.d/my.cnf' is ignored ------------------------------------------------------------------------------------ -This warning might occur when using :ref:`docker_toolbox` on Windows and trying to apply custom -MySQL configuration files. This will also result in the configuration file not being source -by the MySQL server. +This warning might occur when using :ref:`howto_docker_toolbox_and_the_devilbox` on Windows and +trying to apply custom MySQL configuration files. This will also result in the configuration file +not being source by the MySQL server. To fix this issue, you will have to change the file permission of your custom configuration files to read-only by applying the following ``chmod`` command. diff --git a/docs/tutorials/change-container-versions.rst b/docs/tutorials/change-container-versions.rst deleted file mode 100644 index b2934501..00000000 --- a/docs/tutorials/change-container-versions.rst +++ /dev/null @@ -1,134 +0,0 @@ -************************* -Change container versions -************************* - -One of the core concepts of the Devilbox is to easily change between different versions of a -specific service. - - -**Table of Contents** - -.. contents:: :local: - - -Change PHP version -================== - -Stop the Devilbox ------------------ - -Shut down the Devilbox in case it is still running: - -.. code-block:: bash - - # Navigate to the Devilbox directory - host> /home/user/devilbox - - # Stop all container - host> docker-compose stop - - -Edit the ``.env`` file ----------------------- - -Open the ``.env`` file with your favourite editor and navigate to the ``PHP_SERVER`` section. -It will look something like this: - - -.. code-block:: bash - :caption: .env - :emphasize-lines: 5 - - #PHP_SERVER=5.3 - #PHP_SERVER=5.4 - #PHP_SERVER=5.5 - #PHP_SERVER=5.6 - #PHP_SERVER=7.0 - PHP_SERVER=7.1 - #PHP_SERVER=7.2 - #PHP_SERVER=7.3 - -As you can see, all available values are already there, but commented. Only one is uncommented. -In this example it is ``7.1``, which is the PHP version that will be started, once the Devilbox -starts. - -To change this, simply uncomment your version of choice and save this file. Do not forget to comment -(disable) any other version. - -In order to enable PHP 5.5, you would change the ``.env`` file like this: - -.. code-block:: bash - :caption: .env - :emphasize-lines: 2 - - #PHP_SERVER=5.3 - #PHP_SERVER=5.4 - PHP_SERVER=5.5 - #PHP_SERVER=5.6 - #PHP_SERVER=7.0 - #PHP_SERVER=7.1 - #PHP_SERVER=7.2 - #PHP_SERVER=7.3 - - -Start the Devilbox ----------------------- - -Now save the file and you can start the Devilbox again. - -.. code-block:: bash - - # Navigate to the Devilbox directory - host> /home/user/devilbox - - # Stop all container - host> docker-compose up php httpd bind - -.. seealso:: :ref:`start_the_devilbox` - - -Gotchas -------- - -If two versions are uncommented, always the last one takes precedence. - -Consider this ``.env`` file: - -.. code-block:: bash - :caption: .env - :emphasize-lines: 2,4 - - #PHP_SERVER=5.3 - #PHP_SERVER=5.4 - PHP_SERVER=5.5 - #PHP_SERVER=5.6 - PHP_SERVER=7.0 - #PHP_SERVER=7.1 - #PHP_SERVER=7.2 - #PHP_SERVER=7.3 - -Both, PHP 5.4 and PHP 7.0 are uncommented, however, when you start the Devilbox, it will use -PHP 7.0 as this value overwrites any previous ones. - - -Change whatever version -======================= - -When you have read how to change the PHP version, it should be fairly simple to change any -service version. It behaves in the exact same way. - -The variable names of all available services with changable versions are in the following format: -``_SERVER``. Just look through the :ref:`env_file`. - -.. seealso:: - The following variables control service versions: - :ref:`env_php_server`, :ref:`env_httpd_server`, :ref:`env_mysql_server`, :ref:`env_pgsql_server`, :ref:`env_redis_server`, :ref:`env_memcd_server`, :ref:`env_mongo_server` - - - -Checklist -========= - -1. Stop the Devilbox -2. Uncomment version of choice in ``.env`` -3. Start the Devilbox diff --git a/docs/tutorials/communicating-with-external-hosts.rst b/docs/tutorials/communicating-with-external-hosts.rst deleted file mode 100644 index 95db0ee9..00000000 --- a/docs/tutorials/communicating-with-external-hosts.rst +++ /dev/null @@ -1,170 +0,0 @@ -.. _communicating_with_external_hosts: - -********************************* -Communicating with 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. - - -**Table of Contents** - -.. contents:: :local: - - -Prerequisites -============= - -There are two things you need to make sure of are met beforehand: - -1. The external Docker container must expose its ports on all interfaces on your host operating system -2. The IP by which the host is reachable from within the Devilbox container. - -Host IP: Docker on Linux ------------------------- - -If you run Docker on Linux the host IP is always ``172.16.238.1``, which is the default gateway -IP address within the Devilbox bridge network (see ``docker-compose.yml``). - -By default Docker on Linux does not have CNAME's of the host computer as for example with MacOS -or Windows, therefore two custom CNAME's have been added by the Devilbox in order to emulate the -same behaviour: - -* CNAME: ``docker.for.lin.host.internal`` -* CNAME: ``docker.for.lin.localhost`` - -Host IP: Docker for Mac ------------------------ - -If you run Docker for Mac, an IP address is not necessary as it already provides a CNAME which will -always point to the IP address of your host operating system. Depending on the Docker version this -CNAME will differ: - -Docker 18.03.0-ce+ and Docker compose 1.20.1+ -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -CNAME: ``host.docker.internal`` - -Docker 17.12.0-ce+ and Docker compose 1.18.0+ -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -CNAME: ``docker.for.mac.host.internal`` - -Docker 17.06.0-ce+ and Docker compose 1.14.0+ -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -CNAME: ``docker.for.mac.localhost`` - - -Host IP: Docker for Windows ----------------------------- - -If you run Docker for Windows, an IP address is not necessary as it already provides a CNAME which will -always point to the IP address of your host operating system. Depending on the Docker version this -CNAME will differ: - -Docker 18.03.0-ce+ and Docker compose 1.20.1+ -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -CNAME: ``docker.for.win.host.internal`` - -Docker 17.06.0-ce+ and Docker compose 1.14.0+ -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -CNAME: ``docker.for.win.host.localhost`` - - - -Make DNS available to the Devilbox -================================== - -Inside each Devilbox Docker container you can already connect to all host ports (if they are bound -to all interfaces) by the above specified IP addresses or CNAME's. You can however also create a -custom DNS entry for convenience or if an external web server requires a special vhost name. - -Adding extra hosts ------------------- - -Extra hosts (hostname and IP address mappings or hostname and CNAME mappings) can be set in the -``.env`` file. - -.. seealso:: :ref:`env_extra_hosts` - - -Example -------- - -Let's assume another Docker container is running on your host, which must be accessed by the exact -name of ``mywebserver.loc`` in order to respond by that virtual host name. - - -Mapping on Linux -^^^^^^^^^^^^^^^^ - -If you are running Linux as your host operating system you would use the IP address of the host -computer which was identified as ``172.16.238.1``. - -.. code-block:: bash - :caption: .env - - EXTRA_HOSTS=mywebserver.loc=172.16.238.1 - -or - -.. code-block:: bash - :caption: .env - - EXTRA_HOSTS=mywebserver.loc=docker.for.lin.host.internal - -or - -.. code-block:: bash - :caption: .env - - EXTRA_HOSTS=mywebserver.loc=docker.for.lin.localhost - - -Mapping on MacOS -^^^^^^^^^^^^^^^^ - -If you are running MacOS as your host operating system you would use one of the identified CNAME's -(depending on your Docker version). - -.. code-block:: bash - :caption: .env - - EXTRA_HOSTS=mywebserver.loc=host.docker.internal - -The CNAME ``host.docker.internal`` will be resolved to an IP address during startup and ``mywebserver.loc`` -'s DNS record will point to that IP address. - - -Mapping on Windows -^^^^^^^^^^^^^^^^^^ - -If you are running Windows as your host operating system you would use one of the identified CNAME's -(depending on your Docker version). - -.. code-block:: bash - :caption: .env - - EXTRA_HOSTS=mywebserver.loc=docker.for.win.host.internal - -The CNAME ``docker.for.win.host.internal`` will be resolved to an IP address during startup and ``mywebserver.loc`` -'s DNS record will point to that IP address. - - -Auto DNS --------- - -If you also turned on :ref:`global_configuration_auto_dns` these extra hosts will then also be available -to your host operating system as well. - - -Further reading -=============== - -.. seealso:: - * :ref:`env_extra_hosts` - * :ref:`global_configuration_auto_dns` diff --git a/docs/tutorials/enable-xdebug.rst b/docs/tutorials/enable-xdebug.rst deleted file mode 100644 index e043fcc9..00000000 --- a/docs/tutorials/enable-xdebug.rst +++ /dev/null @@ -1,407 +0,0 @@ -.. _enable_xdebug: - -************* -Enable Xdebug -************* - -This tutorial shows you how to enable and use Xdebug with the Devilbox. - -.. seealso:: - If you are unsure of how to add custom ``*.ini`` files to the Devilbox, - have a look at this section first: :ref:`php_ini` - - -**Table of Contents** - -.. contents:: :local: - -Enable Xdebug -============= - -This section shows you the minimum required ``*.ini`` ini settings to get xdebug to work with -the Devilbox. It will also highlight the differences between operating system and Docker versions. - -.. seealso:: See here for how to add the ``*.ini`` values to the Devilbox: :ref:`php_ini`. - -Once you have configured Xdebug, you can verify it at the Devilbox intranet: -http://localhost/info_php.php - - -Required for all OS -------------------- - -Additionally to the specific configurations for each operating system and Docker version you will -probably also want to add the following to your ini file: - -.. code-block:: ini - :caption: xdebug.ini - - xdebug.default_enable=1 - xdebug.remote_enable=1 - xdebug.remote_handler=dbgp - xdebug.remote_port=9000 - xdebug.remote_autostart=1 - xdebug.idekey="PHPSTORM" - xdebug.remote_log=/var/log/php/xdebug.log - -.. seealso:: https://xdebug.org/docs/all_settings - -default_enable -^^^^^^^^^^^^^^ -By enabling this, stacktraces will be shown by default on an error event. -It is advisable to leave this setting set to 1. - -remote_enable -^^^^^^^^^^^^^ -This switch controls whether Xdebug should try to contact a debug client which is listening on the -host and port as set with the settings ``xdebug.remote_host`` and ``xdebug.remote_port``. -If a connection can not be established the script will just continue as if this setting was 0. - -remote_handler -^^^^^^^^^^^^^^ -Can be either ``'php3'`` which selects the old PHP 3 style debugger output, ``'gdb'`` which enables -the GDB like debugger interface or ``'dbgp'`` - the debugger protocol. The DBGp protocol is the only -supported protocol. - -**Note:** Xdebug 2.1 and later only support ``'dbgp'`` as protocol. - -remote_port -^^^^^^^^^^^ -The port to which Xdebug tries to connect on the remote host. Port ``9000`` is the default for both -the client and the bundled debugclient. As many clients use this port number, it is best to leave -this setting unchanged. - -remote_autostart -^^^^^^^^^^^^^^^^ -Normally you need to use a specific HTTP GET/POST variable to start remote debugging (see -`Remote Debugging `_). When this setting is set to -``1``, Xdebug will always attempt to start a remote debugging session and try to connect to a client, -even if the GET/POST/COOKIE variable was not present. - -idekey -^^^^^^ -Controls which IDE Key Xdebug should pass on to the DBGp debugger handler. The default is based on -environment settings. First the environment setting DBGP_IDEKEY is consulted, then USER and as last -USERNAME. The default is set to the first environment variable that is found. If none could be found -the setting has as default ''. If this setting is set, it always overrides the environment variables. - -For the sake of this tutorial we are going to use ``PHPSTORM`` as an example value. - -remote_log -^^^^^^^^^^ -Keep the exact path of ``/var/log/php/xdebug.log``. You will then have the log file available -in the Devilbox log directory of the PHP version for which you have configured Xdebug. - -.. important:: - You can set the value of ``xdebug.idekey`` to whatever you like, however it is important - to remember what value you have set. Throughout the examples in this tutorial it is assumed, - that the value is ``PHPSTORM``. - - -Linux ------ - -.. code-block:: ini - :caption: xdebug.ini - :emphasize-lines: 1 - - xdebug.remote_connect_back=1 - - -MacOS (Docker for Mac) ----------------------- - -Docker 18.03.0-ce+ and Docker compose 1.20.1+ - -.. code-block:: ini - :caption: xdebug.ini - :emphasize-lines: 1 - - xdebug.remote_host=host.docker.internal - xdebug.remote_connect_back=0 - -Docker 17.12.0-ce+ and Docker compose 1.18.0+ - -.. code-block:: ini - :caption: xdebug.ini - :emphasize-lines: 1 - - xdebug.remote_host=docker.for.mac.host.internal - xdebug.remote_connect_back=0 - -Docker 17.06.0-ce+ and Docker compose 1.14.0+ - -.. code-block:: ini - :caption: xdebug.ini - :emphasize-lines: 1 - - xdebug.remote_host=docker.for.mac.localhost - xdebug.remote_connect_back=0 - -If you have older versions, upgrade. - - -MacOS (Docker Toolbox) ----------------------- - -.. warning:: - This is a legacy solution, upgrade to Docker for Mac - https://docs.docker.com/toolbox - - -Windows (Docker for Windows) ----------------------------- - -Docker 18.03.0-ce+ and Docker compose 1.20.1+ - -.. code-block:: ini - :caption: xdebug.ini - :emphasize-lines: 1 - - xdebug.remote_host=docker.for.win.host.internal - xdebug.remote_connect_back=0 - -Docker 17.06.0-ce+ and Docker compose 1.14.0+ - -.. code-block:: ini - :caption: xdebug.ini - :emphasize-lines: 1 - - xdebug.remote_host=docker.for.win.host.localhost - xdebug.remote_connect_back=0 - -If you have older versions, upgrade. - - -Windows (Docker Toolbox) ------------------------- - -.. warning:: - This is a legacy solution, upgrade to Docker for Windows - https://docs.docker.com/toolbox - - -Configure your IDE -================== - -Required for all IDE --------------------- - -Path mapping -^^^^^^^^^^^^ -The path mapping is a mapping between the file path on your host operating system and the one -inside the PHP Docker container. - -The path on your host operating system is the one you have set in :ref:`env_httpd_datadir`. -In case you have set a relative path in ``.env``, ensure to retrieve the absolute path of it when -setting up your IDE config. - -The path inside the PHP Docker container is always ``/shared/httpd``. - -.. important:: - Even though your path in ``.env`` for :ref:`env_httpd_datadir` might be relative (e.g. ``./data/www``), - you need to get the actualy absolute path of it, when setting up your IDE. - -IDE key -^^^^^^^ -This is the value you have set in ``xdebug.ini`` for ``xdebug.idekey``. In the example of this -tutorial, the value was set to ``PHPSTORM``. - -Port -^^^^ -This is the value you have set in ``xdebug.ini`` for ``xdebug.remote_port``. In the example of this -tutorial, the value was set to ``9000``. - - -Atom ----- - -1. Install `php-debug `_ -2. Configure ``config.cson`` (File -> Config...) -3. Adjust your ``xdebug.ini`` - -For Atom, you need to provide a different ``xdebug.idekey`` in your php.ini file ``xdebug.ini``: - -.. code-block:: ini - :caption: xdebug.ini - - xdebug.idekey=xdebug.atom - - -Linux -^^^^^^ -.. code-block:: js - :caption: launch.json - :emphasize-lines: 6 - - "php-debug": - { - ServerPort: 9000 - PathMaps: [ - "remotepath;localpath" - "/shared/httpd;/home/cytopia/repo/devilbox/data/www" - ] - } - -MacOS (Docker for Mac) -^^^^^^^^^^^^^^^^^^^^^^ -.. todo:: Help needed. Please provide your config. - -MacOS (Docker Toolbox) -^^^^^^^^^^^^^^^^^^^^^^ -.. todo:: Help needed. Please provide your config. - -Windows (Docker for Windows) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. todo:: Help needed. Please provide your config. - -Windows (Docker Toolbox) -^^^^^^^^^^^^^^^^^^^^^^^^ -.. todo:: Help needed. Please provide your config. - - -PHPStorm --------- - -Linux -^^^^^^ - -Enable Xdebug for the port set in ``xdebug.ini``: - -.. image:: /_static/img/tutorials/xdebug_phpstorm_settings.png - -Create a new PHP server and set a path mapping. This tutorial assumes your local Devilbox projects -to be in ``./data/www`` of the Devilbox git directory: - -.. image:: /_static/img/tutorials/xdebug_phpstorm_path_mapping.png - -Set DBGp proxy settings: - -.. image:: /_static/img/tutorials/xdebug_phpstorm_proxy.png - - -MacOS (Docker for Mac) -^^^^^^^^^^^^^^^^^^^^^^ -.. todo:: Help needed. Please provide your config. - -MacOS (Docker Toolbox) -^^^^^^^^^^^^^^^^^^^^^^ -.. todo:: Help needed. Please provide your config. - -Windows (Docker for Windows) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. todo:: Help needed. Please provide your config. - -Windows (Docker Toolbox) -^^^^^^^^^^^^^^^^^^^^^^^^ -.. todo:: Help needed. Please provide your config. - - -Sublime Text 3 --------------- - -1. Install `Xdebug Client `_ via the Sublime Package Control. -2. Configure ``Xdebug.sublime-settings`` (Tools -> Xdebug -> Settings - User) - -Linux -^^^^^^ -.. code-block:: json - :caption: Xdebug-sublime-settings - :emphasize-lines: 3,6 - - { - "path_mapping": { - "/shared/httpd" : "/home/cytopia/repo/devilbox/data/www" - }, - "url": "", - "ide_key": "PHPSTORM", - "host": "0.0.0.0", - "port": 9000 - } - - -MacOS (Docker for Mac) -^^^^^^^^^^^^^^^^^^^^^^ -.. todo:: Help needed. Please provide your config. - -MacOS (Docker Toolbox) -^^^^^^^^^^^^^^^^^^^^^^ -.. todo:: Help needed. Please provide your config. - -Windows (Docker for Windows) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. todo:: Help needed. Please provide your config. - -Windows (Docker Toolbox) -^^^^^^^^^^^^^^^^^^^^^^^^ -.. todo:: Help needed. Please provide your config. - - -Visual Studio Code ------------------- - -1. Install `vscode-php-debug `_ -2. Configure ``launch.json`` - -Linux -^^^^^^ -.. code-block:: json - :caption: launch.json - :emphasize-lines: 9,10 - - { - "version": "0.2.0", - "configurations": [ - { - "name": "Listen for Xbebug", - "type": "php", - "request": "launch", - "port": 9000, - "serverSourceRoot": "/shared/httpd", - "localSourceRoot": "/home/cytopia/repo/devilbox/data/www" - }, { - "name": "Launch currently open script", - "type": "php", - "request": "launch", - "program": "${file}", - "cwd": "${fileDirname}", - "port": 9000 - } - ] - } - - -MacOS (Docker for Mac) -^^^^^^^^^^^^^^^^^^^^^^ -.. todo:: Help needed. Please provide your config. - -MacOS (Docker Toolbox) -^^^^^^^^^^^^^^^^^^^^^^ -.. todo:: Help needed. Please provide your config. - -Windows (Docker for Windows) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. todo:: Help needed. Please provide your config. - -Windows (Docker Toolbox) -^^^^^^^^^^^^^^^^^^^^^^^^ -.. todo:: Help needed. Please provide your config. - - -.. - MacOS videos - https://serversforhackers.com/c/getting-xdebug-working - https://serversforhackers.com/c/auto-config - - https://www.arroyolabs.com/2016/10/docker-xdebug/ - - https://medium.com/@yuliakostrikova/configure-remote-debugging-with-xdebug-for-php-docker-container-on-macos-8edbc01dc373 - - https://github.com/petronetto/php7-alpine - - #old - docker.for.mac.localhost - #new - docker.for.mac.host.internal - - docker.for.win.localhost diff --git a/docs/configuration-project/custom-vhost.rst b/docs/vhost-gen/customize-specific-virtual-host.rst similarity index 97% rename from docs/configuration-project/custom-vhost.rst rename to docs/vhost-gen/customize-specific-virtual-host.rst index 07a8e3a5..b18792e7 100644 --- a/docs/configuration-project/custom-vhost.rst +++ b/docs/vhost-gen/customize-specific-virtual-host.rst @@ -1,8 +1,10 @@ -.. _custom_vhost: +.. include:: /_includes/all.rst -*********************************** -Customized virtual host (vhost-gen) -*********************************** +.. _customize_specific_virtual_host: + +******************************* +Customize specific virtual host +******************************* **Table of Contents** @@ -26,9 +28,9 @@ listening ports. If you intend to use ``vhost-gen`` for your own projects, have a look at its project page and its sister projects: - * `vhost-gen `_ - * `watcherd `_ - * `watcherp `_ + * |ext_lnk_project_vhost_gen| + * |ext_lnk_project_watcherd| + * |ext_lnk_project_watcherp| Where do I find templates @@ -412,4 +414,4 @@ Further readings .. seealso:: Have a look at the following examples which involve customizing vhost-gen templates: - * :ref:`tutorial_adding_sub_domains` + * :ref:`example_add_sub_domains` diff --git a/docs/tutorials/adding-subdomains.rst b/docs/vhost-gen/example-add-subdomains.rst similarity index 96% rename from docs/tutorials/adding-subdomains.rst rename to docs/vhost-gen/example-add-subdomains.rst index 064e649a..8a2b352c 100644 --- a/docs/tutorials/adding-subdomains.rst +++ b/docs/vhost-gen/example-add-subdomains.rst @@ -1,8 +1,10 @@ -.. _tutorial_adding_sub_domains: +.. include:: /_includes/all.rst -****************** -Adding Sub domains -****************** +.. _example_add_sub_domains: + +************************ +Example: 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 @@ -53,13 +55,17 @@ When you want to have multiple domains and/or sub domains for one project (such case of Wordpress multi-sites), you will need to customize your virtual host config for this project and make the web server allow to serve your files by different server names. -Each web server virtual host is auto-generated by a tool called -`vhost-gen `_. ``vhost-gen`` allows you to overwrite its +Each web server virtual host is auto-generated by a tool called |ext_lnk_project_vhost_gen|. +``vhost-gen`` allows you to overwrite its default generation process via templates. Those templates can be added to each project, giving you the option to customize the virtual host of this specific project. +.. + note:: + :ref:`customize_all_virtual_hosts_globally` and :ref:`customize_specific_virtual_host` + .. note:: - :ref:`custom_vhost` + :ref:`customize_specific_virtual_host` Ensure you have read and understand how to customize your virtual host with ``vhost-gen``. :ref:`env_httpd_template_dir` Ensure you know what this variable does inside your ``.env`` file. @@ -82,7 +88,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 +224,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 +394,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