Add documentation for #222 #229: Custom docker images

docker-compose.override.yml-example

@@ -0,0 +1,23 @@
+# IMPORTANT: The version must match the version of docker-compose.yml
+version: '2.1'
+
+# The following override shows an example for the cockroachdb
+services:
+  # Your custom Docker image here:
+  cockroach:
+    image: cockroachdb/cockroach:latest
+    command: start --insecure
+    # Ensure the chosen ports are not occupied on the host system
+    ports:
+      - "${LOCAL_LISTEN_ADDR}26257:26257"
+      - "${LOCAL_LISTEN_ADDR}8080:8080"
+    networks:
+      app_net:
+        # Ensure to pick an IP address from docker-compose.yml network
+        # that is not yet taken by other sevices
+        ipv4_address: 172.16.238.200
+    # (Optional) For ease of use always automatically start these:
+    depends_on:
+      - bind
+      - php
+      - httpd

docker-compose.yml

@@ -12,6 +12,9 @@
 ##
 ## -- DO NOT EDIT THIS FILE --
 ##
+## Copy 'docker-compose.override.yml-example' to 'docker-compose.override.yml'
+## and edit this file with your custom changes (override or even new services).
+##
 ## Edit '.env' for configuration.
 ##
 ## If '.env' does not exist, copy 'env-example' to '.env'

docs/configuration-files/docker-compose-override-yml.rst

@@ -0,0 +1,75 @@
+.. _docker_compose_override_yml:
+
+***************************
+docker-compose.override.yml
+***************************
+
+The ``docker-compose.override.yml`` is the configuration file where you can override existing settings from ``docker-compose.yml`` or even add completely new services.
+
+By default, this file does not exist and you must create it. You can either copy the existing ``docker-compose.override.yml-example`` or create a new one.
+
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+.. seealso:: Official Docker documentation: `Share Compose configurations between files and projects <https://docs.docker.com/compose/extends>`_
+
+
+Create docker-compose.override.yml
+==================================
+
+Copy example file
+-----------------
+
+.. code-block:: bash
+
+    host> cd path/to/devilbox
+    host> cp docker-compose.override.yml-example docker-compose.override.yml
+
+
+Create new file from scratch
+----------------------------
+
+1. Create an empty file within the Devilbox git directory named ``docker-compose.override.yml``
+2. Retrieve the currently used version from the existing ``docker-compose.yml`` file
+3. Copy this version line to your newly created ``docker-compose.override.yml`` at the very top
+
+.. code-block:: bash
+
+    # Create an empty file
+    host> cd path/to/devilbox
+    host> touch docker-compose.override.yml
+
+    # Retrieve the current version
+    host> grep ^version docker-compose.yml
+    version: '2.1'
+
+    # Add this version line to docker-compose.override.yml
+    host> echo "version: '2.1'" > docker-compose.override.yml
+
+Let's see again how this file should look like now:
+
+.. code-block:: yaml
+    :name: docker-compose.override.yml
+    :caption: docker-compose.override.yml
+
+    version: '2.1'
+
+
+
+.. note::
+    The documentation might be outdated and the version number might already be higher.
+    Rely on the output of the ``grep`` command.
+
+
+Further reading
+===============
+
+To dive deeper into this topic and see how to actually add new services or overwrite existing
+services follow the below listed links:
+
+.. seealso::
+    * :ref:`add_your_own_docker_image`
+    * :ref:`overwrite_existing_docker_image`

docs/configuration-files/docker-compose-yml.rst

@@ -0,0 +1,13 @@
+.. _docker_compose_yml:
+
+******************
+docker-compose.yml
+******************
+
+This file is the core of the Devilbox and glues together all Docker images.
+
+It is very tempting to just change this file in order to add new services to the already existing once.
+However your git directory will become dirty and you will always have to stash your changes before pulling new features from remote. To overcome this Docker Compose offers a default override file (``docker-compose.override.yml``) that let's you specify custom changes as well as completely new services without having to touch the default ``docker-compose.yml``.
+
+.. seealso::
+    To find out more read :ref:`docker_compose_override_yml`

docs/index.rst

@@ -65,6 +65,8 @@ host is ready to be served with your custom domain.
    :maxdepth: 2
    :caption: Tutorials
 
+   tutorials/add-your-own-docker-image
+   tutorials/overwrite-existing-docker-image
    tutorials/adding-subdomains
    tutorials/configure-database-in-your-project
    tutorials/change-document-root
@@ -124,6 +126,8 @@ host is ready to be served with your custom domain.
    :maxdepth: 2
 
    configuration-files/env-file
+   configuration-files/docker-compose-yml
+   configuration-files/docker-compose-override-yml
    configuration-files/apache-conf
    configuration-files/nginx-conf
    configuration-files/php-ini
@@ -158,7 +162,6 @@ host is ready to be served with your custom domain.
 
    support/faq
    support/troubleshooting
-   support/hacking
    support/contributing
    support/blogs-videos-and-use-cases
    support/artwork

docs/support/hacking.rst

@@ -1,199 +0,0 @@
-.. _hacking:
-
-*******
-Hacking
-*******
-
-This section is all about customizing the Devilbox and its Docker images specifically to your needs.
-
-
-**Table of Contents**
-
-.. contents:: :local:
-
-
-
-Rebuilding Docker images
-========================
-
-The Devilbox Docker images are rebuilt frequently and automatically pushed to Dockerhub.
-However there might be cases in which you want to rebuild right away in order to use have custom
-tools installed or of any other reason.
-
-
-How to rebuild?
----------------
-
-MySQL and Web server images
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-All MySQL (including MariaDB and PerconaDB) images as well as the web server images provide
-shell scripts that makes rebuilding the image very simple.
-
-Each of those repositores contain two shell scripts for building normally and rebuilding
-without cache:
-
-* ``build/docker-build.sh``
-* ``build/docker-rebuild.sh``
-
-So you basically just clone the corresponding repository to your computer, edit the ``Dockerfile``
-to your needs and run one of the scripts.
-
-The following shows an example for Apache 2.2
-
-.. code-block:: bash
-
-    # Clone the repository and enter its directory
-    host> git clone https://github.com/devilbox/docker-apache-2.2
-    host> cd docker-apache-2.2
-
-    # Edit the Dockerfile to your needs
-    host> vi Dockerfile
-
-    # Build the Docker image
-    host> ./build/docker-build.sh
-
-PHP-FPM images
-^^^^^^^^^^^^^^
-
-The repository for PHP Docker images contains all version and hence multiple Dockerfiles.
-The build procedure is slightly different as those Dockerfiles are generated via Ansible
-build afterwards. Refer to its original repository for more detailed instructions.
-
-A very basic description is as follows:
-
-.. code-block:: bash
-
-    # Clone the repository and enter its directory
-    host> git https://github.com/devilbox/docker-php-fpm
-    host> cd docker-php-fpm
-
-    # Edit the Dockerfile template for the 'work' images
-    host> vi build/ansible/DOCKERFILES/Dockerfile-work.j2
-
-    # Generate the actual Dockerfiles
-    host> make generate
-
-    # Build one specific PHP version (in this case PHP 5.5)
-    host> make build-work-55
-
-
-How to use the rebuild images?
-------------------------------
-
-For the PHP-FPM images you do not have to do anything, as they are built with the image tag that
-is already present in ``docker-compose.yml``. For all other images you might have to adjust
-the image tag in ``docker-compose.yml`` as all images will be built with the ``latest`` tag by
-default.
-
-If you have built Apache 2.2 for example, open the ``docker-compose.yml`` file inside the Devilbox
-git directory and ensure that the current image tag is replaced with ``latest``.
-
-How it could look by default:
-
-.. code-block:: yaml
-    :caption: docker-compose.yml
-    :name: docker-compose.yml
-    :emphasize-lines: 2
-
-    httpd:
-      image: devilbox/${HTTPD_SERVER:-nginx-stable}:0.13
-
-How it should look with latest tag:
-
-.. code-block:: yaml
-    :caption: docker-compose.yml
-    :name: docker-compose.yml
-    :emphasize-lines: 2
-
-    httpd:
-      image: devilbox/${HTTPD_SERVER:-nginx-stable}:latest
-
-
-Adding your own Docker image
-============================
-
-The Devilbox is at its core just a ``docker-compose.yml`` file which easily gives you the option
-to add other Docker images it is currently lacking.
-
-
-What information do you need?
------------------------------
-
-1. A name, which you can use to refer in the ``docker-compose`` command
-2. The Docker image name itself
-3. The Docker image tag
-4. An unused IP address from the devilbox network (found inside ``docker-compose.yml``)
-
-
-How to add the image?
----------------------
-
-General example
-^^^^^^^^^^^^^^^
-
-Open ``docker-compose.yml`` with your favourite editor and paste the following snippet
-below the ``services:`` line with one level of indentation:
-
-.. code-block:: yaml
-    :caption: docker-compose.yml
-    :name: docker-compose.yml
-    :emphasize-lines: 3-4,7
-
-    services:
-      # Your custom Docker image here:
-      <name>:
-        image: <image-name>:<image-version>
-        networks:
-          app_net:
-            ipv4_address: <unused-ip-address>
-        # For ease of use always automatically start these:
-        depends_on:
-          - bind
-          - php
-          - httpd
-      # End of custom Docker image
-
-Cockroach DB example
-^^^^^^^^^^^^^^^^^^^^
-
-Gather the requirements for the `Cockroach DB <https://hub.docker.com/r/cockroachdb/cockroach/>`_
-Docker image:
-
-1. Name: ``cockroach``
-2. Image: ``cockroachdb/cockroach``
-3. Tag: ``latest``
-4. IP: ``172.16.238.200``
-
-Now add the information to ``docker-compose.yml`` just below the ``services:`` line:
-
-.. code-block:: yaml
-    :caption: docker-compose.yml
-    :name: docker-compose.yml
-    :emphasize-lines: 3-4,7
-
-    services:
-      # Your custom Docker image here:
-      cockroach:
-        image: cockroachdb/cockroach:latest
-        networks:
-          app_net:
-            ipv4_address: 172.16.238.200
-        # For ease of use always automatically start these:
-        depends_on:
-          - bind
-          - php
-          - httpd
-      # End of custom Docker image
-
-
-How to start the new service?
------------------------------
-
-The following will bring up your service including all of its dependent services,
-as defined with ``depends_on`` (bind, php and httpd). You need to replace ``<name>`` with the
-name you have chosen.
-
-.. code-block:: bash
-
-    host> docker-compose up <name>

docs/tutorials/add-your-own-docker-image.rst

@@ -0,0 +1,179 @@
+.. _add_your_own_docker_image:
+
+*************************
+Add your own Docker image
+*************************
+
+This section is all about customizing the Devilbox and its Docker images specifically to your needs.
+
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+Prerequisites
+=============
+
+The new Docker image definition will be added to a file called ``docker-compose.override.yml``.
+So before going any further, read the following section that shows you how to create this file
+for the Devilbox as well as what pitfalls to watch out for.
+
+.. seealso:: :ref:`docker_compose_override_yml`
+
+
+What information do you need?
+=============================
+
+1. ``<name>`` - A name, which you can use to refer in the ``docker-compose`` command
+2. ``<image-name>`` - The Docker image name itself
+3. ``<image-version>`` - The Docker image tag
+4. ``<unused-ip-address>`` - An unused IP address from the devilbox network (found inside ``docker-compose.yml``)
+
+
+How to add a new service?
+=========================
+
+Generic example
+---------------
+
+A single new service
+^^^^^^^^^^^^^^^^^^^^
+
+Open ``docker-compose.override.yml`` with your favourite editor and paste the following snippets
+into it.
+
+.. code-block:: yaml
+    :caption: docker-compose.override.yml
+    :name: docker-compose.override.yml
+    :emphasize-lines: 4,5,8
+
+    version: '2.1'
+    services:
+      # Your custom Docker image here:
+      <name>:
+        image: <image-name>:<image-version>
+        networks:
+          app_net:
+            ipv4_address: <unused-ip-address>
+        # For ease of use always automatically start these:
+        depends_on:
+          - bind
+          - php
+          - httpd
+      # End of custom Docker image
+
+.. note::
+    * ``<name>`` has to be replaced with any name of your choice
+    * ``<image-name>`` has to be replaced with the name of the Docker image
+    * ``<image-version>`` has to be replaced with the tag of the Docker image
+    * ``<unused-ip-address>`` has to be replaced with an unused IP address
+
+Two new services
+^^^^^^^^^^^^^^^^
+
+.. code-block:: yaml
+    :caption: docker-compose.override.yml
+    :name: docker-compose.override.yml
+    :emphasize-lines: 4,5,8,16,17,20
+
+    version: '2.1'
+    services:
+      # Your first custom Docker image here:
+      <name1>:
+        image: <image1-name>:<image1-version>
+        networks:
+          app_net:
+            ipv4_address: <unused-ip-address1>
+        # For ease of use always automatically start these:
+        depends_on:
+          - bind
+          - php
+          - httpd
+      # End of first custom Docker image
+      # Your second custom Docker image here:
+      <name2>:
+        image: <image2-name>:<image2-version>
+        networks:
+          app_net:
+            ipv4_address: <unused-ip-address2>
+        # For ease of use always automatically start these:
+        depends_on:
+          - bind
+          - php
+          - httpd
+      # End of second custom Docker image
+
+.. note::
+    * ``<name1>`` has to be replaced with any name of your choice
+    * ``<image1-name>`` has to be replaced with the name of the Docker image
+    * ``<image1-version>`` has to be replaced with the tag of the Docker image
+    * ``<unused-ip-address1>`` has to be replaced with an unused IP address
+
+.. note::
+    * ``<name2>`` has to be replaced with any name of your choice
+    * ``<image2-name>`` has to be replaced with the name of the Docker image
+    * ``<image2-version>`` has to be replaced with the tag of the Docker image
+    * ``<unused-ip-address2>`` has to be replaced with an unused IP address
+
+
+CockroachDB example
+-------------------
+
+Gather the requirements for the `Cockroach DB <https://hub.docker.com/r/cockroachdb/cockroach/>`_
+Docker image:
+
+1. Name: ``cockroach``
+2. Image: ``cockroachdb/cockroach``
+3. Tag: ``latest``
+4. IP: ``172.16.238.200``
+
+Now add the information to ``docker-compose.override.yml``:
+
+.. code-block:: yaml
+    :caption: docker-compose.override.yml
+    :name: docker-compose.override.yml
+    :emphasize-lines: 4-5,9
+
+    version: '2.1'
+    services:
+      # Your custom Docker image here:
+      cockroach:
+        image: cockroachdb/cockroach:latest
+        command: start --insecure
+        networks:
+          app_net:
+            ipv4_address: 172.16.238.200
+        # For ease of use always automatically start these:
+        depends_on:
+          - bind
+          - php
+          - httpd
+      # End of custom Docker image
+
+
+
+How to start the new service?
+=============================
+
+The following will bring up your service including all of its dependent services,
+as defined with ``depends_on`` (bind, php and httpd). You need to replace ``<name>`` with the
+name you have chosen.
+
+.. code-block:: bash
+
+    host> docker-compose up <name>
+
+In the example of Cockroach DB the command would look like this
+
+.. code-block:: bash
+
+    host> docker-compose up cockroach
+
+
+Further reading
+===============
+
+.. seealso::
+    * :ref:`docker_compose_override_yml`
+    * :ref:`overwrite_existing_docker_image`

docs/tutorials/overwrite-existing-docker-image.rst

@@ -0,0 +1,114 @@
+.. _overwrite_existing_docker_image:
+
+*******************************
+Overwrite existing Docker image
+*******************************
+
+This section is all about customizing the Devilbox and its Docker images specifically to your needs.
+
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+Prerequisites
+=============
+
+The new Docker image overwrite will be added to a file called ``docker-compose.override.yml``.
+So before going any further, read the following section that shows you how to create this file
+for the Devilbox as well as what pitfalls to watch out for.
+
+.. seealso:: :ref:`docker_compose_override_yml`
+
+
+What information do you need?
+=============================
+
+1. The service to overwrite
+
+
+How to overwrite a service?
+===========================
+
+Generic steps
+-------------
+
+1. Copy the whole service definition from docker-compose.yml to docker-compose.override.yml
+2. Remove anything unecessary
+3. Adjust the values you need
+
+Overwrite Docker image for the bind service
+-------------------------------------------
+
+The following example is using the ``bind`` service and overrides the Docker image
+to illustrate how this is done :
+
+
+First you simply copy the while definition of the bind service from ``docker-compose.yml`` to
+``docker-compose.override.yml``:
+
+.. code-block:: yaml
+    :name: docker-compose.override.yml
+    :caption: docker-compose.override.yml
+
+    version: '2.1'
+    services:
+      bind:
+        image: cytopia/bind:0.11
+        restart: always
+        ports:
+          # [local-machine:]local-port:docker-port
+          - "${LOCAL_LISTEN_ADDR}${HOST_PORT_BIND:-1053}:53"
+          - "${LOCAL_LISTEN_ADDR}${HOST_PORT_BIND:-1053}:53/udp"
+
+        environment:
+          ##
+          ## Debug?
+          ##
+          - DEBUG_ENTRYPOINT=${DEBUG_COMPOSE_ENTRYPOINT}
+          - DOCKER_LOGS=1
+
+          ##
+          ## Bind settings
+          ##
+          - WILDCARD_ADDRESS=172.16.238.11
+          - DNS_FORWARDER=${BIND_DNS_RESOLVER:-8.8.8.8,8.8.4.4}
+
+        dns:
+          - 127.0.0.1
+
+        networks:
+          app_net:
+            ipv4_address: 172.16.238.100
+
+The second step is to remove everything that you do not need to overwrite:
+
+.. code-block:: yaml
+    :name: docker-compose.override.yml
+    :caption: docker-compose.override.yml
+
+    version: '2.1'
+    services:
+      bind:
+        image: cytopia/bind:0.11
+
+The last step is to actually adjust the value you want to change for the bind service:
+
+.. code-block:: yaml
+    :name: docker-compose.override.yml
+    :caption: docker-compose.override.yml
+    :emphasize-lines: 4
+
+    version: '2.1'
+    services:
+      bind:
+        image: someother/bind:latest
+
+
+Further reading
+===============
+
+.. seealso::
+    * :ref:`docker_compose_override_yml`
+    * :ref:`add_your_own_docker_image`