diff --git a/docs/Examples.md b/docs/Examples.md index 7a861902..52581cff 100644 --- a/docs/Examples.md +++ b/docs/Examples.md @@ -6,7 +6,7 @@ **Configuration** | **[Usage](Usage.md)** | **Examples** | -**Technical** | +**[Technical](Technical.md)** | **[Hacking](Hacking.md)** | **[FAQ](FAQ.md)** diff --git a/docs/FAQ.md b/docs/FAQ.md index 46b71bf9..e2a34409 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -6,7 +6,7 @@ **Configuration** | **[Usage](Usage.md)** | **[Examples](Examples.md)** | -**Technical** | +**[Technical](Technical.md)** | **[Hacking](Hacking.md)** | **FAQ** diff --git a/docs/Hacking.md b/docs/Hacking.md index 94542440..062ac2d4 100644 --- a/docs/Hacking.md +++ b/docs/Hacking.md @@ -6,7 +6,7 @@ **Configuration** | **[Usage](Usage.md)** | **[Examples](Examples.md)** | -**Technical** | +**[Technical](Technical.md)** | **Hacking** | **[FAQ](FAQ.md)** @@ -14,10 +14,44 @@ ## Hacking -1. [Adding your own docker container](#) +1. [Adding your own docker container](#1-adding-your-own-docker-container) --- ### 1. Adding your own docker container +You can add your custom docker container including its configuration to `docker-compose.yml`. + +#### 1.1 What information will you need? + +1. A name that you can use to refer to in the docker-compose command +2. The image name +3. The image version or `latest` +4. An unused IP address from the devilbox network + +#### 1.2 How to add your service? + +1. Open `docker-compose.yml` +2. Paste the following snippet with your replaced values just below the `services:` line (with one level of indentation) + +```yml + : + image: : + networks: + app_net: + ipv4_address: + # For ease of use always automatically start these: + depends_on: + - bind + - php + - httpd +``` + +#### 1.3 How to start your service? + +```shell +# The following will bring up your service including all the +# dependent services (bind, php and httpd) +$ docker-compose up +``` diff --git a/docs/README.md b/docs/README.md index d98830a2..34012935 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,7 +6,7 @@ **Configuration** | **[Usage](Usage.md)** | **[Examples](Examples.md)** | -**Technical** | +**[Technical](Technical.md)** | **[Hacking](Hacking.md)** | **[FAQ](FAQ.md)** @@ -66,6 +66,7 @@ If you have never worked with docker/docker-compose before, you should check up | **[Usage](Usage.md)** | How to create projects, Email and DNS usage, tools (`composer`, `npm`, `node`, `drush`, ...), entering the container, Log files, Xdebug, Backups, Intranet, ...| | **[Examples](Examples.md)** | Some project examples for popular CMS/Frameworks. How to setup Wordpress, Drupal, Yii, ... | | **Technical** | Technical background information | +| **[Hacking](Hacking.md)**| How to extend the devilbox with your own docker container | | **[FAQ](FAQ.md)** | Questions and Troubleshooting | @@ -75,6 +76,3 @@ Have a look at youtube to see all the features in action. [![Devilbox setup and workflow](img/devilbox_01-setup-and-workflow.png "devilbox - setup and workflow")](https://www.youtube.com/watch?v=reyZMyt2Zzo) [![Devilbox email catch-all](img/devilbox_02-email-catch-all.png "devilbox - email catch-all")](https://www.youtube.com/watch?v=e-U-C5WhxGY) - - - diff --git a/docs/Technical.md b/docs/Technical.md new file mode 100644 index 00000000..52c502a7 --- /dev/null +++ b/docs/Technical.md @@ -0,0 +1,103 @@ +# Devilbox Documentation + +**[Overview](README.md)** | +**Installing** | +**Updating** | +**Configuration** | +**[Usage](Usage.md)** | +**[Examples](Examples.md)** | +**Technical** | +**[Hacking](Hacking.md)** | +**[FAQ](FAQ.md)** + +--- + +## Technical + +1. [Networking](#1-networking) +2. [Ports and forwarding](#2-ports-and-forwarding) + 1. [PHP Container](#2-1-php-container) + 2. [Docker Host](#2-2-docker-host) +3. [Works the same on Host and PHP Container](#3-works-the-same-on-host-and-php-container) + +--- + +### 1. Networking + +It is best to use the hostnames and not to rely on the ip addresses as they might change. In most cases however you can use `127.0.0.1` for all connections. Read up to find out why. + +> E.g.: When you want to setup a MySQL database connection use `mysql` or `127.0.0.1` as the hostname. + +| Container | Container name | Hostname | IP Address | +|-----------------|-----------------|-----------|----------------| +| DNS | bind | bind | 172.16.238.100 | +| PHP / HHVM | php | php | 172.16.238.10 | +| Apache / Nginx | http | http | 172.16.238.11 | +| MySQL / MariaDB | mysql | mysql | 172.16.238.12 | +| PostgreSQL | pgsql | pgsql | 172.16.238.13 | +| Redis | redis | redis | 172.16.238.14 | +| Memcached | memcd | memcd | 172.16.238.15 | +| MongoDB | mongo | mongo | 172.16.238.16 | + +### 2. Ports and forwarding + +#### 2.1 PHP Container + +The `php` container is the center of all container. Everything happens in there. +This is also the reason it does some more magic than actually required. + +**Remote ports and remote sockets are made available to the `php` container.** + +The PHP container is using [socat](https://linux.die.net/man/1/socat) to + +1. forward the remote mysql port `3306` (on the mysql container) to its own `127.0.0.1:3306` +2. forward the remote pgsql port `5432` (on the pgsql container) to its own `127.0.0.1:5432` +3. forward the remote redis port `6379` (on the redis container) to its own `127.0.0.1:6379` +4. forward the remote memcached port `11211` (on the memcd container) to its own `127.0.0.1:11211` +5. forward the remote mongodb port `27017` (on the mongo container) to its own `127.0.0.1:27017` + +The following container can be reached from within the PHP container via the following methods: + +| Container | Hostname | IP Address | IP Address | Port | +|-----------------|-----------|----------------|------------|-------| +| DNS | bind | 172.16.238.100 | - | 53 | +| PHP / HHVM | php | 172.16.238.10 | - | 9000 | +| Apache / Nginx | http | 172.16.238.11 | - | 80 | +| MySQL / MariaDB | mysql | 172.16.238.12 | 127.0.0.1 | 3306 | +| PostgreSQL | pgsql | 172.16.238.13 | 127.0.0.1 | 5432 | +| Redis | redis | 172.16.238.14 | 127.0.0.1 | 6379 | +| Memcached | memcd | 172.16.238.15 | 127.0.0.1 | 11211 | +| MongoDB | mongo | 172.16.238.16 | 127.0.0.1 | 27017 | + + +#### 2.2 Docker Host + +The docker host (your computer) does exactly the same as the `php` container. + +1. container mysql port `3306` is exposed to the host on port `127.0.0.1:3306` +2. container pgsql port `5432` is exposed to the host on port `127.0.0.1:5432` +3. container redis port `6379` is exposed to the host on port `127.0.0.1:6379` +3. container memcd port `11211` is exposed to the host on port `127.0.0.1:11211` +3. container mongo port `27017` is exposed to the host on port `127.0.0.1:27017` + +The following container can be reached from the Docker host via the following methods: + +| Container | IP Address | Port | +|-----------------|------------|-------| +| DNS | 127.0.0.1 | 53 | +| PHP / HHVM | - | 9000 | +| Apache / Nginx | 127.0.0.1 | 80 | +| MySQL / MariaDB | 127.0.0.1 | 3306 | +| PostgreSQL | 127.0.0.1 | 5432 | +| Redis | 127.0.0.1 | 6379 | +| Memcached | 127.0.0.1 | 11211 | +| MongoDB | 127.0.0.1 | 27017 | + +### 3. Works the same on Host and PHP Container + +As you might have noticed, the ports and addresses will be exactly the same inside the PHP container and on the docker host (when using `127.0.0.1`) for most container. That way it is possible to write your php application like this: + +```php +