From e9094fe286931e7846ec65d4d1087f19ae442c7f Mon Sep 17 00:00:00 2001 From: cytopia Date: Fri, 13 Jul 2018 00:35:01 +0200 Subject: [PATCH] Documentation: Xdebug for Atom --- docs/_includes/all.rst | 1 + docs/_includes/links/xdebug.rst | 11 ++ .../xdebug/host-address-alias-an-mac.rst | 50 +++++ .../configure-php-xdebug/atom.rst | 180 ++++++++++++++++++ docs/support/howto.rst | 1 + 5 files changed, 243 insertions(+) create mode 100644 docs/_includes/links/xdebug.rst create mode 100644 docs/howto/xdebug/host-address-alias-an-mac.rst create mode 100644 docs/intermediate/configure-php-xdebug/atom.rst diff --git a/docs/_includes/all.rst b/docs/_includes/all.rst index 5bde35bd..dbb9be78 100644 --- a/docs/_includes/all.rst +++ b/docs/_includes/all.rst @@ -29,3 +29,4 @@ .. include:: /_includes/links/ssh.rst .. include:: /_includes/links/tools.rst .. include:: /_includes/links/uid.rst +.. include:: /_includes/links/xdebug.rst diff --git a/docs/_includes/links/xdebug.rst b/docs/_includes/links/xdebug.rst new file mode 100644 index 00000000..e6590220 --- /dev/null +++ b/docs/_includes/links/xdebug.rst @@ -0,0 +1,11 @@ +.. |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) + 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/intermediate/configure-php-xdebug/atom.rst b/docs/intermediate/configure-php-xdebug/atom.rst new file mode 100644 index 00000000..3cea1661 --- /dev/null +++ b/docs/intermediate/configure-php-xdebug/atom.rst @@ -0,0 +1,180 @@ +:orphan: + +.. include:: /_includes/all.rst + +.. _configure_php_xdebug_atom: + +************************* +Configure Xdebug for Atom +************************* + +**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_enable_xdebug` + + +Atom configuration +================== + +1. Install `php-debug `_ for Atom +2. Configure path mapping in ``config.cson`` or ui. + + .. code-block:: js + :caption: launch.json + :emphasize-lines: 6 + + "php-debug": + { + ServerPort: 9000 + PathMaps: [ + "remotepath;localpath" + "/shared/httpd;/home/cytopia/repo/devilbox/data/www" + ] + } + + .. important:: + You need to adjust the path part on the right side, as it will most likely be different + on your system. + + Also note that on Windows you have to use ``\\`` as directory separators. + E.g.: ``C:\\Users\\projects``. + + +Xdebug configuration +==================== + +Xdebug configuration for the Devilbox will slightly vary depending on your host operating system +and your Docker version (native or Toolbox). Pick your system below and create correct +``xdebug.ini`` for the Devilbox. + + +Docker on Linux +--------------- + +.. 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 Atom documentation + xdebug.idekey=xdebug-atom + + # Optional: Set to true to auto-start xdebug + xdebug.remote_autostart=false + + +Docker for Mac +-------------- + +.. important:: + Ensure you have created an :ref:`howto_host_address_alias_on_mac` and + ``10.254.254.254`` is aliased to your localhost. + +.. code-block:: ini + :caption: xdebug.ini + :emphasize-lines: 6-7,11 + + # Defaults + xdebug.remote_enable=1 + xdebug.remote_port=9000 + + # The MacOS way + xdebug.remote_connect_back=0 + xdebug.remote_host=10.254.254.254 + + # idekey value is specific to each editor + # Verify with Atom documentation + xdebug.idekey=xdebug-atom + + # Optional: Set to true to auto-start xdebug + xdebug.remote_autostart=false + + +Docker for Windows +------------------ + +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:: + The below listed ``xdebug.ini`` uses ``192.168.246.1``, you need to change this to whatever + IP address came out on your system. + +.. code-block:: ini + :caption: xdebug.ini + :emphasize-lines: 6-7,11 + + # Defaults + xdebug.remote_enable=1 + xdebug.remote_port=9000 + + # The Windows way + xdebug.remote_connect_back=0 + xdebug.remote_host=192.168.246.1 + + # idekey value is specific to each editor + # Verify with Atom documentation + xdebug.idekey=xdebug-atom + + # Optional: Set to true to auto-start xdebug + xdebug.remote_autostart=false + + +Docker Toolbox +-------------- + +.. note:: This applies for both, Docker Toolbox on MacOS and Docker Toolbox on Windows. + + +1. Forward host os port ``9000`` (Xdebug listening port of your IDE) to Docker Toolbox machine also on port ``9000``. + (remote or local forward) + + .. seealso:: + * :ref:`howto_ssh_port_forward_on_docker_toolbox_from_host` + * :ref:`howto_ssh_port_forward_on_host_to_docker_toolbox` + +2. Add ``xdebug.php`` + + .. 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 Atom documentation + xdebug.idekey=xdebug-atom + + # Optional: Set to true to auto-start xdebug + xdebug.remote_autostart=false + + .. seealso:: + * CNAME for :ref:`connect_to_host_os_docker_on_linux` diff --git a/docs/support/howto.rst b/docs/support/howto.rst index 476f6702..86381efb 100644 --- a/docs/support/howto.rst +++ b/docs/support/howto.rst @@ -24,6 +24,7 @@ The How to section gathers information about various topics, that might need to :glob: /howto/devilbox/* + /howto/xdebug/* .. toctree:: :caption: Docker Toolbox