Merge pull request gcgarner#79 from SensorsIot/udpate-documentation-c…

…ustom-settings

Updated documentation for custom settings. Updated gitignore to inclu…

.gitignore

@@ -3,7 +3,9 @@
 /volumes/
 /backups/
 /.tmp/*
+__pycache__
 docker-compose.yml
+compose-override.yml
 .outofdate
 
 !.gitkeep

docs/Custom.md

@@ -1,14 +1,91 @@
-# Custom container
-If you have a container that you want to stop and start with the stack you can now use the custom container option. This you can use for testing or in prep for a Pull Request.
+# Custom containers and settings for docker-compose
+You can specify modifcations to the `docker-compose.yml` file, including your own networks and custom containers/services.
 
-You will need to create a directory for your container call `IOTstack/services/<container>`
+Create a file called `compose-override.yml` in the main directory, and place your modifications into it. These changes will be merged into the `docker-compose.yml` file next time you run the build script.
 
-Inside that container create a `service.yml` containing your service and configurations. Have a look at one of the other services for inspiration.
+## How it works
+1. After the build process has been completed, a temporary docker compose file is created in the `tmp` directory.
+2. The script then checks if `compose-override.yml` exists:
+    1. If it exists, then continue to step `3`
+    2. If it does not exist, copy the temporary docker compose file to the main directory and rename to `docker-compose.yml`.
+3. Using the `yaml_merge.py` script, merge both the `compose-override.yml` and the temporary docker compose file together; Using the temporary file as the default values and interating through each level of the yaml structure, check to see if the `compose-override.yml` has a value set.
+4. Output the final file to the main directory, calling it `docker-compose.yml`.
 
-Create a file called `IOTstack/services/custom.txt` and and enter your container names, one per line
+## Example
+For example, lets assume you put the following into the `compose-override.yml` file:
+```
+services:
+  mosquitto:
+    ports:
+      - 1996:1996
+      - 9001:9001
+```
 
-Run the menu.sh and build the stack. After you have made the selection you will be asked if you want to add the custom containers.
+Normally the mosquitto service would be built like this inside the `docker-compose.yml` file:
+```
+version: '3.6'
+services:
+  mosquitto:
+    container_name: mosquitto
+    image: eclipse-mosquitto
+    restart: unless-stopped
+    user: "1883"
+    ports:
+      - 1883:1883
+      - 9001:9001
+    volumes:
+      - ./volumes/mosquitto/data:/mosquitto/data
+      - ./volumes/mosquitto/log:/mosquitto/log
+      - ./volumes/mosquitto/pwfile:/mosquitto/pwfile
+      - ./services/mosquitto/mosquitto.conf:/mosquitto/config/mosquitto.conf
+      - ./services/mosquitto/filter.acl:/mosquitto/config/filter.acl
+```
 
-Now your container will be part of the docker-compose.yml file and will respond to the docker-compose up -d commands.
+Take special note of the ports list.
 
-Docker creates volumes under root and your container may require different ownership on the volume directory. You can see an example of the workaround for this in the python template in `IOTstack/.templates/python/directoryfix.sh`
+If you run the build script with the `compose-override.yml` file in place, and open up the final `docker-compose.yml` file, you will notice that the port list have been replaced with the ones you specified in the `compose-override.yml` file.
+```
+version: '3.6'
+services:
+  mosquitto:
+    container_name: mosquitto
+    image: eclipse-mosquitto
+    restart: unless-stopped
+    user: "1883"
+    ports:
+      - 1996:1996
+      - 9001:9001
+    volumes:
+      - ./volumes/mosquitto/data:/mosquitto/data
+      - ./volumes/mosquitto/log:/mosquitto/log
+      - ./volumes/mosquitto/pwfile:/mosquitto/pwfile
+      - ./services/mosquitto/mosquitto.conf:/mosquitto/config/mosquitto.conf
+      - ./services/mosquitto/filter.acl:/mosquitto/config/filter.acl
+```
+
+Do note that it will replace the entire list, if you were to specify
+```
+services:
+  mosquitto:
+    ports:
+      - 1996:1996
+```
+
+Then the final output will be:
+```
+version: '3.6'
+services:
+  mosquitto:
+    container_name: mosquitto
+    image: eclipse-mosquitto
+    restart: unless-stopped
+    user: "1883"
+    ports:
+      - 1996:1996
+    volumes:
+      - ./volumes/mosquitto/data:/mosquitto/data
+      - ./volumes/mosquitto/log:/mosquitto/log
+      - ./volumes/mosquitto/pwfile:/mosquitto/pwfile
+      - ./services/mosquitto/mosquitto.conf:/mosquitto/config/mosquitto.conf
+      - ./services/mosquitto/filter.acl:/mosquitto/config/filter.acl
+```