From 4012bfd2cf0119a5d020b8feb84f178223b9ded9 Mon Sep 17 00:00:00 2001 From: cytopia Date: Tue, 3 Apr 2018 14:35:32 +0200 Subject: [PATCH] Documentation: hacking --- docs/support/hacking.rst | 199 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 docs/support/hacking.rst diff --git a/docs/support/hacking.rst b/docs/support/hacking.rst new file mode 100644 index 00000000..fdf73a4f --- /dev/null +++ b/docs/support/hacking.rst @@ -0,0 +1,199 @@ +.. _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