From 16131d3c87b20e6b1c3e4486761802191187749c Mon Sep 17 00:00:00 2001 From: cytopia Date: Thu, 28 Feb 2019 12:37:30 +0100 Subject: [PATCH 1/2] Fixes #426: Emphasize importance of docker-compose rm --- .github/ISSUE_TEMPLATE/bug_report.md | 1 + docs/getting-started/start-the-devilbox.rst | 46 ++++++++++++++++++++- docs/maintenance/update-the-devilbox.rst | 7 +++- docs/support/troubleshooting.rst | 31 ++++++++++++++ 4 files changed, 82 insertions(+), 3 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 6fcb52ca..60e008d5 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -30,6 +30,7 @@ assignees: '' * [ ] `docker-compose logs` and `log/` output is added * [ ] I've looked through the docs: https://devilbox.readthedocs.io/en/latest/ * [ ] I've looked through existing issues: https://github.com/cytopia/devilbox/issues +* [ ] I've read troubleshooting: https://devilbox.readthedocs.io/en/latest/support/troubleshooting.html ### OS / ENVIRONMENT diff --git a/docs/getting-started/start-the-devilbox.rst b/docs/getting-started/start-the-devilbox.rst index de6880e6..d81f62a6 100644 --- a/docs/getting-started/start-the-devilbox.rst +++ b/docs/getting-started/start-the-devilbox.rst @@ -69,6 +69,7 @@ For the first startup, foreground start is recommended to see any errors that mi * If you want to gracefully stop all container, hit ``Ctrl + c`` * If you want to kill all container, hit ``Ctrl + c`` twice +* Ensure to run ``docker-compose rm -f`` afterwards Background ---------- @@ -81,6 +82,7 @@ For consecutive startups you can send them into background (``-d``): * If you want to gracefully stop all container, enter ``docker-compose stop`` * If you want to kill all container, enter ``docker-compose kil`` +* Ensure to run ``docker-compose rm -f`` afterwards Start some container @@ -98,6 +100,7 @@ Foreground * If you want to gracefully stop all started container, hit ``Ctrl + c`` * If you want to kill all started container, hit ``Ctrl + c`` twice +* Ensure to run ``docker-compose rm -f`` afterwards Background ---------- @@ -108,6 +111,7 @@ Background * If you want to gracefully stop all container, enter ``docker-compose stop`` * If you want to kill all container, enter ``docker-compose kil`` +* Ensure to run ``docker-compose rm -f`` afterwards .. seealso:: :ref:`available_container` @@ -115,12 +119,48 @@ Background they have to be specified. +Stop and Restart +================ + +.. important:: + + When stopping or restarting the Devilbox, ensure to also **remove stopped container** before the + next startup to prevent orphaned runtime settings and always start fresh. + + This will prevent many common Docker issues. + +.. seealso:: **Troubleshooting:** :ref:`troubleshooting_what_to_do_first` + + +Stop all container +------------------ + +.. code-block:: bash + + # Stop all container + host> docker-compose stop + # Remove stopped container (important!) + host> docker-compose rm -f + +Restart all container +--------------------- + +.. code-block:: bash + + # Stop all container + host> docker-compose stop + # Remove stopped container (important!) + host> docker-compose rm -f + # Start all container + host> docker-compose up + + Open Devilbox intranet ====================== Once ``docker-compose up`` has finished and all or the selected container are up and running, you can visit the Devilbox intranet with your favorite Web browser at http://localhost or -http://127.0.0.1. +http://127.0.0.1 (https://localhost or https:127.0.0.1 respectively). The Intranet start page will also show you all running and failed containers: @@ -139,6 +179,8 @@ Checklist ========= 1. Docker container are started successfully with ``docker-compose up`` -2. Intranet is reachable via ``http://localhost``, ``http://127.0.0.1`` or Docker Toolbox IP address +2. ``docker-compose rm -f`` is issued before restarting the Devilbox +3. Intranet is reachable via ``http://localhost``, ``http://127.0.0.1`` or Docker Toolbox IP address +4. Intranet is reachable via ``https://localhost``, ``https://127.0.0.1`` (HTTPS) .. seealso:: :ref:`troubleshooting` diff --git a/docs/maintenance/update-the-devilbox.rst b/docs/maintenance/update-the-devilbox.rst index 3991da48..2e92c46a 100644 --- a/docs/maintenance/update-the-devilbox.rst +++ b/docs/maintenance/update-the-devilbox.rst @@ -27,6 +27,8 @@ stop all devilbox containers: # Stop containers host> cd path/to/devilbox host> docker-compose stop + # Remove stopped container (required) + host> docker-compose rm -f # Ensure containers are stopped host> docker-compose ps @@ -99,7 +101,7 @@ recreated during the next start. # Remove anonymous volumes host> cd path/to/devilbox - host> docker-compose rm + host> docker-compose rm -f .. seealso:: :ref:`remove_stopped_container` @@ -210,3 +212,6 @@ Checklist Docker images ======================= 1. Ensure ``docker-compose pull`` or ``./update-docker.sh`` is executed +2. Ensure ``docker-compose rm -f`` is executed after stopping the Devilbox + +.. seealso:: **Troubleshooting:** :ref:`troubleshooting_what_to_do_first` diff --git a/docs/support/troubleshooting.rst b/docs/support/troubleshooting.rst index 6cc4dcab..55d45d5e 100644 --- a/docs/support/troubleshooting.rst +++ b/docs/support/troubleshooting.rst @@ -27,6 +27,37 @@ It will grow over time once there are more issues reported. .. contents:: :local: +.. _troubleshooting_what_to_do_first: + +What to always do first +======================= + +Before going into the issues below, always do the following + +**1. Ensure stopped container are removed** + + .. code-block:: bash + + # Ensure everything is stopped + host> docker-compose stop + host> docker-compose kill + host> docker-compose rm -f + +**2. Ensure config is normalized** + + .. code-block:: bash + + # Ensure .env file is normalized + host> cp env-example .env + +**3. Statup minimal** + + .. code-block:: bash + + # Test everything with the minimal stack + host> docker-compose up php httpd bind + + General ======= From c32b8462e21a45eb049af83e7679927d35940ac3 Mon Sep 17 00:00:00 2001 From: cytopia Date: Thu, 28 Feb 2019 12:37:47 +0100 Subject: [PATCH 2/2] Add architecture diagram --- docs/index.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/index.rst b/docs/index.rst index 940db235..1cc34045 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -20,6 +20,10 @@ The only thing you will have to do is to create a new directory on the filesyste host is ready to be served with your custom domain. +.. raw:: html + + + .. important:: :ref:`read_first` Ensure you have read this document to understand how this documentation works.