diff --git a/docker-compose.override.yml-example b/docker-compose.override.yml-example new file mode 100644 index 00000000..b93885a9 --- /dev/null +++ b/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 diff --git a/docker-compose.yml b/docker-compose.yml index 218ddeaa..2954392b 100644 --- a/docker-compose.yml +++ b/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' diff --git a/docs/configuration-files/docker-compose-override-yml.rst b/docs/configuration-files/docker-compose-override-yml.rst new file mode 100644 index 00000000..630e3933 --- /dev/null +++ b/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 `_ + + +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` diff --git a/docs/configuration-files/docker-compose-yml.rst b/docs/configuration-files/docker-compose-yml.rst new file mode 100644 index 00000000..9acce8fa --- /dev/null +++ b/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` diff --git a/docs/index.rst b/docs/index.rst index c0f4c9be..e30468e6 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/support/hacking.rst b/docs/support/hacking.rst deleted file mode 100644 index fdf73a4f..00000000 --- a/docs/support/hacking.rst +++ /dev/null @@ -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: - : - image: : - networks: - app_net: - ipv4_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 `_ -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 ```` with the -name you have chosen. - -.. code-block:: bash - - host> docker-compose up diff --git a/docs/tutorials/add-your-own-docker-image.rst b/docs/tutorials/add-your-own-docker-image.rst new file mode 100644 index 00000000..472f6a83 --- /dev/null +++ b/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. ```` - 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 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: + : + image: : + networks: + app_net: + ipv4_address: + # For ease of use always automatically start these: + depends_on: + - bind + - php + - httpd + # End of custom Docker image + +.. note:: + * ```` has to be replaced with any name of your choice + * ```` has to be replaced with the name of the Docker image + * ```` has to be replaced with the tag of the Docker image + * ```` 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: + : + image: : + networks: + app_net: + ipv4_address: + # 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: + : + image: : + networks: + app_net: + ipv4_address: + # For ease of use always automatically start these: + depends_on: + - bind + - php + - httpd + # End of second custom Docker image + +.. note:: + * ```` has to be replaced with any name of your choice + * ```` has to be replaced with the name of the Docker image + * ```` has to be replaced with the tag of the Docker image + * ```` has to be replaced with an unused IP address + +.. note:: + * ```` has to be replaced with any name of your choice + * ```` has to be replaced with the name of the Docker image + * ```` has to be replaced with the tag of the Docker image + * ```` has to be replaced with an unused IP address + + +CockroachDB example +------------------- + +Gather the requirements for the `Cockroach DB `_ +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 ```` with the +name you have chosen. + +.. code-block:: bash + + host> docker-compose up + +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` diff --git a/docs/tutorials/overwrite-existing-docker-image.rst b/docs/tutorials/overwrite-existing-docker-image.rst new file mode 100644 index 00000000..57f65ae0 --- /dev/null +++ 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`