DVL-012 #92 Adds documentation for changing data directories

docs/Configure.md

@@ -168,11 +168,28 @@ If set to `1`, it will show all executed commands during docker startup.
 
 | `.env` file variable name | Default | Note |
 |---------------------------|---------|------|
-| DEVILBOX_PATH             | `.`     | Relative or absolute path allowed |
+| DEVILBOX_PATH             | `.`     | Relative or absolute path allowed.<br/><strong>Note:</strong> Container need to be re-created after changing this value. |
 
 This is the base path that will be prepended to all mount paths specified in `.env`.
 You will usually not need to change this value..
 
+**IMPORTANT:** When changing this path, it will affect the paths of all other mounted DATA directories. You must therefore also remove any stopped container so that they will be re-created with new different mount points during the next run. In order to accomplish this obey the following precedure:
+
+```shell
+# Stop the container
+$ docker-compose stop
+
+# Remove the stopped container (IMPORTANT!)
+# After the removal it will be re-created during next run
+$ docker-compose rm -f
+
+# Edit any path variables
+$ vim .env
+
+# Start your stack
+$ docker-compose up -d
+```
+
 #### 2.3 Host computer listening address
 
 | `.env` file variable name | Default | Note |
@@ -213,10 +230,24 @@ The above examples should make it clear enough.
 
 | `.env` file variable name | Default | Note |
 |---------------------------|---------|------|
-| HOST_PATH_HTTPD_DATADIR   | `./data/www`   | Can be absolute or relative path. A relative path starts inside the devilbox git directory. |
+| HOST_PATH_HTTPD_DATADIR   | `./data/www`   | Can be absolute or relative path. A relative path starts inside the devilbox git directory.<br/><strong>Note:</strong> Container need to be re-created after changing this value. |
 
 This is the file system path on your host computer which will hold the Project Folders.
 
+**IMPORTANT:** When changing this path, you must re-create any affected Docker container explicitly. This can be accomplished by doing the following:
+
+```shell
+# Stop the container
+$ docker-compose stop
+
+# Remove the stopped container (IMPORTANT!)
+# After the removal it will be re-created during next run
+$ docker-compose rm -f
+
+# Start your stack
+$ docker-compose up -d
+```
+
 
 ## 4. Container settings
 
@@ -416,7 +447,7 @@ If you also want to change the listening address (default: 127.0.0.1) to somethi
 
 | `.env` file variable name | Default | Note |
 |---------------------------|---------|------|
-| HOST_PATH_MYSQL_DATADIR   | `./data/mysql`   | Can be absolute or relative path. A relative path starts inside the devilbox git directory. |
+| HOST_PATH_MYSQL_DATADIR   | `./data/mysql`   | Can be absolute or relative path. A relative path starts inside the devilbox git directory.<br/><strong>Note:</strong> Container need to be re-created after changing this value. |
 
 This is the file system path on your host computer which will hold the MySQL data.
 
@@ -439,6 +470,21 @@ 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/
 ```
 
+**IMPORTANT:** When changing this path, you must re-create any affected Docker container explicitly. This can be accomplished by doing the following:
+
+```shell
+# Stop the container
+$ docker-compose stop
+
+# Remove the stopped container (IMPORTANT!)
+# After the removal it will be re-created during next run
+$ docker-compose rm -f
+
+# Start your stack
+$ docker-compose up -d
+```
+
+
 ##### 4.4.6 my.cnf
 
 `my.cnf` settings can be configured for each MySQL/MariaDB version separately. Container-based configuration is done inside the `./cfg/` directory.
@@ -520,7 +566,7 @@ If you also want to change the listening address (default: 127.0.0.1) to somethi
 
 | `.env` file variable name | Default | Note |
 |---------------------------|---------|------|
-| HOST_PATH_PGSQL_DATADIR   | `./data/pgsql`   | Can be absolute or relative path. A relative path starts inside the devilbox git directory. |
+| HOST_PATH_PGSQL_DATADIR   | `./data/pgsql`   | Can be absolute or relative path. A relative path starts inside the devilbox git directory.<br/><strong>Note:</strong> Container need to be re-created after changing this value. |
 
 This is the file system path on your host computer which will hold the PostgreSQL data.
 
@@ -538,6 +584,21 @@ drwxrwxr-x 6 48 48 4096 Jun 21 08:47 9.5/
 drwxrwxr-x 6 48 48 4096 Jun 21 08:47 9.6/
 ```
 
+**IMPORTANT:** When changing this path, you must re-create any affected Docker container explicitly. This can be accomplished by doing the following:
+
+```shell
+# Stop the container
+$ docker-compose stop
+
+# Remove the stopped container (IMPORTANT!)
+# After the removal it will be re-created during next run
+$ docker-compose rm -f
+
+# Start your stack
+$ docker-compose up -d
+```
+
+
 #### 4.6 Redis
 
 ##### 4.6.1 Select Redis version
@@ -611,7 +672,7 @@ If you also want to change the listening address (default: 127.0.0.1) to somethi
 
 | `.env` file variable name | Default | Note |
 |---------------------------|---------|------|
-| HOST_PATH_MONGO_DATADIR   | `./data/mongo`   | Can be absolute or relative path. A relative path starts inside the devilbox git directory. |
+| HOST_PATH_MONGO_DATADIR   | `./data/mongo`   | Can be absolute or relative path. A relative path starts inside the devilbox git directory.<br/><strong>Note:</strong> Container need to be re-created after changing this value. |
 
 This is the file system path on your host computer which will hold the MongoDB data.
 
@@ -628,6 +689,21 @@ drwxrwxr-x 6 48 48 4096 Jun 21 08:47 3.4/
 drwxrwxr-x 6 48 48 4096 Jun 21 08:47 3.5/
 ```
 
+**IMPORTANT:** When changing this path, you must re-create any affected Docker container explicitly. This can be accomplished by doing the following:
+
+```shell
+# Stop the container
+$ docker-compose stop
+
+# Remove the stopped container (IMPORTANT!)
+# After the removal it will be re-created during next run
+$ docker-compose rm -f
+
+# Start your stack
+$ docker-compose up -d
+```
+
+
 #### 4.9 Bind
 
 ##### 4.9.1 Upstream resolver

docs/FAQ.md

@@ -21,6 +21,7 @@ FAQ
 1. [General](#1-general)
 2. [Configuration](#2-configuration)
 3. [Usage](#3-usage)
+4. [Troubleshooting](#4-troubleshooting)
 
 ---
 
@@ -152,3 +153,19 @@ Yes, see **[How to setup Yii](Examples.md#8-setup-yii)**.
 
 Yes, see **[How to setup Zend](Examples.md#9-setup-zend)**.
 
+
+## 4. Troubleshooting
+
+**`Invalid bind mount spec` after changing the path of MySQL, PgSQL, Mongo or the Data dir.**
+
+When you change any paths inside `.env` that affect Docker mountpoints, the container need to be *removed* and re-created during the next startup. *Removing* the container is sufficient as they will always be created during run if they don't exist.
+
+In order to *remove* the container do the following:
+
+```shell
+$ docker-compose stop
+
+# Remove the stopped container (IMPORTANT!)
+# After the removal it will be re-created during next run
+$ docker-compose rm -f
+```

docs/Quickstart.md

@@ -83,6 +83,16 @@ Edit all general settings inside the .env file (file paths, what version to run,
 $ vim .env
 ```
 
+**Important:** When changing any path variables, you will have to stop all container, delete them so that they can be re-created during the next startup.
+
+```shell
+$ docker-compose stop
+
+# Remove the stopped container (IMPORTANT!)
+# After the removal it will be re-created during next run
+$ docker-compose rm -rf
+```
+
 #### 3.2 Services
 
 Additionally to configure the devilbox in general, you can also configure each service separately by adding/altering service specific configuration files.