mirror of
https://github.com/cytopia/devilbox.git
synced 2025-06-18 15:18:14 +00:00
cytopia
179
docs/tutorials/add-your-own-docker-image.rst
Normal file
179
docs/tutorials/add-your-own-docker-image.rst
Normal file
@ -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`
|
||||
114
docs/tutorials/overwrite-existing-docker-image.rst
Normal file
114
docs/tutorials/overwrite-existing-docker-image.rst
Normal file
@ -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`
|
||||
Reference in New Issue
Block a user