ExternalVendorCode/devilbox
1
0
Fork 0
mirror of https://github.com/cytopia/devilbox.git synced 2025-04-12 21:33:02 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge pull request #231 from cytopia/DVL-014

Browse Source 
Add documentation for #222 #229: Custom docker images
This commit is contained in:
cytopia 2018-04-25 01:02:35 +02:00 committed by GitHub
commit 14d759d18b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 411 additions and 200 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
docker-compose.override.yml-example Normal file
View File

@ -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

3
docker-compose.yml
View File

@ -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'

75
docs/configuration-files/docker-compose-override-yml.rst Normal file
View File

@ -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`

13
docs/configuration-files/docker-compose-yml.rst Normal file
View File

@ -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`

5
docs/index.rst
View File

@ -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

199
docs/support/hacking.rst
View File

@ -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>

179
docs/tutorials/add-your-own-docker-image.rst Normal file
View 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
View 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`