devilbox/docs/Hacking.md

Devilbox Documentation

Overview | Quickstart | Install | Update | Configure | Run | Usage | OS | Backups | Examples | Technical | Hacking | FAQ

---

Hacking

1. Rebuilding bundled Docker container
2. Why rebuild yourself?
3. How to rebuild yourself?
4. How to use the rebuild container?
5. Customizing the bundled Docker container
6. Adding your own Docker container
7. What information will you need?
8. How to add your service?
9. How to start your service?

---

1. Rebuilding bundled Docker container

The devilbox Docker container are rebuild frequently and pushed to dockerhub. However there might be cases in which you want to rebuild right away in order to use a new minor version of a tool inside the container.

1.1 Why rebuild yourself?

Imagine for example you are using the PHP 7.1 container which currently is available with the version 7.1.6. You found that PHP 7.1.7 has just been released, but the container wasn't yet updated to that version. If you can't wait and need that version now, you can just update the container to that version yourself.

1.2 How to rebuild yourself?

Rebuilding yourself has been made pretty easy. The devilbox docker container repositories come with two scripts for automatic rebuilding. build/docker-build.sh and build/docker-rebuild.sh.

1. Clone or fork and clone the desired docker repository to your computer
2. Run build/docker-build.sh (cached build) or build/docker-rebuild.sh (uncached build)

Either of the two above scripts will rebuild the desired docker container with the latest available versions. The rebuild docker container will then be available locally by the tag latest

1.3 How to use the rebuild container?

1.3.1 Tagged devilbox repository

If your devilbox git repository is checked out on a git tag, then also the docker container are bound to specific docker tags. It will look like this in docker-compose.yml:

  php:
     image: cytopia/${PHP_SERVER:-php-fpm-7.0}:0.10

Your newly rebuild latest docker container will not yet be available for the next run. You still need to change the docker-compose.yml and set the container to latest:

  php:
     image: cytopia/${PHP_SERVER:-php-fpm-7.0}:latest

1.3.2 devilbox repository on master branch

If your devilbox git repository is checkout out on the master branch, then all docker container are always bound to the latest docker tag inside docker-compose.yml and you do not need to change anything. Just rebuilding the container is enough to be picked up for the next start.

2. Customizing the bundled Docker container

Customizing a Docker container is almost as simple as rebuilding it.

1. Fork the desired docker repository
2. Clone your forked docker repository locally
3. Edit Dockerfile with your customization
4. Run build/docker-build.sh (cached build) or build/docker-rebuild.sh (uncached build)
5. Read the rebuild section above to apply necessary steps

3. Adding your own Docker container

You can add your custom docker container including its configuration to docker-compose.yml.

3.1 What information will you need?

1. A name that you can use to refer to in the docker-compose command
2. The Docker image name
3. The Docker image version or latest
4. An unused IP address from the devilbox network

3.2 How to add your service?

3.2.1 General example

1. Open docker-compose.yml
2. Paste the following snippet with your replaced values just below the services: line (with one level of indentation)

...
services:
  # Your custom Docker container 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 container
...

3.2.2 Specific example

Lets make a real example for adding Cockroach DB

1. Name: cockroach
2. Image: cockroachdb/cockroach
3. Version: latest
4. IP: 172.16.238.200

Now add the information to docker-compose.yml just below the services: line:

...
services:
  # Your custom Docker container 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 container
...

3.3 How to start your service?

# The following will bring up your service including all the
# dependent services (bind, php and httpd)
$ docker-compose up <name>