Merge pull request #513 from cytopia/docs-restart-devilbox

Docs restart Devilbox (docker-compose rm -f)

.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

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`

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
+
+   <img src="https://raw.githubusercontent.com/devilbox/artwork/master/submissions_diagrams/cytopia/01/png/architecture-full.png" />
+
 .. important::
    :ref:`read_first`
     Ensure you have read this document to understand how this documentation works.

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`

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
 =======