#1021 document lagoon base docker images

docs/administering_lagoon/create-project.gql

@@ -31,7 +31,7 @@ mutation {
       name: ""
       # TODO: Fill in the private key field
       # This is the private key for a project, which is used to access the git code.  If no private key is added, Lagoon will create a private key, which can later be accessed by loading the project.
-      privatekey: ""
+      privateKey: ""
       # TODO: Fill in the openshift field
       # This is the id of the OpenShift to assign to the project
       openshift: 0

docs/using_lagoon/docker_images/mariadb.md

@@ -0,0 +1,48 @@
+# MariaDB Image
+Lagoon `MariaDB` image Dockerfile, based on offical packages `mariadb` and `mariadb-client` provided by the `alpine:3.8` image.
+
+This Dockerfile is intended to be used to setup a standalone MariaDB database server.
+
+## Lagoon & OpenShift adaptions
+This image is prepared to be used on Lagoon which leverages OpenShift. There are therefore some things already done:
+
+- Folder permissions are automatically adapted with [`fix-permissions`](https://github.com/sclorg/s2i-base-container/blob/master/core/root/usr/bin/fix-permissions) so this image will work with a random user and therefore also on OpenShift.
+- `readiness-probe.sh` script to check when mariadb container's readiness.
+
+## Included tools
+
+- `mysqltuner.pl` - Perl script useful for database's parameters tuning
+- `mysql-backup.sh` - script for automating the daily mysql backups on development computer
+- `pwgen` - utility to generate random and complex passwords
+
+## Included `my.cnf` configuration file
+The image ships a *default* MariaDB configuration file, optimized to work on Lagoon.  
+Some options are configurable via environments variables (see [Environment Variables](#environment-variables)).
+
+## Environment Variables
+Environment variables defined in MariaDB base image
+
+| Environment Variable              | Default             | Description                                    |
+| ---------------------------------      | ---------      | ---------------------------------------------- |
+| `MARIADB_DATABASE`                     |   lagoon 	    | Database name created at startup               |
+| `MARIADB_USER`                         |   lagoon 	    | Default user created at startup                |
+| `MARIADB_PASSWORD`                     |   lagoon 	    | Password of default user createt at startup    |
+| `MARIADB_ROOT_PASSWORD`                |   Lag00n 	    | MariaDB root user's password                   |
+| `MARIADB_CHARSET`                      |   utf8mb4 	    | Set the server charset                         |
+| `MARIADB_COLLATION`                    |   utf8mb4_bin 	| Set server collation                           |
+| `MARIADB_INNODB_BUFFER_POOL_SIZE`      |   256M	        | Set the MariaDB InnoDB Buffer Pool Size        |
+| `MARIADB_INNODB_BUFFER_POOL_INSTANCES` |   1            | Number of InnoDB Buffer Pool instances         |
+| `MARIADB_INNODB_LOG_FILE_SIZE`         |   64M          | Size of InnoDB log file                        |
+| `MARIADB_LOG_SLOW`                     | empty          | Variable to control the save of slow queries   |
+| `MARIADB_LOG_QUERIES`                  | empty          | Variable to control the save of ALL queries    |
+| `BACKUPS_DIR`                          |  /var/lib/mysql/backup | Default path for databases' backups    |
+
+## MariaDB Drupal image
+Lagoon `mariadb-drupal` Docker image, is a customized `mariadb` image to use within Drupal projects in Lagoon.  
+It differs from `mariadb` only for initial database setup, made by some environment variables:
+
+| Environment Variable              | Default             | Description                                    |
+| ---------------------------------      | ---------      | ---------------------------------------------- |
+| `MARIADB_DATABASE`                     |   drupal 	    | Drupal database created at startup             |
+| `MARIADB_USER`                         |   drupal 	    | Default user created at startup                |
+| `MARIADB_PASSWORD`                     |   drupal 	    | Password of default user createt at startup    |

docs/using_lagoon/docker_images/mongo.md

@@ -0,0 +1,10 @@
+# MongoDB Image
+Lagoon `MongoDB` image Dockerfile, based on offical package `mongodb` provided by the `alpine:3.8` image.
+
+This Dockerfile is intended to be used to setup a standalone MongoDB database server.
+
+## Lagoon & OpenShift adaptions
+This image is prepared to be used on Lagoon which leverages OpenShift.  
+There are therefore some things already done:
+
+- Folder permissions are automatically adapted with [`fix-permissions`](https://github.com/sclorg/s2i-base-container/blob/master/core/root/usr/bin/fix-permissions) so this image will work with a random user and therefore also on OpenShift.

docs/using_lagoon/docker_images/nginx-drupal.md

@@ -0,0 +1,17 @@
+# nginx-drupal Image
+Lagoon `nginx-drupal` Docker image optimized to work with Drupal, based on Lagoon `nginx` image.
+
+## Lagoon & OpenShift adaptions
+This image is prepared to be used on Lagoon which leverages OpenShift.  
+There are therefore some things already done:
+
+- Folder permissions are automatically adapted with [`fix-permissions`](https://github.com/sclorg/s2i-base-container/blob/master/core/root/usr/bin/fix-permissions) so this image will work with a random user and therefore also on OpenShift.
+- For all file's section, there are two `include` directives: the `prepend*.conf` and the `append*.conf`. They allow to add and append custom configuration to `drupal.conf` file
+
+## Included Nginx Drupal configuration (drupal.conf)
+
+The image includes a full Drupal 7 and 8 Nginx working configuration. It includes some extra functionalities like:
+
+ - support for `humanstxt` drupal module
+ - support for `robotstxt` drupal module
+ - disallow access to `vagrant` directory for local development

docs/using_lagoon/docker_images/nginx.md

@@ -1,23 +1,24 @@
 # nginx Image
-amazee.io Alpine 7 Dockerfile with nginx installed, based on the official openresty Alpine images at (https://hub.docker.com/r/openresty/openresty/).
+Lagoon `nginx` image Dockerfile, based on official `openresty/openresty` images at (https://hub.docker.com/r/openresty/openresty/).  
 
-This Dockerfile is intended to be used as base for any webservers within amazee.io. By default the nginx only serves static files. If you need php have a look at the php-fpm image and use nginx and php-fpm in tandem.
+This Dockerfile is intended to be used as base for any webservers within Lagoon.  
+By default the nginx only serves static files. If you need php have a look at the `php-fpm` image and use nginx and php-fpm in tandem.
 
-## amazee.io & OpenShift adaptions
-This image is prepared to be used on amazee.io which leverages OpenShift. There are therefore some things already done:
+## Lagoon & OpenShift adaptions
+This image is prepared to be used on Lagoon which leverages OpenShift. There are therefore some things already done:
 
 - Folder permissions are automatically adapted with [`fix-permissions`](https://github.com/sclorg/s2i-base-container/blob/master/core/root/usr/bin/fix-permissions) so this image will work with a random user and therefore also on OpenShift.
 - The files within `/etc/nginx/*` are parsed through [envplate](https://github.com/kreuzwerker/envplate) with an container-entrypoint.
 
 ## Included Nginx configuration (static-files.conf)
-By default nginx only serves static files - this can be used for static sites that don't require a database or php components e.g. Static site generators like Hugo, Jekyll or Gatsby. Simply build the content during the build process and inject it into the nginx container.
+By default nginx only serves static files - this can be used for static sites that don't require a database or php components e.g. Static site generators like Hugo, Jekyll or Gatsby.  
+Simply build the content during the build process and inject it into the nginx container.
 
 ## Helpers
 ### redirects-map.conf
-In order to create redirects we have the redirects-map.conf in place. This helps you to redirect marketing domains to subsites or do non-www to www redirects.
-If you have a lot of redirects we suggest to have the `redirects-map.conf` stored next to your code for easier maintainability.
-If you just have a few redirects there's a handy trick to create the redirects with a `RUN` command in your `nginx.dockerfile`.
-
+In order to create redirects we have the `redirects-map.conf` in place. This helps you to redirect marketing domains to subsites or do non-www to www redirects.  
+If you have a lot of redirects we suggest to have the `redirects-map.conf` stored next to your code for easier maintainability.  
+If you just have a few redirects there's a handy trick to create the redirects with a `RUN` command in your `nginx.dockerfile`.  
 
 Example for redirecting `www.example.com` to `example.com` and preserving the request.
 
@@ -26,21 +27,20 @@ RUN echo "~^www.example.com           http://example.com\$request_uri;" >> /etc/
 
 ```
 
-To get more details about the various types of redirects that can be achieved see the documentation within the [redirects-map.conf](https://github.com/amazeeio/lagoon/blob/master/images/nginx/redirects-map.conf) directly.
+To get more details about the various types of redirects that can be achieved see the documentation within the [redirects-map.conf](https://github.com/amazeeio/lagoon/blob/master/images/nginx/redirects-map.conf) directly.  
 
-After you put the `redirects-map.conf` in place you also need to include it in your `nginx.dockerfile` in order to get
-the configuration file into your build.
+After you put the `redirects-map.conf` in place you also need to include it in your `nginx.dockerfile` in order to get the configuration file into your build.
 
 ```
 COPY redirects-map.conf /etc/nginx/redirects-map.conf
 ```
 
 ### Basic Authentication
-If you want to protect your site via Basic Authentication you can do this by defining the environment variables `BASIC_AUTH_USERNAME` and `BASIC_AUTH_PASSWORD` within your .lagoon.env.environment files.
+If you want to protect your site via Basic Authentication you can do this by defining the environment variables `BASIC_AUTH_USERNAME` and `BASIC_AUTH_PASSWORD` within your `.lagoon.env.environment` files.
 
 
 ## Environment Variables
-Environment variables are meant to do common behavior changes of php.
+Environment variables are meant to do common behavior changes of nginx container.
 
 | Environment Variable              | Default   | Description                                    |
 | --------------------------------- | --------- | ---------------------------------------------- |

docs/using_lagoon/docker_images/php-cli-drupal.md

@@ -0,0 +1,9 @@
+# php-cli-drupal Image
+
+Based on Lagoon `php-cli` image, `cli-drupal` image has all tools for daily maintenance, plus `drush`.
+
+## Lagoon & OpenShift adaptions
+
+This image is prepared to be used on Lagoon which leverages OpenShift. There are therefore some things already done:
+
+- Folder permissions are automatically adapted with [`fix-permissions`](https://github.com/sclorg/s2i-base-container/blob/master/core/root/usr/bin/fix-permissions) so this image will work with a random user and therefore also on OpenShift.

docs/using_lagoon/docker_images/php-cli.md

@@ -0,0 +1,33 @@
+# php-cli Image
+
+Lagoon `php-cli` Docker image, based on Lagoon `php-fpm` image, with all needed tools for daily operations.  
+Containers (or PODS) started from `cli` images are responsible for building code for `composer` or `node` based projects.  
+The image also owns database CLIs for both **MariaDB** and **PostgreSQL**.  
+
+This Dockerfile is intended to be used as an base for any cli needs within Lagoon.
+
+## Lagoon & OpenShift adaptions
+
+This image is prepared to be used on Lagoon which leverages OpenShift. There are therefore some things already done:
+
+- Folder permissions are automatically adapted with [`fix-permissions`](https://github.com/sclorg/s2i-base-container/blob/master/core/root/usr/bin/fix-permissions) so this image will work with a random user and therefore also on OpenShift.
+- `COMPOSER_ALLOW_SUPERUSER=1` removes warning about use of composer as root
+- `80-shell-timeout.sh` script checks if containers are running in a Kubernetes environment and then set a 10 minutes timeout to idle `cli` pods
+- cli containers use ssh key injected by Lagoon or defined into `SSH_PRIVATE_KEY` environment variable
+
+## Included cli tools
+
+The included cli tools are:
+
+- `composer` version 1.9.0 (changeable via `COMPOSER_VERSION` and `COMPOSER_HASH_SHA256`)
+- `nodejs` verison v12 (as at October 2019)
+- `npm`
+- `yarn`
+- `mariadb-client`
+- `postgresql-client`
+
+
+### Change NodeJS Version
+
+By default this Image ships with the current Nodejs Version (v12 at time of writing this).  
+If you need another Version you can remove the current version and install the one of your choice.

docs/using_lagoon/docker_images/php-fpm.md

@@ -1,12 +1,14 @@
 # php-fpm Image
 
-amazee.io Alpine 7 Dockerfile with php-fpm installed, based on the official PHP Alpine images at (https://hub.docker.com/_/php/)
+Lagoon `php-fpm` Docker image, based on the official PHP Alpine images at (https://hub.docker.com/_/php/).  
+The supported versions of PHP on Lagoon are 7.1, 7.2 and 7.3.  Older versions (5.6, 7.0) may also be available for compatibility.  
 
-This Dockerfile is intended to be used as an base for any php needs within amazee.io. This image itself does not create a webserver, rather just an php-fpm fastcgi listener. You maybe need to adapt the php-fpm pool config.
+This Dockerfile is intended to be used as an base for any php needs within Lagoon.  
+This image itself does not create a webserver, rather just an php-fpm fastcgi listener. You maybe need to adapt the php-fpm pool config.
 
-## amazee.io & OpenShift adaptions
+## Lagoon & OpenShift adaptions
 
-This image is prepared to be used on amazee.io which leverages OpenShift. There are therefore some things already done:
+This image is prepared to be used on Lagoon which leverages OpenShift. There are therefore some things already done:
 
 - Folder permissions are automatically adapted with [`fix-permissions`](https://github.com/sclorg/s2i-base-container/blob/master/core/root/usr/bin/fix-permissions) so this image will work with a random user and therefore also on OpenShift.
 - The `/usr/local/etc/php/php.ini` and `/usr/local/etc/php-fpm.conf` plus all files within `/usr/local/etc/php-fpm.d/` are parsed through [envplate](https://github.com/kreuzwerker/envplate) with an container-entrypoint.
@@ -15,7 +17,8 @@ This image is prepared to be used on amazee.io which leverages OpenShift. There
 
 ## Included php config
 
-The included php config contains sane values that will make the creation of php pools configs easier. Here a list these, check `/usr/local/etc/php.ini`, `/usr/local/etc/php-fpm.conf` for all of it:
+The included php config contains sane values that will make the creation of php pools configs easier.  
+Here a list these, check `/usr/local/etc/php.ini`, `/usr/local/etc/php-fpm.conf` for all of it:
 
 - `max_execution_time = 900` (changeable via `PHP_MAX_EXECUTION_TIME`)
 - `realpath_cache_size = 256k` for handling big php projects
@@ -27,7 +30,7 @@ The included php config contains sane values that will make the creation of php
 - `apc.shm_size = 32m` and `apc.enabled = 1` (changeable via `PHP_APC_SHM_SIZE` and `PHP_APC_ENABLED`)
 - php-fpm error logging happens in stderr
 
-Hint: If you don't like any of these configs, you have three possibilities:
+Hint: If you don't like any of these configs, you have three possibilities:  
 1. If they are changeable via environment variables, use them (preferred version, see list of environment variables below)
 2. Create your own fpm-pool config and set configs them via `php_admin_value` and `php_admin_flag` in there (learn more about them [here](http://php.net/manual/en/configuration.changes.php) - yes this refers to Apache, but it is also the case for php-fpm). _Important:_
     1. If you like to provide your own php-fpm pool, overwrite the file `/usr/local/etc/php-fpm.d/www.conf` with your own config or remove this file if you like another name. If you don't do that the provided pool will be started!
@@ -36,7 +39,9 @@ Hint: If you don't like any of these configs, you have three possibilities:
 
 ## default fpm-pool
 
-This image is shipped with an fpm-pool config ([`php-fpm.d/www.conf`](https://github.com/amazeeio/lagoon/blob/master/images/php/fpm/php-fpm.d/www.conf)) that creates a fpm-pool and listens on port 9000. This is because we try to provide an image which covers already most needs for PHP and so you don't need to create your own. You are happy to do so if you like though :) Here a short description of what this file does:
+This image is shipped with an fpm-pool config ([`php-fpm.d/www.conf`](https://github.com/amazeeio/lagoon/blob/master/images/php/fpm/php-fpm.d/www.conf)) that creates a fpm-pool and listens on port 9000.  
+This is because we try to provide an image which covers already most needs for PHP and so you don't need to create your own. You are happy to do so if you like though :)  
+Here a short description of what this file does:
 
 - listens on port 9000 via ipv4 and ipv6
 - uses the pm `dynamic` and creates between 2-50 children