DVL-016 Technical documentation

docs/Examples.md

@@ -6,7 +6,7 @@
 **Configuration** |
 **[Usage](Usage.md)** |
 **Examples** |
-**Technical** |
+**[Technical](Technical.md)** |
 **[Hacking](Hacking.md)** |
 **[FAQ](FAQ.md)**
 

docs/FAQ.md

@@ -6,7 +6,7 @@
 **Configuration** |
 **[Usage](Usage.md)** |
 **[Examples](Examples.md)** |
-**Technical** |
+**[Technical](Technical.md)** |
 **[Hacking](Hacking.md)** |
 **FAQ**
 

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
+  <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
+```
+
+#### 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 <name>
+```

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

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
+<?php
+mysql_connect('127.0.0.1', 'user', 'pass');
+```

docs/Usage.md

@@ -6,7 +6,7 @@
 **Configuration** |
 **Usage** |
 **[Examples](Examples.md)** |
-**Technical** |
+**[Technical](Technical.md)** |
 **[Hacking](Hacking.md)** |
 **[FAQ](FAQ.md)**