From b1f0e12111d4a143ce49fbe4ea7b6258239098f5 Mon Sep 17 00:00:00 2001 From: cytopia Date: Fri, 16 Mar 2018 23:26:12 +0100 Subject: [PATCH] Extend env file documentation --- docs/configuration-files/env-file.rst | 113 ++++++++++++++++++- docs/getting-started/update-the-devilbox.rst | 34 +++--- docs/index.rst | 1 + docs/readings/remove-stopped-container.rst | 31 +++++ 4 files changed, 161 insertions(+), 18 deletions(-) create mode 100644 docs/readings/remove-stopped-container.rst diff --git a/docs/configuration-files/env-file.rst b/docs/configuration-files/env-file.rst index 07e53f35..ff4f894e 100644 --- a/docs/configuration-files/env-file.rst +++ b/docs/configuration-files/env-file.rst @@ -46,8 +46,10 @@ The only reason you would ever want change this variable is when you are on MacO your project files onto an NFS volume due to performance issues. .. warning:: - Whenever you change this value you have to stop the Devilbox and re-create your volumes via - ``docker-compose rm -f``. + :ref:`remove_stopped_container` + Whenever you change this value you have to stop the Devilbox and also remove the stopped + container via + ``docker-compose rm``. +-------------------+----------------+---------------+ | Name | Allowed values | Default value | @@ -131,6 +133,12 @@ this project visible to everyone in your corporate LAN. | www.test | ``org`` | ``http://www.test.org`` | +-------------+----------------+---------------------------+ +.. warning:: + Do not use ``dev`` (I know, it's tempting) as a domain suffix, as it has been registered by + `Google `_ and they advertise the + `HSTS header `_ + which makes your browser redirect every http request to https. + .. _env_new_uid: @@ -587,6 +595,107 @@ Mapping No matter what path you assign, inside the PHP and the web server container your data dir will always be ``/shared/httpd/``. +.. warning:: + Do not create any symlinks inside your project directories that go outside the data dir. + Anything which is outside this directory is not mounted into the container. + +.. warning:: + :ref:`remove_stopped_container` + Whenever you change this value you have to stop the Devilbox and also remove the stopped + container via + ``docker-compose rm``. + + +HOST_PATH_MYSQL_DATADIR +----------------------- + +This is an absolute or relative path (relative to Devilbox git directory) to your MySQL data directory. + +* Relative path: relative to the devilbox git directory (Must start with ``.``) +* Absolute path: Full path (Must start with ``/``) + ++------------------------------+----------------+------------------+ +| Name | Allowed values | Default value | ++==============================+================+==================+ +| ``HOST_PATH_MYSQL_DATADIR`` | valid path | ``./data/mysql`` | ++------------------------------+----------------+------------------+ + +Each MySQL, MariaDB or PerconaDB version will have its own subdirectory, so when first running MySQL 5.5 +and then starting MySQL 5.6, you will have a different database with different data. + +Having each version separated from each other makes sure that you don't accidently upgrade +from a lower to a higher version which might not be reversable. (MySQL auto-upgrade certain older +data files to newer, but this process does not necessarily work the other way round and could result in failues). + +The directory structure will look something like this: + +.. code-block:: bash + + host> ls -l ./data/mysql/ + drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mariadb-10.0/ + drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mariadb-10.1/ + drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mariadb-10.2/ + drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mariadb-10.3/ + drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mysql-5.5/ + drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mysql-5.6/ + drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mysql-5.7/ + drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mysql-8.0/ + drwxrwxr-x 6 48 48 4096 Jun 21 08:47 percona-5.5/ + drwxrwxr-x 6 48 48 4096 Jun 21 08:47 percona-5.6/ + drwxrwxr-x 6 48 48 4096 Jun 21 08:47 percona-5.7/ + +.. warning:: + :ref:`remove_stopped_container` + Whenever you change this value you have to stop the Devilbox and also remove the stopped + container via + ``docker-compose rm``. + + +HOST_PATH_PGSQL_DATADIR +----------------------- + +This is an absolute or relative path (relative to Devilbox git directory) to your PostgreSQL data directory. + +* Relative path: relative to the devilbox git directory (Must start with ``.``) +* Absolute path: Full path (Must start with ``/``) + ++------------------------------+----------------+------------------+ +| Name | Allowed values | Default value | ++==============================+================+==================+ +| ``HOST_PATH_PGSQL_DATADIR`` | valid path | ``./data/pgsql`` | ++------------------------------+----------------+------------------+ + +Each PostgreSQL version will have its own subdirectory, so when first running PostgreSQL 9.1 +and then starting PostgreSQL 10.0, you will have a different database with different data. + +Having each version separated from each other makes sure that you don't accidently upgrade +from a lower to a higher version which might not be reversable. + +The directory structure will look something like this: + +.. code-block:: bash + + host> ls -l ./data/pgsql/ + drwxrwxr-x 6 48 48 4096 Jun 21 08:47 9.1/ + drwxrwxr-x 6 48 48 4096 Jun 21 08:47 9.2/ + drwxrwxr-x 6 48 48 4096 Jun 21 08:47 9.3/ + drwxrwxr-x 6 48 48 4096 Jun 21 08:47 9.4/ + drwxrwxr-x 6 48 48 4096 Jun 21 08:47 9.5/ + drwxrwxr-x 6 48 48 4096 Jun 21 08:47 9.6/ + +.. warning:: + :ref:`remove_stopped_container` + Whenever you change this value you have to stop the Devilbox and also remove the stopped + container via + ``docker-compose rm``. + + + + + + + + .. |br| raw:: html diff --git a/docs/getting-started/update-the-devilbox.rst b/docs/getting-started/update-the-devilbox.rst index 043a48a8..5dd4486c 100644 --- a/docs/getting-started/update-the-devilbox.rst +++ b/docs/getting-started/update-the-devilbox.rst @@ -78,6 +78,23 @@ your favorite diff editor: host> meld .env env-example +Recreate container +------------------ + +Whenever the path of a volume changes (either due to upstream changes in git or due to you changing +it manually in the ``.env`` file) you need to remove the stopped container and have them fully +recreated during the next start. + +.. code-block:: bash + + # Remove anonymous volumes + host> cd path/to/devilbox + host> docker-compose rm + +.. seealso:: + :ref:`remove_stopped_container` + + Update Docker container ======================= @@ -100,30 +117,15 @@ which will update all available Docker images at once. latest security patches and tool versions are applied. -Remove anonymous volumes -======================== - -The devilbox is not yet at a feature-ready stable release and volumes mounts might change from release to release until version 1.0 will be released. This can cause errors during startup. To solve those issues after updating, you should remove all anonymouse volumes with the following command: - -.. code-block:: bash - - # Remove anonymous volumes - host> cd path/to/devilbox - host> docker-compose rm - - Checklist git repository ======================== -1. Ensure containers are stopped +1. Ensure containers are stopped and removed/recreated 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 anonymous volumes are removed Checklist Docker images ======================= 1. Ensure ``./update-docker.sh`` is executed -2. Ensure anonymous volumes are removed - diff --git a/docs/index.rst b/docs/index.rst index efb875e3..c19c4e31 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -104,6 +104,7 @@ devilbox documentation installation/docker-installation installation/docker-toolbox readings/available-container + readings/remove-stopped-container readings/syncronize-container-permissions diff --git a/docs/readings/remove-stopped-container.rst b/docs/readings/remove-stopped-container.rst new file mode 100644 index 00000000..af558b62 --- /dev/null +++ b/docs/readings/remove-stopped-container.rst @@ -0,0 +1,31 @@ +.. _remove_stopped_container: + +************************ +Remove stopped container +************************ + +Why should I? +============= + +If you simply ``docker-compose stop`` in order to stop all containers, they are still preserved +in the ``docker ps -a`` process list and still have state. + +In case you change any path variables inside the ``.env`` file (or silently due to git updates), +you need to completely re-create the state. + +This is done by first fully removing the container and then simply starting it again. + + +How to do it? +============= + +.. code-block:: bash + + host> docker-compose stop + host> docker-compose rm + + +When to do it? +============== + +Whenever path values inside the ``.env`` file change.