Add documentation for #222 #229: Custom docker images

2025-06-19 15:43:50 +00:00 · 2018-04-25 00:24:47 +02:00
parent ba233165ab
commit f0834dc9c5
8 changed files with 411 additions and 200 deletions
--- a/docs/tutorials/overwrite-existing-docker-image.rst
+++ b/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`