From a72077605f2fa1a1c8b8cfe3d1a9f4a2be6f2b8b Mon Sep 17 00:00:00 2001 From: cytopia Date: Tue, 6 Jun 2017 14:02:08 +0200 Subject: [PATCH 01/12] DVL-016 clean-up after gh-pages branch --- .gitignore | 6 ---- .tests/.lib.sh | 6 ++-- .travis.yml | 6 ++-- docs/CNAME | 1 - docs/_config.yml | 2 -- docs/_layouts/default.html | 62 -------------------------------------- docs/assets/css/style.scss | 46 ---------------------------- 7 files changed, 6 insertions(+), 123 deletions(-) delete mode 100644 docs/CNAME delete mode 100644 docs/_config.yml delete mode 100644 docs/_layouts/default.html delete mode 100644 docs/assets/css/style.scss diff --git a/.gitignore b/.gitignore index a10fc659..4441f5c4 100644 --- a/.gitignore +++ b/.gitignore @@ -39,12 +39,6 @@ /cfg/php-fpm-7.1/*.ini /cfg/hhvm-latest/*.ini -# gh-pages -docs/Gemfile -docs/Gemfile.lock -docs/_site/ -docs/view-page.sh - ###################################### # GENERIC diff --git a/.tests/.lib.sh b/.tests/.lib.sh index 833f9022..95103d1d 100644 --- a/.tests/.lib.sh +++ b/.tests/.lib.sh @@ -340,8 +340,8 @@ devilbox_start() { done printf "\n" - # Wait another 30 sec for databases to come up - wait_for 30 1 + # Wait another 60 sec for databases to come up + wait_for 60 1 echo } @@ -436,7 +436,7 @@ devilbox_test_url() { _pattern="${2}" _number="${3}" - _count="$( curl -q "${_url}" 2>/dev/null | grep -c "${_pattern}" || true )" + _count="$( curl -q --retry 100 --retry-max-time 0 "${_url}" 2>/dev/null | grep -c "${_pattern}" || true )" if [ "${_count}" != "${_number}" ]; then echo "[ERR]: Found ${_count}/${_number} of '${_pattern}'" diff --git a/.travis.yml b/.travis.yml index b79dee7b..81870b61 100644 --- a/.travis.yml +++ b/.travis.yml @@ -172,10 +172,10 @@ matrix: ### before_install: # Get newer docker version - - max=20; i=0; while [ $i -lt $max ]; do if sudo apt-get update; then break; else i=$((i+1)); fi done - - max=20; i=0; while [ $i -lt $max ]; do if sudo apt-get -y -o Dpkg::Options::="--force-confnew" install docker-engine; then break; else i=$((i+1)); fi done + - max=100; i=0; while [ $i -lt $max ]; do if sudo apt-get update; then break; else i=$((i+1)); fi done + - max=100; i=0; while [ $i -lt $max ]; do if sudo apt-get -y -o Dpkg::Options::="--force-confnew" install docker-engine; then break; else i=$((i+1)); fi done # Get newer docker-compose version - - curl -L https://github.com/docker/compose/releases/download/1.13.0/docker-compose-`uname -s`-`uname -m` > docker-compose + - curl -L --retry 100 --retry-max-time 0 https://github.com/docker/compose/releases/download/1.13.0/docker-compose-`uname -s`-`uname -m` > docker-compose - chmod +x docker-compose - sudo mv -f docker-compose /usr/local/bin diff --git a/docs/CNAME b/docs/CNAME deleted file mode 100644 index e3fbf84d..00000000 --- a/docs/CNAME +++ /dev/null @@ -1 +0,0 @@ -devilbox.org \ No newline at end of file diff --git a/docs/_config.yml b/docs/_config.yml deleted file mode 100644 index 7f1f4688..00000000 --- a/docs/_config.yml +++ /dev/null @@ -1,2 +0,0 @@ -theme: jekyll-theme-slate -google_analytics: UA-51797082-4 diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html deleted file mode 100644 index 1793825c..00000000 --- a/docs/_layouts/default.html +++ /dev/null @@ -1,62 +0,0 @@ - - - - - - - - - - - - {{ site.title | default: site.github.repository_name }} - - - - - -
-
- View on GitHub - -

{{ site.title | default: site.github.repository_name }}

-

{{ site.description | default: site.github.project_tagline }}

- - {% if site.show_downloads %} -
- Download this project as a .zip file - Download this project as a tar.gz file -
- {% endif %} -
-
- - -
-
- {{ content }} -
-
- - - - - {% if site.google_analytics %} - - {% endif %} - - diff --git a/docs/assets/css/style.scss b/docs/assets/css/style.scss deleted file mode 100644 index 93baa1b9..00000000 --- a/docs/assets/css/style.scss +++ /dev/null @@ -1,46 +0,0 @@ ---- ---- - -@import "{{ site.theme }}"; - -.inner { - max-width: 850px; - position: relative; - padding: 20px 10px; - margin: 0 auto; -} -#header_wrap { - background-image: url('/assets/img/devilbox-dash.png'); - background-repeat: no-repeat; - background-size: cover; - min-height: 100%; -} -h1, h2, h3 { - text-align: center; -} -h2, h3 { - margin-top:30px; -} - - -table { - margin: auto; - width: 50%; - padding: 10px; -} - -.center { - text-align: center; -} -img.battery { - /*border: 1px solid black;*/ - border-radius: 15px; -} - -/* remove gh pages link */ -footer.inner p { - display: none; -} -footer.inner p.copyright { - display: block; -} From 1ac6a134bd5abe71fee86a3d629d01ed8bd2c018 Mon Sep 17 00:00:00 2001 From: cytopia Date: Thu, 8 Jun 2017 09:25:03 +0200 Subject: [PATCH 02/12] DVL-016 Documentation Intro page --- docs/Configuration.md | 114 --------------- docs/Emails.md | 23 --- docs/Examples.md | 28 ++++ docs/FAQ.md | 22 ++- docs/Info.md | 73 ---------- docs/Intranet.md | 18 --- docs/Logs.md | 58 -------- docs/PHP_Projects.md | 120 ---------------- docs/README.md | 319 +++++++----------------------------------- docs/Updating.md | 68 --------- docs/Usage.md | 63 +++++++-- 11 files changed, 144 insertions(+), 762 deletions(-) delete mode 100644 docs/Configuration.md delete mode 100644 docs/Emails.md create mode 100644 docs/Examples.md delete mode 100644 docs/Info.md delete mode 100644 docs/Intranet.md delete mode 100644 docs/Logs.md delete mode 100644 docs/PHP_Projects.md delete mode 100644 docs/Updating.md diff --git a/docs/Configuration.md b/docs/Configuration.md deleted file mode 100644 index d976893b..00000000 --- a/docs/Configuration.md +++ /dev/null @@ -1,114 +0,0 @@ -# Devilbox Documentation - -[Home](https://github.com/cytopia/devilbox) | -[Overview](README.md) | -Configuration | -[Usage](Usage.md) | -[Updating](Updating.md) | -[Info](Info.md) | -[PHP Projects](PHP_Projects.md) | -[Emails](Emails.md) | -[Logs](Logs.md) | -[Intranet](Intranet.md) | -[FAQ](FAQ.md) - ----- - -## Configuration - - -### 1. The `.env` file - -All docker-compose configuration is done inside the `.env` file which simply defines key-value variables parsed to `docker-compose.yml`. - -First thing to do after cloning this repository is creating this file from the `env-example`. - -```shell -$ cp env-example .env -``` - -The file itself is well commented and should explain itself. In case anything is unclear leave an issue at GitHub. - -> [What is the `.env` file?](https://docs.docker.com/compose/env-file/) - - -There are a few sections you should be aware off to better understand how it all works. - -#### 1.1 Selecting service versions - -Each service has a `_SERVER` variable with a corresponding version. All existing versions are present in the file and commented out. - -It is important to leave at least one version uncomment, otherwise the start-up will lead to errors. Use the following variable to control which version will be loaded: - -* **`PHP_SERVER`** -* **`HTTPD_SERVER`** -* **`MYSQL_SERVER`** -* **`PGSQL_SERVER`** -* **`REDIS_SERVER`** -* **`MEMCD_SERVER`** - -#### 1.2 Data directories - -There are a few pre-configured data directories to make storage persistent across container restarts: - -* *`HOST_PATH_HTTPD_DATADIR`* -* *`HOST_PATH_MYSQL_DATADIR`* -* *`HOST_PATH_PGSQL_DATADIR`* - -The values by default point to relative directories inside the devilbox repository. You can however also point them to different locations (relative or absolute) - -MySQL and PgSQL data directories will also append their version as a subfolder to the data directories in order to prevent database file corruptions due to different versions and possible incompatabilities between them. - -If you have a MySQL database on your host computer with the same version that your docker container is using, you can also interchangeably use the data dir with you host MySQL version and vice-versa. - -### 2. The `cfg/` directory - -Inside the devilbox root directory you will find a foder called `cfg/`. This will contain subdirectories in the form of `-`. -Those folders will be mounted into the appropriate location into the respective docker container in order to overwrite service configuration. - -Currently only MySQL/MariaDB and PHP/HHVM overrides are supported. - -The folder structure looks like this: -``` -cfg/ - hhvm-latest/ - mariadb-10.0/ - mariadb-10.1/ - mariadb-10.2/ - mariadb-10.3/ - mariadb-5.5/ - mysql-5.5/ - mysql-5.6/ - mysql-5.7/ - mysql-8.0/ - php-fpm-5.4/ - php-fpm-5.5/ - php-fpm-5.6/ - php-fpm-7.0/ - php-fpm-7.1/ -``` - -Each of the folders will contain an example file in the following format: -``` -devilbox-custom.-example -``` - -Only files which have the correct file extensions will be read, all others such as `*.-example` will be ignored. - -#### 2.1 Adding PHP options - - - - ---- - -### Hints - -**A. Can I not just comment out the service in the `.env` file?** - -No, don't do this. This will lead to unexpected behaviour (different versions will be loaded). -The `.env` file allows you to configure the devilbox, but not to start services selectively. At least one version per service must be defined. - -**B. I don't want to start all container. How would I do this?** - -Head over to the **[Usage](Usage.md)** section to get an in-depth explanation about how to start services selectively. diff --git a/docs/Emails.md b/docs/Emails.md deleted file mode 100644 index 017e50e3..00000000 --- a/docs/Emails.md +++ /dev/null @@ -1,23 +0,0 @@ -# Devilbox Documentation - -[Home](https://github.com/cytopia/devilbox) | -[Overview](README.md) | -[Configuration](Configuration.md) | -[Usage](Usage.md) | -[Updating](Updating.md) | -[Info](Info.md) | -[PHP Projects](PHP_Projects.md) | -Emails | -[Logs](Logs.md) | -[Intranet](Intranet.md) | -[FAQ](FAQ.md) - ----- - -## Emails - -You can send emails from within your PHP projects without having to worry to accidentally sending them out. - -All emails to whatever recipients are kept inside by a catch-all functionality from within the `php` container (using postfix). - -In order to view the sent emails, use the bundled devilbox intranet and go to the Emails menu. For more information about this see the **[Intranet](Intranet.md)** section. diff --git a/docs/Examples.md b/docs/Examples.md new file mode 100644 index 00000000..deb4baac --- /dev/null +++ b/docs/Examples.md @@ -0,0 +1,28 @@ +# Devilbox Documentation + +| +**Overview** | +**Installing** | +**Updating** | +**Configuration** | +[**Usage**](Usage.md) | +Examples | +**Technical** | +[**FAQ**](FAQ.md) | + +--- + +## Examples + +1. Setup Wordpress +2. Setup Drupal +3. Setup Yii + +--- + +### 1. Setup Wordpress + +### 2. Setup Drupal + +### 3. Setup Yii + diff --git a/docs/FAQ.md b/docs/FAQ.md index 256a2c42..8cf61544 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,18 +1,16 @@ # Devilbox Documentation -[Home](https://github.com/cytopia/devilbox) | -[Overview](README.md) | -[Configuration](Configuration.md) | -[Usage](Usage.md) | -[Updating](Updating.md) | -[Info](Info.md) | -[PHP Projects](PHP_Projects.md) | -[Emails](Emails.md) | -[Logs](Logs.md) | -[Intranet](Intranet.md) | -FAQ +| +**Overview** | +**Installing** | +**Updating** | +**Configuration** | +[**Usage**](Usage.md) | +[**Examples**](Examples.md) | +**Technical** | +FAQ | ----- +--- ## FAQ diff --git a/docs/Info.md b/docs/Info.md deleted file mode 100644 index e589d6a4..00000000 --- a/docs/Info.md +++ /dev/null @@ -1,73 +0,0 @@ -# Devilbox Documentation - -[Home](https://github.com/cytopia/devilbox) | -[Overview](README.md) | -[Configuration](Configuration.md) | -[Usage](Usage.md) | -[Updating](Updating.md) | -Info | -[PHP Projects](PHP_Projects.md) | -[Emails](Emails.md) | -[Logs](Logs.md) | -[Intranet](Intranet.md) | -[FAQ](FAQ.md) - ----- - -## Info - - -### Available containers - -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 even use `127.0.0.1` or `localhost` (See background section below). - -> 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 | - -### Background - -#### Background - 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` - - -#### Background - 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` - -Also the database sockets from the container are mounted into the host. - -#### Background - Benefit of the above - -With the PHP container and the docker host (your computer) behaving the same it is possible to write your php applications like this: -```php --` which will then hold all available log files. - -**Example:** - -``` -devilbox/ - log/ - apache-2.2/ - access_log - error_log - localhost-access.log - localhost-error.log - other-error.log - mariadb-10.3/ - error.log - query.log - slow.log - php-fpm-7.0/ - php-fpm.err - www-access.log - www-error.log -``` - -### Docker logs - -All output that is produced to stdout or stderr by the started service will be available in `docker logs`. In order to view them constantly in a terminal session use: - -```shell -docker-compose logs -f -``` - -Docker logs are currently only being used to display the initial startup including the chosen settings. All other logging is written to file and mounted to the docker host. diff --git a/docs/PHP_Projects.md b/docs/PHP_Projects.md deleted file mode 100644 index 937dbd82..00000000 --- a/docs/PHP_Projects.md +++ /dev/null @@ -1,120 +0,0 @@ -# Devilbox Documentation - -[Home](https://github.com/cytopia/devilbox) | -[Overview](README.md) | -[Configuration](Configuration.md) | -[Usage](Usage.md) | -[Updating](Updating.md) | -[Info](Info.md) | -PHP Projects | -[Emails](Emails.md) | -[Logs](Logs.md) | -[Intranet](Intranet.md) | -[FAQ](FAQ.md) - ----- - -## PHP Projects - - -### TL;DR - -1. Create folder `${HOST_PATH_HTTPD_DATADIR}/my-project/htdocs` -2. Set `${TLD_SUFFIX}` in the `.env` file (example: `loc`) -2. Expand docker host `/etc/hosts` with `127.0.0.1 my-project.loc` or attach included DNS server to your host and stop worrying about DNS -3. Browse `http://my-project.loc` - - -### Adding projects - -As an example, we are going to add two projects. - -**Prerequisites (dir)** - -For this case let's assume your www root folder points to `~/www`. This means your projects will reside on your host computer in your home directory under www. - -In order to achive this set `HOST_PATH_HTTPD_DATADIR=~/www` in the `.env` file (If this file does not yet exist, copy `env-example` to `.env`). - -`.env`: -``` -... -HOST_PATH_HTTPD_DATADIR=~/www -... -``` - -**Prerequisites (domain suffix)** - -Let's also assume that you have chosen `*.loc` as you projects `TLD_SUFFIX` Domain - -In order to achive this set `TLD_SUFFIX=loc` in the `.env` file (If this file does not yet exist, copy `env-example` to `.env`). - -`.env`: -``` -... -TLD_SUFFIX=loc -... -``` - -**Desired Projects** - -| Project name | Document Root | URL | -|--------------|---------------|-----| -| devilbox | ~/www/devilbox/htdocs | http://devilbox.loc | -| foo.bar | ~/www/foo.bar/htdocs | http://foo.bar.loc | - -`htdocs` can either be a folder or a symlink to a folder. - -**Project: devilbox** - -Setup projects folder and an `index.php` (on your host computer) - -```shell -$ mkdir -p ~/www/devilbox/htdocs -$ vim ~/devilbox/htdocs/index.php -``` - -```php - -``` - -Adjust your local (host computer) `/etc/hosts` and point `devilbox.loc` to your localhost address `127.0.0.1` - -```shell -$ sudo vim /etc/hosts -``` -```shell -127.0.0.1 devilbox.loc -``` - - -**Project: foo.bar** - -Setup projects folder and use existing github project to serve. - -```shell -$ mkdir -p ~/www/foo.bar -$ cd ~/www/foo.bar - -# Use an existing github project as your document root -$ git clone https://github.com// - -# Symlink the project to htdocs -$ ln -s htdocs - -$ ls -l -drwxr-xr-x 4 cytopia 1286676289 136 Oct 30 14:24 / -lrwxr-xr-x 1 cytopia 1286676289 549 Nov 6 15:13 htdocs -> / -``` - - -Adjust your local (host computer) `/etc/hosts` and point `foo.bar.loc` to your localhost address `127.0.0.1` - -```shell -$ sudo vim /etc/hosts -``` -```shell -127.0.0.1 foo.bar.loc -``` - diff --git a/docs/README.md b/docs/README.md index 4ec95cbd..a86cb537 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,292 +1,81 @@ -# Devilbox +# Devilbox Documentation -| **Overview** | **Installing** | **Updating** | **Configuration** | **Usage** | **Technical** | **FAQ** | +| +Overview | +**Installing** | +**Updating** | +**Configuration** | +[**Usage**](Usage.md) | +[**Examples**](Examples.md) | +**Technical** | +[**FAQ**](FAQ.md) | --- +## Overview -### Dockerized LAMP/MEAN stack +1. [Supported Host OS](#1-supported-host-os) +2. [Requirements](#2-requirements) +3. [Docker documentation](#3-docker-documentation) +4. [Devilbox documentation](#4-devilbox-documentation) +5. [Video Tutorials](#5-video-tutorials) -

The devilbox is a modern and highly customisable LAMP and MEAN stack replacement based purely on docker and docker-compose running on all major platforms. It supports an unlimited number of projects for which vhosts and DNS records are created automatically. Email catch-all and popular development tools will be at your service as well.

+--- -Devilbox +### 1. Supported Host OS +The devilbox runs on all major operating systems. Below you can quickly check the recommended docker versions and current issues per OS. -### Supported Host OS +| | ![linux][lin-logo] | ![windows][win-logo] | ![osx][osx-logo] | +|-------------|----------------------|---------------------------|----------------------| +| **Version** | normal | [Docker for Windows][d4w] | [Docker dor Mac][d4m]| +| **Issues** | [here][lin-issues] | [here][win-issues] | [here][osx-issues] | -

Don't worry about switching computers. The devilbox will run on all major operating systems.

+**Note:** There is also the deprecated [Docker Toolbox][dtb] (for Windows and OSX). It is however not recommended to use with the devilbox. -
- Linux support - OSX support - Windows support -
+[win-logo]: https://raw.githubusercontent.com/cytopia/icons/master/64x64/windows.png +[lin-logo]: https://raw.githubusercontent.com/cytopia/icons/master/64x64/linux.png +[osx-logo]: https://raw.githubusercontent.com/cytopia/icons/master/64x64/osx.png +[d4w]: https://docs.docker.com/docker-for-windows/install/ +[d4m]: https://docs.docker.com/docker-for-mac/install/ +[dtb]: https://docs.docker.com/toolbox/overview/ +[win-issues]: https://github.com/cytopia/devilbox/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3A%22host%3Awindows%22 +[lin-issues]: https://github.com/cytopia/devilbox/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3A%22host%3Alinux%22 +[osx-issues]: https://github.com/cytopia/devilbox/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3A%22host%3Aosx%22 -### Install, Configure and Start +### 2. Requirements -

Your whole development stack is up and running in a few simple steps.

+* [Docker Engine 1.12.0+](https://docs.docker.com/compose/compose-file/compose-versioning/#version-21) +* [Docker Compose 1.6.0+](https://docs.docker.com/compose/compose-file/compose-versioning/#version-2) +* On Windows use [Docker for Windows][d4w] (not tested on [Docker Toolbox][dtb]) +* On OSX use [Docker for Mac][d4m] (not tested on [Docker Toolbox][dtb]) -```shell -# Get the soures -$ git clone https://github.com/cytopia/devilbox -$ cd devilbox -# Create and customize the config file -$ cp env-example .env -$ vim .env +### 3. Docker documentation -# Start your daemons -$ docker-compose up -``` +If you have never worked with docker/docker-compose before, you should check up on their documentation to get you started: [docker docs](https://docs.docker.com/). -### Run exactly what you need +### 4. Devilbox documentation -

Choose your required daemons and select a version. Any combination is possible.
This will allow you, to always exactly simulate your production environment locally during development.

+| Topic | Description | +|-------------------------|-------------| +| **Installing** | How to install docker, docker-compose and the devilbox | +| **Updating** | Update best practise | +| **Configuration** | How to configure the devilbox, switch versions (PHP, MySQL, PgSQL, ...) and how to set custom options (php.ini, my.cnf, httpd.conf, ...) | +| **[Usage](Usage.md)** | How to create projects, Email and DNS usage, tools (`composer`, `npm`, `node`, `drush`, ...), entering the container, Log files, Xdebug, ...| +| **[Examples](Examples.md)** | Some project examples for popular CMS/Frameworks. How to setup Wordpress, Drupal, Yii, ... | +| **Technical** | Technical background information | +| **[FAQ](FAQ.md)** | Questions and Troubleshooting | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ApacheNginxPHPMySQLMariaDBPgSQLRedisMemcachedMongoDB
2.2stable5.45.55.59.12.81.4.212.8
2.4mainline5.55.610.09.23.01.4.223.0
5.65.710.19.33.21.4.233.2
7.08.010.29.4...3.4
7.110.39.51.4.363.5
HHVM9.6latest
+### 5. Video Tutorials -### Run only what you need +Have a look at youtube to see all the features in action. -

You are not forced to load the whole stack everytime. Only bring up what you really need.
It is also possible to add or remove daemons while the stack is already running.

+[![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) -```shell -# Load traditional lamp stack only -$ docker-compose up httpd php mysql - -# Add redis to the running stack -$ docker-compose up redis - -# Stop MySQL from the current stack -$ docker-compose stop mysql -``` - - -### Introduction Videos - -

Head over to youtube for a quick introduction and see for yourself how easily new projects can be created.

- -
- - -
- - -### PHP Modules - -
-

The devilbox is a development stack, so it is made sure that a lot of PHP modules are available out of the box in order to work with many different frameworks. There will however be slight differences between the versions and especially with HHVM. To see the exact bundled modules for each version visit the corresponding docker repositories on Github:

- - PHP - HHVM - -

- PHP 5.4 | - PHP 5.5 | - PHP 5.6 | - PHP 7.0 | - PHP 7.1 | - HHVM -

-

apc, apcu, bcmath, bz2, calendar, Core, ctype, curl, date, dom, ereg, exif, fileinfo, filter, ftp, gd, gettext, gmp, hash, iconv, igbinary, imagick, imap, intl, json, ldap, libxml, magickwand, mbstring, mcrypt, memcache, memcached, mhash, mongodb, msgpack, mysql, mysqli, mysqlnd, openssl, pcntl, pcre, PDO, pdo_mysql, pdo_pgsql, pdo_sqlite, pgsql, phalcon, Phar, posix, pspell, readline, recode, redis, Reflection, session, shmop, SimpleXML, soap, sockets, SPL, sqlite3, standard, sysvmsg, sysvsem, sysvshm, tidy, tokenizer, uploadprogress, wddx, xdebug, xml, xmlreader, xmlrpc, xmlwriter, xsl, Zend OPcache, zip, zlib

-
- - -### Email catch-all - -
- Email catch-all -

The built-in postfix mailserver is configured to automatically intercept all outgoing emails. This is an important measurement during development to make sure not to accidentally send out real emails. Instead you will be able to see all sent emails in the included intranet mail view. See Intranet section below.

-
- - -### Auto-DNS - -
- Auto-DNS -

Creating a new project just requires you to create a new folder on the filesystem. As you probalby don't want to bother with editing your /etc/hosts file everytime, the built-in DNS server will automatically provide the correct DNS records for every project.

-
- - -### Batteries included - -

No need to download external tools. Everything is bundled, up-to-date and available inside the containers.

- -
- Devilbox - Devilbox - Devilbox -
- Devilbox - Devilbox - Devilbox - Devilbox - Devilbox - Devilbox - Devilbox -
- - -### Supported Frameworks and CMS - -

There is nothing special about the devilbox, so any framework or CMS that will work with normal LAMP/MEAN stacks will work here as well. However in order to make double sure, a few popular applications have been explicitly tested.

- -
- CakePHP - Drupal - PhalconPHP - Wordpress - Yii -
- - -### Devilbox Intranet - -

Once the devilbox is up and running, you can visit the bundled intranet on http://localhost.
The intranet is not just a simple dash, it provides many useful tools:

- -
- Container Health | DNS Status | Available vHosts | Emails | Databases | Effective Configuration
- - -
- - -### Security - -

Be aware that the docker service is running with root privileges on your system (like any other webserver for example). The devilbox is using a mix of official docker images and custom images. All integrated containers are available on Github and can be reviewed at any time.

- - -### Up-to-dateness - -

Docker containers are pushed to Docker Hub frequently.
It should be enough for you to pull updated images on a regeular basis.

- -```shell -$ docker-compose pull -``` - -

However, if a new minor version (PHP for example) has just been released and you want to use it right away, you can simply *git clone* the docker repository and rebuild the container. Each container repository contains a shell script for easy building.

- -```shell -# Download PHP 7.1 repository -$ git clone https://github.com/cytopia/docker-php-fpm-7.1 - -# Rebuild the container in order to get the latest minor/patch version -$ cd docker-php-fpm-7.1 -$ ./build/docker-rebuild.sh -``` - - -### Integration Tests - -
- -
- -

In order to make sure everything always runs stable and as expected, the devilbox makes heavy use of integration tests. You can head over to Travis-CI and have a look at stable and nightly builds.

- - -### Contribute - -
-

Contributers are welcome in any way.

- -

First of all, if you like the project, please do star it. Starring is an important measurement to see the number of active users and better allows me to organize my time and effort I can put into this project.

- -

You can also get actively involved. Do clone the project and start improving whatever you think is useful. There is quite a lot todo and planned. If you like to contribute, view CONTRIBUTING.md and ROADMAP.

- -

Major contributors will be credited within the intranet and on the github page.

-
- - -### License - -
-

MIT License

-

Copyright (c) 2016 cytopia

-
diff --git a/docs/Updating.md b/docs/Updating.md deleted file mode 100644 index aeb59d97..00000000 --- a/docs/Updating.md +++ /dev/null @@ -1,68 +0,0 @@ -# Devilbox Documentation - -[Home](https://github.com/cytopia/devilbox) | -[Overview](README.md) | -[Configuration](Configuration.md) | -[Usage](Usage.md) | -Updating | -[Info](Info.md) | -[PHP Projects](PHP_Projects.md) | -[Emails](Emails.md) | -[Logs](Logs.md) | -[Intranet](Intranet.md) | -[FAQ](FAQ.md) - ----- - -## Updating - -### Tags vs Branches - -The devilbox git repository offers two types of setups. - -1. Git `tags` for stable release -2. The `master` branch with the latest features - - -### Git tags - -Each new devilbox release is tagged in git and bound to tagged docker images. -Updating only involves to check out the latest tag and make sure to stop and remmove your containers prior starting them up again. Latest docker images will be pulled automatically as their docker tag number will also change between releases. - -Additionally you will also have compare `env-example` against your current `.env` file and in case of differences apply them. - -```shell -# Update source -$ git fetch --all -$ git checkout - -# Stop and remove your container -$ docker-compose stop -$ docker-compose rm - -# Check for config file changes -$ vimdiff .env env-example -``` - -Currently releases are not that frequent, so you might be better of with the `master` branch. - -### Git master branch - -The `master` branch does not use tagged docker images, but `latest`. So once you git pull you should also pull the latest docker images. - - -```shell -# Update source -$ git fetch --all -$ git pull origin master - -# Stop and remove your container -$ docker-compose stop -$ docker-compose rm - -# Pull latest docker images -$ docker-compose pull - -# Check for config file changes -$ vimdiff .env env-example -``` diff --git a/docs/Usage.md b/docs/Usage.md index f6a58c68..30799069 100644 --- a/docs/Usage.md +++ b/docs/Usage.md @@ -1,21 +1,62 @@ # Devilbox Documentation -[Home](https://github.com/cytopia/devilbox) | -[Overview](README.md) | -[Configuration](Configuration.md) | +| +**Overview** | +**Installing** | +**Updating** | +**Configuration** | Usage | -[Updating](Updating.md) | -[Info](Info.md) | -[PHP Projects](PHP_Projects.md) | -[Emails](Emails.md) | -[Logs](Logs.md) | -[Intranet](Intranet.md) | -[FAQ](FAQ.md) +[**Examples**](Examples.md) | +**Technical** | +[**FAQ**](FAQ.md) | ----- +--- ## Usage +1. [Start and Stop](#1-start-and-stop) + 1. [Normal Start](#1-1-normal-start) + 2. [Background Start](#) + 3. [Selective Start](#) + 4. [Normal Stop](#) + 5. [Selective Stop](#) + 6. [Attach/Detach during run-time](#) +2. [Work inside the PHP container](#) + 1. [As devilbox user](#) + 2. [As root user](#) + 3. [Available tools](#) + 4. [Available URLs](#) +3. [Creating Projects](#) + 1. Creating projects on the docker host + 2. Creating projects from within the PHP container +4. [DNS](#) + 1. [/etc/hosts](#) + 2. [Auto-DNS](#) +5. [Intranet](#) +6. [Emails](#) +7. [Log files](#) + +--- + +### 1. Start and Stop + +Starting and stopping containers is done via docker-compose. If you have never worked with it before, have a look at their documentation for an [overview](https://docs.docker.com/compose/reference/overview/), [up](https://docs.docker.com/compose/reference/up/) and [stop](https://docs.docker.com/compose/reference/stop/) + +#### 1.1 Normal Start + +The normal start will bring up all container defined in *docker-compose.yml* and will stay in forground making it possible to stop them via Ctrl+c. + +```shell +$ docker-compose up +``` + +#### 1.2 Background Start +#### 1.3 Selective Start +#### 1.4 Normal Stop +#### 1.5 Selective stop +#### 1.6 Attach/Detach during run-time +### 2. Creating Projects + This section is about how to start, stop, view and enter (all or a selection of some) containers. If you want to know how to choose the container type version (e.g. which mysql version or which php version) refer to the **[Configuration](Configuration.md)** section. **Convention:** The terms *container* and *service* are used interchangeably. From 5fb80b0cf10b17ec4a38017717ae5823f6f72f59 Mon Sep 17 00:00:00 2001 From: cytopia Date: Thu, 8 Jun 2017 09:28:53 +0200 Subject: [PATCH 03/12] DVL-016 Documentation FAQ --- docs/FAQ.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/FAQ.md b/docs/FAQ.md index 8cf61544..7c4805ba 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,7 +1,7 @@ # Devilbox Documentation | -**Overview** | +[**Overview**](README.md) | **Installing** | **Updating** | **Configuration** | From 2c57098fce525de6a6c7b3237092e6301ac3f6c8 Mon Sep 17 00:00:00 2001 From: cytopia Date: Fri, 9 Jun 2017 09:23:26 +0200 Subject: [PATCH 04/12] DVL-016 Documentation structure --- docs/Examples.md | 16 ++++++++-------- docs/FAQ.md | 19 ++++++++++++++----- docs/Hacking.md | 23 +++++++++++++++++++++++ docs/README.md | 19 +++++++++---------- docs/Usage.md | 41 ++++++++++++++--------------------------- 5 files changed, 68 insertions(+), 50 deletions(-) create mode 100644 docs/Hacking.md diff --git a/docs/Examples.md b/docs/Examples.md index deb4baac..7a861902 100644 --- a/docs/Examples.md +++ b/docs/Examples.md @@ -1,22 +1,22 @@ # Devilbox Documentation -| -**Overview** | +**[Overview](README.md)** | **Installing** | **Updating** | **Configuration** | -[**Usage**](Usage.md) | -Examples | +**[Usage](Usage.md)** | +**Examples** | **Technical** | -[**FAQ**](FAQ.md) | +**[Hacking](Hacking.md)** | +**[FAQ](FAQ.md)** --- ## Examples -1. Setup Wordpress -2. Setup Drupal -3. Setup Yii +1. [Setup Wordpress](#1-setup-wordpress) +2. [Setup Drupal](#2-setup-drupal) +3. [Setup Yii](#3-setup-yii) --- diff --git a/docs/FAQ.md b/docs/FAQ.md index 7c4805ba..46b71bf9 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,14 +1,14 @@ # Devilbox Documentation -| -[**Overview**](README.md) | +**[Overview](README.md)** | **Installing** | **Updating** | **Configuration** | -[**Usage**](Usage.md) | -[**Examples**](Examples.md) | +**[Usage](Usage.md)** | +**[Examples](Examples.md)** | **Technical** | -FAQ | +**[Hacking](Hacking.md)** | +**FAQ** --- @@ -33,3 +33,12 @@ See: *Why are mounted MySQL data directories separated by version?* **Why do the user/group permissions of log/ or cfg/ directories show 1000?** Uid and Gid are set to 1000 by default. You can alter them to match the uid/gid of your current user. Open the `.env` file and change the sections `NEW_UID` and `NEW_GID`. When you start up the devilbox, the php-container will use these values for its user. + +**Can I not just comment out the service in the `.env` file?** + +No, don't do this. This will lead to unexpected behaviour (different versions will be loaded). +The `.env` file allows you to configure the devilbox, but not to start services selectively. + +**Are there any required services that must/will always be started?** + +Yes. `http` and `php` will automatically always be started (due to dependencies inside `docker-compose.yml`) if you specify them or not. diff --git a/docs/Hacking.md b/docs/Hacking.md new file mode 100644 index 00000000..94542440 --- /dev/null +++ b/docs/Hacking.md @@ -0,0 +1,23 @@ +# Devilbox Documentation + +**[Overview](README.md)** | +**Installing** | +**Updating** | +**Configuration** | +**[Usage](Usage.md)** | +**[Examples](Examples.md)** | +**Technical** | +**Hacking** | +**[FAQ](FAQ.md)** + +--- + +## Hacking + +1. [Adding your own docker container](#) + +--- + +### 1. Adding your own docker container + + diff --git a/docs/README.md b/docs/README.md index a86cb537..d98830a2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,14 +1,14 @@ # Devilbox Documentation -| -Overview | +**Overview** | **Installing** | **Updating** | **Configuration** | -[**Usage**](Usage.md) | -[**Examples**](Examples.md) | +**[Usage](Usage.md)** | +**[Examples](Examples.md)** | **Technical** | -[**FAQ**](FAQ.md) | +**[Hacking](Hacking.md)** | +**[FAQ](FAQ.md)** --- @@ -28,10 +28,8 @@ The devilbox runs on all major operating systems. Below you can quickly check th | | ![linux][lin-logo] | ![windows][win-logo] | ![osx][osx-logo] | |-------------|----------------------|---------------------------|----------------------| -| **Version** | normal | [Docker for Windows][d4w] | [Docker dor Mac][d4m]| -| **Issues** | [here][lin-issues] | [here][win-issues] | [here][osx-issues] | - -**Note:** There is also the deprecated [Docker Toolbox][dtb] (for Windows and OSX). It is however not recommended to use with the devilbox. +| **Docker Version** | normal | [Docker for Windows][d4w] | [Docker dor Mac][d4m]| +| **Current Issues** | [here][lin-issues] | [here][win-issues] | [here][osx-issues] | [win-logo]: https://raw.githubusercontent.com/cytopia/icons/master/64x64/windows.png [lin-logo]: https://raw.githubusercontent.com/cytopia/icons/master/64x64/linux.png @@ -46,6 +44,7 @@ The devilbox runs on all major operating systems. Below you can quickly check th ### 2. Requirements +* **Internet connection** - only required during initial setup for cloning the devilbox repository and pulling the required docker container. Afterwards you can always work offline. * [Docker Engine 1.12.0+](https://docs.docker.com/compose/compose-file/compose-versioning/#version-21) * [Docker Compose 1.6.0+](https://docs.docker.com/compose/compose-file/compose-versioning/#version-2) * On Windows use [Docker for Windows][d4w] (not tested on [Docker Toolbox][dtb]) @@ -64,7 +63,7 @@ If you have never worked with docker/docker-compose before, you should check up | **Installing** | How to install docker, docker-compose and the devilbox | | **Updating** | Update best practise | | **Configuration** | How to configure the devilbox, switch versions (PHP, MySQL, PgSQL, ...) and how to set custom options (php.ini, my.cnf, httpd.conf, ...) | -| **[Usage](Usage.md)** | How to create projects, Email and DNS usage, tools (`composer`, `npm`, `node`, `drush`, ...), entering the container, Log files, Xdebug, ...| +| **[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 | | **[FAQ](FAQ.md)** | Questions and Troubleshooting | diff --git a/docs/Usage.md b/docs/Usage.md index 30799069..72471618 100644 --- a/docs/Usage.md +++ b/docs/Usage.md @@ -1,14 +1,14 @@ # Devilbox Documentation -| -**Overview** | +**[Overview](README.md)** | **Installing** | **Updating** | **Configuration** | -Usage | -[**Examples**](Examples.md) | +**Usage** | +**[Examples](Examples.md)** | **Technical** | -[**FAQ**](FAQ.md) | +**[Hacking](Hacking.md)** | +**[FAQ](FAQ.md)** --- @@ -27,14 +27,17 @@ Usage | 3. [Available tools](#) 4. [Available URLs](#) 3. [Creating Projects](#) - 1. Creating projects on the docker host - 2. Creating projects from within the PHP container -4. [DNS](#) + 1. [Creating projects on the docker host](#) + 2. [Creating projects from inside the PHP container](#) +4. [Backups](#) + 1. [Backup MySQL database](#) + 2. [Backup PgSQL database](#) +5. [DNS](#) 1. [/etc/hosts](#) 2. [Auto-DNS](#) -5. [Intranet](#) -6. [Emails](#) -7. [Log files](#) +6. [Intranet](#) +7. [Emails](#) +8. [Log files](#) --- @@ -154,19 +157,3 @@ The `php` container mounts your project files (the path of `HOST_PATH_TO_WWW_DOC So enter the container as described above and once inside the `php` container cd into `/shared/httpd`. ----- - -### Hints - -**A. How do I know the name of the container I can start?** - -Refer to the **[Info](Info.md)** section or look it up in the `docker-compose.yml` file. - -**B. Can I not just comment out the service in the `.env` file?** - -No, don't do this. This will lead to unexpected behaviour (different versions will be loaded). -The `.env` file allows you to configure the devilbox, but not to start services selectively. - -**C. Are there any required services that must/will always be started?** - -Yes. `http` and `php` will automatically always be started (due to dependencies inside `docker-compose.yml`) if you specify them or not. From 04d7a4aaefc3456c92ac09885749370a56af8edf Mon Sep 17 00:00:00 2001 From: cytopia Date: Sat, 10 Jun 2017 11:41:46 +0200 Subject: [PATCH 05/12] DVL-016 Technical documentation --- docs/Examples.md | 2 +- docs/FAQ.md | 2 +- docs/Hacking.md | 38 ++++++++++++++++- docs/README.md | 6 +-- docs/Technical.md | 103 ++++++++++++++++++++++++++++++++++++++++++++++ docs/Usage.md | 2 +- 6 files changed, 144 insertions(+), 9 deletions(-) create mode 100644 docs/Technical.md 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 + Date: Sat, 10 Jun 2017 12:35:55 +0200 Subject: [PATCH 06/12] DVL-016 Hacking the devilbox --- docs/Hacking.md | 112 +++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 105 insertions(+), 7 deletions(-) diff --git a/docs/Hacking.md b/docs/Hacking.md index 062ac2d4..7121df10 100644 --- a/docs/Hacking.md +++ b/docs/Hacking.md @@ -14,28 +14,93 @@ ## Hacking -1. [Adding your own docker container](#1-adding-your-own-docker-container) +1. [Rebuilding bundled Docker container](#1-rebuilding-bundled-docker-container) + 1. [Why rebuild yourself?](#1-1-why-rebuild-yourself-) + 2. [How to rebuild yourself?](#1-2-how-to-rebuild-yourself-) + 3. [How to use the rebuild container?](#1-3-how-to-use-the-rebuild-container-) +2. [Customizing the bundled Docker container](#2-customizing-the-bundled-docker-container) +3. [Adding your own Docker container](#3-adding-your-own-docker-container) + 1. [What information will you need?](#3-1-what-information-will-you-need-) + 2. [How to add your service?](#3-2-how-to-add-your-service-) + 3. [How to start your service?](#3-3-how-to-start-your-service-) --- -### 1. Adding your own docker container +### 1. Rebuilding bundled Docker container + +The devilbox Docker container are rebuild frequently and pushed to [dockerhub](https://hub.docker.com/r/cytopia/). 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](https://github.com/cytopia/docker-php-fpm-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`: + +```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`: + +```yml + 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`. -#### 1.1 What information will you need? +#### 3.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` +2. The Docker image name +3. The Docker image version or `latest` 4. An unused IP address from the devilbox network -#### 1.2 How to add your service? +#### 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) ```yml +... +services: + # Your custom Docker container here: : image: : networks: @@ -46,9 +111,42 @@ You can add your custom docker container including its configuration to `docker- - bind - php - httpd + # End of custom Docker container +... ``` -#### 1.3 How to start your service? +##### 3.2.2 Specific example + +Lets make a real example for adding [Cockroach DB](https://hub.docker.com/r/cockroachdb/cockroach/) + +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: + +```yml +... +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? ```shell # The following will bring up your service including all the From 3dba84461dab9027ddc14d2c0e871642a39e021a Mon Sep 17 00:00:00 2001 From: cytopia Date: Sat, 10 Jun 2017 13:33:28 +0200 Subject: [PATCH 07/12] DVL-016 Overview --- docs/README.md | 63 +++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 52 insertions(+), 11 deletions(-) diff --git a/docs/README.md b/docs/README.md index 34012935..1dfa9ce3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,15 +14,45 @@ ## Overview -1. [Supported Host OS](#1-supported-host-os) -2. [Requirements](#2-requirements) -3. [Docker documentation](#3-docker-documentation) -4. [Devilbox documentation](#4-devilbox-documentation) -5. [Video Tutorials](#5-video-tutorials) +1. [Main idea](#1-main-idea) +2. [Supported Host OS](#2-supported-host-os) +3. [Requirements](#3-requirements) +4. [Docker documentation](#4-docker-documentation) +5. [Devilbox documentation](#5-devilbox-documentation) +6. [Video Tutorials](#6-video-tutorials) +7. [Supported Frameworks and CMS](#7-supported-frameworks-and-cms) --- -### 1. Supported Host OS +### 1. Main idea + +The devilbox allows you to have an unlimitted number of projects ready without having to install any external software and without having to configure any virtual hosts. + +The only thing you will have to do is to create a new folder on the filesystem and your virtual host is ready to be served with your custom domain. + +The default project catch-all domain is `*.dev` (can be changed). Let's see an example: + +```shell +# Inside your main project folder +$ ls -l +drwxr-xr-x 3 cytopia 4096 Jun 10 13:10 my-drupal +drwxr-xr-x 3 cytopia 4096 Jun 10 13:10 my-wordpress +drwxr-xr-x 3 cytopia 4096 Jun 10 13:10 project1 +drwxr-xr-x 3 cytopia 4096 Jun 10 13:10 project2 +drwxr-xr-x 3 cytopia 4096 Jun 10 13:10 yii-test +``` + +By having the above folders, the devilbox will automatically be able to serve the following vhosts: + +* http://my-drupal.dev +* http://my-wordpress.dev +* http://project1.dev +* http://project2.dev +* http://yii-test.dev + +New folders can be created, deleted and removed during run-time and corresponding virtual hosts will be available instantly without having to restart anything. + +### 2. Supported Host OS The devilbox runs on all major operating systems. Below you can quickly check the recommended docker versions and current issues per OS. @@ -42,7 +72,7 @@ The devilbox runs on all major operating systems. Below you can quickly check th [osx-issues]: https://github.com/cytopia/devilbox/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3A%22host%3Aosx%22 -### 2. Requirements +### 3. Requirements * **Internet connection** - only required during initial setup for cloning the devilbox repository and pulling the required docker container. Afterwards you can always work offline. * [Docker Engine 1.12.0+](https://docs.docker.com/compose/compose-file/compose-versioning/#version-21) @@ -51,12 +81,12 @@ The devilbox runs on all major operating systems. Below you can quickly check th * On OSX use [Docker for Mac][d4m] (not tested on [Docker Toolbox][dtb]) -### 3. Docker documentation +### 4. Docker documentation If you have never worked with docker/docker-compose before, you should check up on their documentation to get you started: [docker docs](https://docs.docker.com/). -### 4. Devilbox documentation +### 5. Devilbox documentation | Topic | Description | |-------------------------|-------------| @@ -70,9 +100,20 @@ If you have never worked with docker/docker-compose before, you should check up | **[FAQ](FAQ.md)** | Questions and Troubleshooting | -### 5. Video Tutorials +### 6. Video Tutorials -Have a look at youtube to see all the features in action. +Have a look at youtube to see some 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) + + +### 7. Supported Frameworks and CMS + +As far as tested there are no limitations and you can use any Framework or CMS just as you would on your live environment. Below are a few examples of extensively tested Frameworks and CMS: + +![CakePHP](img/logos/cake.png) +![Drupal](img/logos/drupal.png) +![Phalcon](img/logos/phalcon.png) +![Wordpress](img/logos/wordpress.png) +![Yii](img/logos/yii.png) From c909e5df4234a609ae17c545ad8d917c4cf37e3c Mon Sep 17 00:00:00 2001 From: cytopia Date: Sat, 10 Jun 2017 15:07:26 +0200 Subject: [PATCH 08/12] DVL-016 Run the devilbox --- docs/Examples.md | 1 + docs/FAQ.md | 11 ++++ docs/Hacking.md | 1 + docs/README.md | 2 + docs/Run.md | 133 +++++++++++++++++++++++++++++++++++++++++++++ docs/Technical.md | 1 + docs/Usage.md | 136 ++++++++++++++++++++++++---------------------- 7 files changed, 221 insertions(+), 64 deletions(-) create mode 100644 docs/Run.md diff --git a/docs/Examples.md b/docs/Examples.md index 52581cff..b681ad74 100644 --- a/docs/Examples.md +++ b/docs/Examples.md @@ -4,6 +4,7 @@ **Installing** | **Updating** | **Configuration** | +**[Run](Run.md)** | **[Usage](Usage.md)** | **Examples** | **[Technical](Technical.md)** | diff --git a/docs/FAQ.md b/docs/FAQ.md index e2a34409..cac92c3e 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -4,6 +4,7 @@ **Installing** | **Updating** | **Configuration** | +**[Run](Run.md)** | **[Usage](Usage.md)** | **[Examples](Examples.md)** | **[Technical](Technical.md)** | @@ -42,3 +43,13 @@ The `.env` file allows you to configure the devilbox, but not to start services **Are there any required services that must/will always be started?** Yes. `http` and `php` will automatically always be started (due to dependencies inside `docker-compose.yml`) if you specify them or not. + +**What PHP Modules are available?** + +**Can I add other PHP Modules?** + +**Can I change php.ini?** + +**Can I change my.cnf?** + +**Can I switch HHVM between PHP 5.6 and PHP 7 mode?** diff --git a/docs/Hacking.md b/docs/Hacking.md index 7121df10..b52bdc97 100644 --- a/docs/Hacking.md +++ b/docs/Hacking.md @@ -4,6 +4,7 @@ **Installing** | **Updating** | **Configuration** | +**[Run](Run.md)** | **[Usage](Usage.md)** | **[Examples](Examples.md)** | **[Technical](Technical.md)** | diff --git a/docs/README.md b/docs/README.md index 1dfa9ce3..02c3f621 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,6 +4,7 @@ **Installing** | **Updating** | **Configuration** | +**[Run](Run.md)** | **[Usage](Usage.md)** | **[Examples](Examples.md)** | **[Technical](Technical.md)** | @@ -93,6 +94,7 @@ If you have never worked with docker/docker-compose before, you should check up | **Installing** | How to install docker, docker-compose and the devilbox | | **Updating** | Update best practise | | **Configuration** | How to configure the devilbox, switch versions (PHP, MySQL, PgSQL, ...) and how to set custom options (php.ini, my.cnf, httpd.conf, ...) | +| **[Run](Run.md)** | How to operate the devilbox, start and stop all or only required Docker container. | | **[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 | diff --git a/docs/Run.md b/docs/Run.md new file mode 100644 index 00000000..41982f9f --- /dev/null +++ b/docs/Run.md @@ -0,0 +1,133 @@ +# Devilbox Documentation + +**[Overview](README.md)** | +**Installing** | +**Updating** | +**Configuration** | +**Run** | +**[Usage](Usage.md)** | +**[Examples](Examples.md)** | +**[Technical](Technical.md)** | +**[Hacking](Hacking.md)** | +**[FAQ](FAQ.md)** + +--- + +## Run + +1. [Start the devilbox](#1-start-the-devilbox) + 1. [Foreground Start](#1-1-foreground-start) + 2. [Background Start](#1-2-background-start) + 3. [Selective Start](#1-3-selective-start) +2. [Stop the devilbox](#2-stop-the-devilbox) + 1. [Foreground Stop](#2-1-foreground-stop) + 2. [Background Stop](#2-2-background-stop) +3. [Attach/Detach during run-time](#3-attach-detach-during-run-time) + 1. [Attach during run-time](#3-1-attach-during-run-time) + 2. [Detach during run-time](#3-2-detach-during-run-time) + + +--- + +### 1. Start the devilbox + +Starting and stopping containers is done via docker-compose. If you have never worked with it before, have a look at their documentation for an [overview](https://docs.docker.com/compose/reference/overview/), [up](https://docs.docker.com/compose/reference/up/) and [stop](https://docs.docker.com/compose/reference/stop/) commands. + +#### 1.1 Foreground Start + +The normal start will bring up **all** container defined in *docker-compose.yml* and will stay in forground making it possible to stop them via Ctrl+c. + +```shell +$ docker-compose up +``` + +#### 1.2 Background Start + +Instead of having the docker-compose run stay in foreground, you can also send it to the background by adding `-d` as an argument. The following will bring up **all** container and send docker-compose to background. + +```shell +$ docker-compose up -d +``` + +#### 1.3 Selective Start + +There is no need to always bring up **all** container, if you just need a few at the moment. In order to do so, simply specify the container by name that you actually need. + +##### 1.3.1 Starting httpd, php, bind and mysql + +```shell +# Foreground +$ docker-compose up httpd php bind mysql + +# Background +$ docker-compose up -d httpd php bind mysql +``` + +**Note:** `httpd`, `php` and `bind` are base container that will **always** be started if specified or not. (Defined by `depends_on` in `docker-compose.yml`). So the above could also be achieved by simply specifying `mysql` only. + +```shell +# Foreground +$ docker-compose up mysql + +# Background +$ docker-compose up -d mysql +``` + +##### 1.3.2 Starting httpd, php, bind, pgsql and redis + +```shell +# Foreground +$ docker-compose up httpd php bind pgsql redis + +# Background +$ docker-compose up -d httpd php bind pgsql redis +``` + +**Note:** `httpd`, `php` and `bind` are base container that will **always** be started if specified or not. (Defined by `depends_on` in `docker-compose.yml`). So the above could also be achieved by simply specifying `pgsql` and `redis` only. + +```shell +# Foreground +$ docker-compose up pgsql redis + +# Background +$ docker-compose up -d pgsql redis +``` + +### 2. Stop the devilbox + +#### 2.1 Foreground stop + +If you started up docker compose in foreground mode (without `-d`), you can hit `ctrl+c` to gracefull stop or **twice** `ctrl+c` to kill the running containers. + +**Note:** Automatically started containers that were not specified (such as `http` or `php`) will have to be stopped manually via `docker-compose down` afterwards. + +#### 2.2 Background stop + +If you started up docker compose in background mode (with `-d`), go back to the devilbox directory (where the `docker-compose.yml` file resides and type `docker-compose down` to gracefully stop or `docker-compose kill` to kill them immediately. + +Best pracice would be to start the container in the background (with `-d`) and use `docker compose down` to gracefully stop all of them. + +### 3. Attach/Detach during run-time + +#### 3.1 Attach during run-time + +You can also add/attach containers during runtime if you need them. You might have started httpd, php, bind and mysql and decided that you will also require redis. So go ahead and add redis to the running container stack. + +```shell +# Foreground +$ docker-compose up redis + +# Background +$ docker-compose up -d redis +``` + +It is recommended to always use background starts, this way you can intially start your desired stack and re-use the current terminal window to start or stop other services. + + +#### 3.2 Detach during run-time + +You can also stop specific containers during runtime if they are not needed anymore. You might have started httpd, php, bind, mysql and redis and decided that redis was not needed. So go ahead and remove redis from the running container stack. + +```shell +$ docker-compose stop redis +``` diff --git a/docs/Technical.md b/docs/Technical.md index 52c502a7..84bb3f5b 100644 --- a/docs/Technical.md +++ b/docs/Technical.md @@ -4,6 +4,7 @@ **Installing** | **Updating** | **Configuration** | +**[Run](Run.md)** | **[Usage](Usage.md)** | **[Examples](Examples.md)** | **Technical** | diff --git a/docs/Usage.md b/docs/Usage.md index 43ee4675..4b980975 100644 --- a/docs/Usage.md +++ b/docs/Usage.md @@ -4,6 +4,7 @@ **Installing** | **Updating** | **Configuration** | +**[Run](Run.md)** | **Usage** | **[Examples](Examples.md)** | **[Technical](Technical.md)** | @@ -43,21 +44,87 @@ ### 1. Start and Stop -Starting and stopping containers is done via docker-compose. If you have never worked with it before, have a look at their documentation for an [overview](https://docs.docker.com/compose/reference/overview/), [up](https://docs.docker.com/compose/reference/up/) and [stop](https://docs.docker.com/compose/reference/stop/) +Starting and stopping containers is done via docker-compose. If you have never worked with it before, have a look at their documentation for an [overview](https://docs.docker.com/compose/reference/overview/), [up](https://docs.docker.com/compose/reference/up/) and [stop](https://docs.docker.com/compose/reference/stop/) commands. #### 1.1 Normal Start -The normal start will bring up all container defined in *docker-compose.yml* and will stay in forground making it possible to stop them via Ctrl+c. +The normal start will bring up **all** container defined in *docker-compose.yml* and will stay in forground making it possible to stop them via Ctrl+c. ```shell $ docker-compose up ``` #### 1.2 Background Start + +Instead of having the docker-compose run stay in foreground, you can also send it to the background by adding `-d` as an argument. The following will bring up **all** container and send docker-compose to background. + +```shell +$ docker-compose up -d +``` + #### 1.3 Selective Start + +There is no need to always bring up **all** container, if you just need a few at the moment. In order to do so, simply specify the container by name that you actually need. + +##### 1.3.1 Starting httpd, php, bind and mysql + +```shell +# Foreground +$ docker-compose up httpd php bind mysql + +# Background +$ docker-compose up -d httpd php bind mysql +``` + +**Note:** `httpd`, `php` and `bind` are base container that will **always** be started if specified or not. (Defined by `depends_on` in `docker-compose.yml`). So the above could also be achieved by simply specifying `mysql` only. + +```shell +# Foreground +$ docker-compose up mysql + +# Background +$ docker-compose up -d mysql +``` + +##### 1.3.2 Starting httpd, php, bind, pgsql and redis + +```shell +# Foreground +$ docker-compose up httpd php bind pgsql redis + +# Background +$ docker-compose up -d httpd php bind pgsql redis +``` + +**Note:** `httpd`, `php` and `bind` are base container that will **always** be started if specified or not. (Defined by `depends_on` in `docker-compose.yml`). So the above could also be achieved by simply specifying `pgsql` and `redis` only. + +```shell +# Foreground +$ docker-compose up pgsql redis + +# Background +$ docker-compose up -d pgsql redis +``` + #### 1.4 Normal Stop -#### 1.5 Selective stop -#### 1.6 Attach/Detach during run-time + +1. If you started up docker compose in foreground mode (without `-d`), you can hit `ctrl+c` to gracefull stop or **twice** `ctrl+c` to kill the running containers.
**Note:** Automatically started containers that were not specified (such as `http` or `php`) will have to be stopped manually via `docker-compose down` afterwards. +2. If you started up docker compose in background mode (with `-d`), go back to the devilbox directory (where the `docker-compose.yml` file resides and type `docker-compose down` to gracefully stop or `docker-compose kill` to kill them immediately. + +Best pracice would be to start the container in the background (with `-d`) and use `docker compose down` to gracefully stop all of them. + +#### 1.5 Selective stop + +You can also stop specific containers during runtime if they are not needed anymore. You might have started httpd, php, bind, mysql and redis and decided that redis was not needed. So go ahead and remove redis from the running container stack. + +```shell +$ docker-compose stop redis +``` + +#### 1.6 Attach/Detach during run-time + + + ### 2. Creating Projects This section is about how to start, stop, view and enter (all or a selection of some) containers. If you want to know how to choose the container type version (e.g. which mysql version or which php version) refer to the **[Configuration](Configuration.md)** section. @@ -66,66 +133,7 @@ This section is about how to start, stop, view and enter (all or a selection of **Assumption:** All `docker-compose` commands must be executed within the devilbox root directory, where the `docker-compose.yml` file resides. -### 1. Start and Stop - -#### 1.1 Start all container - -```shell -$ docker-compose up -``` - -This will bring up **all containers** defined in `docker-compose.yml`. - -However, you will probably not need all of the defined services and especially on slow machines you only want to start what you really need. This is possible as well. - -#### 1.2 Start selected container - -In order to only start the services you actually need, you must specify them with the docker-compose command. - -**Note:** The `http` and `php` container will automatically be started and must not be explicitly specified. (If not specified, their log output will also not go to stderr/stdout, but instead to docker logs) - -```shell -# Only start HTTP and PHP -$ docker-compose up http php - -# Start HTTP, PHP and Redis -$ docker-compose up redis - -# Start HTTP, PHP and MySQL -$ docker-compose up mysql - -# Start HTTP, PHP, PostgreSQL and Memcache -$ docker-compose up pgsql memcache -``` -I think you get the idea. - -#### 1.3 Start in background - -You can also run the docker compose command in the background and close your terminal after startup. To do so simply add the `-d` flag: - -```shell -$ docker-compose up -d -``` -Or in case of selectively starting -```shell -$ docker-compose up -d mysql -``` - -#### 1.4 Stop container - -1. If you started up docker compose in foreground mode (without `-d`), you can hit `ctrl+c` to gracefull stop or **twice** `ctrl+c` to kill the running containers.
**Note:** Automatically started containers that were not specified (such as `http` or `php`) will have to be stopped manually via `docker-compose down` afterwards. -2. If you started up docker compose in background mode (with `-d`), go back to the devilbox directory (where the `docker-compose.yml` file resides and type `docker-compose down` to gracefully stop or `docker-compose kill` to kill them immediately. - -Best pracice would be to start the container in the background (with `-d`) and use `docker compose down` to gracefully stop all of them. - -### 2. Container Info - -#### 2.1 List running container - -Inside the devilbox directory enter the following command to get a list of the started/running container: -```shell -$ docker-compose ps -``` +`` #### 2.2 Show container stdout/stderr output From 4b8889bef971f842b0475c7a5506386d80c37bec Mon Sep 17 00:00:00 2001 From: cytopia Date: Sat, 10 Jun 2017 15:19:06 +0200 Subject: [PATCH 09/12] DVL-016 Info about docker logs --- docs/Run.md | 41 +++++++++++++++++++- docs/Usage.md | 104 ++++---------------------------------------------- 2 files changed, 46 insertions(+), 99 deletions(-) diff --git a/docs/Run.md b/docs/Run.md index 41982f9f..f8142230 100644 --- a/docs/Run.md +++ b/docs/Run.md @@ -25,6 +25,10 @@ 3. [Attach/Detach during run-time](#3-attach-detach-during-run-time) 1. [Attach during run-time](#3-1-attach-during-run-time) 2. [Detach during run-time](#3-2-detach-during-run-time) +4. [Docker logs](#4-docker-logs) + 1. [All logs](#4-1-all-logs) + 1. [Specific logs](#4-2-specific-logs) + 1. [Tail logs](#4-3-tail-logs) --- @@ -63,7 +67,7 @@ $ docker-compose up httpd php bind mysql $ docker-compose up -d httpd php bind mysql ``` -**Note:** `httpd`, `php` and `bind` are base container that will **always** be started if specified or not. (Defined by `depends_on` in `docker-compose.yml`). So the above could also be achieved by simply specifying `mysql` only. +**Start Note:** `httpd`, `php` and `bind` are base container that will **always** be started if specified or not. (Defined by `depends_on` in `docker-compose.yml`). So the above could also be achieved by simply specifying `mysql` only. ```shell # Foreground @@ -73,6 +77,8 @@ $ docker-compose up mysql $ docker-compose up -d mysql ``` +**Log Note:** When you do not specify httpd, php and bind in foreground start, their docker-logs will not be shown and you will have to explicitly use `docker-compose logs` to view their stdout/stderr output. Refer to the Log section below. + ##### 1.3.2 Starting httpd, php, bind, pgsql and redis ```shell @@ -83,7 +89,7 @@ $ docker-compose up httpd php bind pgsql redis $ docker-compose up -d httpd php bind pgsql redis ``` -**Note:** `httpd`, `php` and `bind` are base container that will **always** be started if specified or not. (Defined by `depends_on` in `docker-compose.yml`). So the above could also be achieved by simply specifying `pgsql` and `redis` only. +**Start Note:** `httpd`, `php` and `bind` are base container that will **always** be started if specified or not. (Defined by `depends_on` in `docker-compose.yml`). So the above could also be achieved by simply specifying `pgsql` and `redis` only. ```shell # Foreground @@ -92,6 +98,8 @@ $ docker-compose up pgsql redis # Background $ docker-compose up -d pgsql redis ``` +**Log Note:** When you do not specify httpd, php and bind in foreground start, their docker-logs will not be shown and you will have to explicitly use `docker-compose logs` to view their stdout/stderr output. Refer to the Log section below. + ### 2. Stop the devilbox @@ -131,3 +139,32 @@ You can also stop specific containers during runtime if they are not needed anym ```shell $ docker-compose stop redis ``` + +### 4. Docker Logs + +Services started in background mode (`-d`) or those that were started as dependencies (`http` and `php`) will always only log to docker logs and not to stdout/stderr. + +#### 4.1 All logs + +In order to view logs of all started containers type: + +```shell +$ docker-compose logs +``` + +#### 4.2 Specific logs + +In order to view logs of a specific container, name it explicitly: + +```shell +$ docker-compose logs redis +``` + +#### 4.3 Tail logs + +There is also a version similar to `tail -f` to keep logs updated all the time. + +```shell +$ docker-compose logs -f +``` + diff --git a/docs/Usage.md b/docs/Usage.md index 4b980975..1615a334 100644 --- a/docs/Usage.md +++ b/docs/Usage.md @@ -15,116 +15,26 @@ ## Usage -1. [Start and Stop](#1-start-and-stop) - 1. [Normal Start](#1-1-normal-start) - 2. [Background Start](#) - 3. [Selective Start](#) - 4. [Normal Stop](#) - 5. [Selective Stop](#) - 6. [Attach/Detach during run-time](#) -2. [Work inside the PHP container](#) +1. [Work inside the PHP container](#) 1. [As devilbox user](#) 2. [As root user](#) 3. [Available tools](#) 4. [Available URLs](#) -3. [Creating Projects](#) +2. [Creating Projects](#) 1. [Creating projects on the docker host](#) 2. [Creating projects from inside the PHP container](#) -4. [Backups](#) +3. [Backups](#) 1. [Backup MySQL database](#) 2. [Backup PgSQL database](#) -5. [DNS](#) +4. [DNS](#) 1. [/etc/hosts](#) 2. [Auto-DNS](#) -6. [Intranet](#) -7. [Emails](#) -8. [Log files](#) +5. [Intranet](#) +6. [Emails](#) +7. [Log files](#) --- -### 1. Start and Stop - -Starting and stopping containers is done via docker-compose. If you have never worked with it before, have a look at their documentation for an [overview](https://docs.docker.com/compose/reference/overview/), [up](https://docs.docker.com/compose/reference/up/) and [stop](https://docs.docker.com/compose/reference/stop/) commands. - -#### 1.1 Normal Start - -The normal start will bring up **all** container defined in *docker-compose.yml* and will stay in forground making it possible to stop them via Ctrl+c. - -```shell -$ docker-compose up -``` - -#### 1.2 Background Start - -Instead of having the docker-compose run stay in foreground, you can also send it to the background by adding `-d` as an argument. The following will bring up **all** container and send docker-compose to background. - -```shell -$ docker-compose up -d -``` - -#### 1.3 Selective Start - -There is no need to always bring up **all** container, if you just need a few at the moment. In order to do so, simply specify the container by name that you actually need. - -##### 1.3.1 Starting httpd, php, bind and mysql - -```shell -# Foreground -$ docker-compose up httpd php bind mysql - -# Background -$ docker-compose up -d httpd php bind mysql -``` - -**Note:** `httpd`, `php` and `bind` are base container that will **always** be started if specified or not. (Defined by `depends_on` in `docker-compose.yml`). So the above could also be achieved by simply specifying `mysql` only. - -```shell -# Foreground -$ docker-compose up mysql - -# Background -$ docker-compose up -d mysql -``` - -##### 1.3.2 Starting httpd, php, bind, pgsql and redis - -```shell -# Foreground -$ docker-compose up httpd php bind pgsql redis - -# Background -$ docker-compose up -d httpd php bind pgsql redis -``` - -**Note:** `httpd`, `php` and `bind` are base container that will **always** be started if specified or not. (Defined by `depends_on` in `docker-compose.yml`). So the above could also be achieved by simply specifying `pgsql` and `redis` only. - -```shell -# Foreground -$ docker-compose up pgsql redis - -# Background -$ docker-compose up -d pgsql redis -``` - -#### 1.4 Normal Stop - -1. If you started up docker compose in foreground mode (without `-d`), you can hit `ctrl+c` to gracefull stop or **twice** `ctrl+c` to kill the running containers.
**Note:** Automatically started containers that were not specified (such as `http` or `php`) will have to be stopped manually via `docker-compose down` afterwards. -2. If you started up docker compose in background mode (with `-d`), go back to the devilbox directory (where the `docker-compose.yml` file resides and type `docker-compose down` to gracefully stop or `docker-compose kill` to kill them immediately. - -Best pracice would be to start the container in the background (with `-d`) and use `docker compose down` to gracefully stop all of them. - -#### 1.5 Selective stop - -You can also stop specific containers during runtime if they are not needed anymore. You might have started httpd, php, bind, mysql and redis and decided that redis was not needed. So go ahead and remove redis from the running container stack. - -```shell -$ docker-compose stop redis -``` - -#### 1.6 Attach/Detach during run-time - - - ### 2. Creating Projects This section is about how to start, stop, view and enter (all or a selection of some) containers. If you want to know how to choose the container type version (e.g. which mysql version or which php version) refer to the **[Configuration](Configuration.md)** section. From 40401dda8583d317de40d35ead1f6b56782aec03 Mon Sep 17 00:00:00 2001 From: cytopia Date: Sun, 11 Jun 2017 15:16:01 +0200 Subject: [PATCH 10/12] DVL-16 Finalized doc structure --- docs/Backups.md | 36 +++++++++++ docs/Configure.md | 23 +++++++ docs/Examples.md | 7 ++- docs/FAQ.md | 7 ++- docs/Hacking.md | 7 ++- docs/Install.md | 81 ++++++++++++++++++++++++ docs/README.md | 31 ++++++--- docs/Run.md | 17 ++++- docs/Technical.md | 7 ++- docs/Update.md | 116 ++++++++++++++++++++++++++++++++++ docs/Usage.md | 156 +++++++++++++++++++++++++++++++++------------- 11 files changed, 424 insertions(+), 64 deletions(-) create mode 100644 docs/Backups.md create mode 100644 docs/Configure.md create mode 100644 docs/Install.md create mode 100644 docs/Update.md diff --git a/docs/Backups.md b/docs/Backups.md new file mode 100644 index 00000000..75ac506c --- /dev/null +++ b/docs/Backups.md @@ -0,0 +1,36 @@ +# Devilbox Documentation + +**[Overview](README.md)** | +**[Install](Install.md)** | +**[Update](Update.md)** | +**[Configure](Configure.md)** | +**[Run](Run.md)** | +**[Usage](Usage.md)** | +**Backups** | +**[Examples](Examples.md)** | +**[Technical](Technical.md)** | +**[Hacking](Hacking.md)** | +**[FAQ](FAQ.md)** + +--- + +## Backups + +1. [MySQL](#1-mysql) + 1. [MySQL Database Backup](#1-1-mysql-database-backup) + 2. [MySQL Database Restore](#1-2-mysql-database-restore) +2. [PostgreSQL](#2-postgresql) + 1. [PostgreSQL Database Backup](#2-1-postgresql-database-backup) + 2. [PostgreSQL Database Restore](#2-1-postgresql-database-restore) + +--- + +### 1. MySQL + +#### 1.1 MySQL Database Backup +#### 1.2 MySQL Database Restore + +### 2. PostgreSQL + +#### 2.1 PostgreSQL Database Backup +#### 2.2 PostgreSQL Database Restore diff --git a/docs/Configure.md b/docs/Configure.md new file mode 100644 index 00000000..87215769 --- /dev/null +++ b/docs/Configure.md @@ -0,0 +1,23 @@ +# Devilbox Documentation + +**[Overview](README.md)** | +**[Install](Install.md)** | +**[Update](Update.md)** | +**Configure** | +**[Run](Run.md)** | +**[Usage](Usage.md)** | +**[Backups](Backups.md)** | +**[Examples](Examples.md)** | +**[Technical](Technical.md)** | +**[Hacking](Hacking.md)** | +**[FAQ](FAQ.md)** + +--- + +## Configure + +1. TODO + +--- + +### 1. TODO diff --git a/docs/Examples.md b/docs/Examples.md index b681ad74..6361cc61 100644 --- a/docs/Examples.md +++ b/docs/Examples.md @@ -1,11 +1,12 @@ # Devilbox Documentation **[Overview](README.md)** | -**Installing** | -**Updating** | -**Configuration** | +**[Install](Install.md)** | +**[Update](Update.md)** | +**[Configure](Configure.md)** | **[Run](Run.md)** | **[Usage](Usage.md)** | +**[Backups](Backups.md)** | **Examples** | **[Technical](Technical.md)** | **[Hacking](Hacking.md)** | diff --git a/docs/FAQ.md b/docs/FAQ.md index cac92c3e..c1451914 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,11 +1,12 @@ # Devilbox Documentation **[Overview](README.md)** | -**Installing** | -**Updating** | -**Configuration** | +**[Install](Install.md)** | +**[Update](Update.md)** | +**[Configure](Configure.md)** | **[Run](Run.md)** | **[Usage](Usage.md)** | +**[Backups](Backups.md)** | **[Examples](Examples.md)** | **[Technical](Technical.md)** | **[Hacking](Hacking.md)** | diff --git a/docs/Hacking.md b/docs/Hacking.md index b52bdc97..4f182b00 100644 --- a/docs/Hacking.md +++ b/docs/Hacking.md @@ -1,11 +1,12 @@ # Devilbox Documentation **[Overview](README.md)** | -**Installing** | -**Updating** | -**Configuration** | +**[Install](Install.md)** | +**[Update](Update.md)** | +**[Configure](Configure.md)** | **[Run](Run.md)** | **[Usage](Usage.md)** | +**[Backups](Backups.md)** | **[Examples](Examples.md)** | **[Technical](Technical.md)** | **Hacking** | diff --git a/docs/Install.md b/docs/Install.md new file mode 100644 index 00000000..4ee7f604 --- /dev/null +++ b/docs/Install.md @@ -0,0 +1,81 @@ +# Devilbox Documentation + +**[Overview](README.md)** | +**Install** | +**[Update](Update.md)** | +**[Configure](Configure.md)** | +**[Run](Run.md)** | +**[Usage](Usage.md)** | +**[Backups](Backups.md)** | +**[Examples](Examples.md)** | +**[Technical](Technical.md)** | +**[Hacking](Hacking.md)** | +**[FAQ](FAQ.md)** + +--- + +## Install + +1. [Install Docker](#1-install-docker) + 1. [Linux](#1-1-linux) + 2. [Windows](#1-2-windows) + 3. [OSX](#1-3-osx) +2. [Install Devilbox](#2-install-devilbox) + 1. [Latest git tag](#2-1-latest-git-tag) + 2. [Current master branch](#2-2-current-master-branch) + +--- + +### 1. Install Docker + +Only requirement for the devilbox is to have docker and docker-compose installed, everything else is bundled and provided within the Docker container. + +#### 1.1 Linux + +Refer to the official [Docker for Linux documentation](https://docs.docker.com/engine/installation/#supported-platforms) for how to install Docker on your distribution. + +#### 1.2 Windows + +Refer to the official [Docker for Windows documentation](https://docs.docker.com/docker-for-windows/install/) for how to install Docker. + +**Note:** You should install the [Native Windows Docker](https://docs.docker.com/docker-for-windows/install/) and not the [Docker Toolbox](https://docs.docker.com/toolbox/overview/). + +#### 1.3 OSX + +Refer to the official [Docker for Mac documentation](https://docs.docker.com/docker-for-mac/install/) for how to install Docker. + +**Note:** You should install the [Native Mac Docker](https://docs.docker.com/docker-for-mac/install/) and not the [Docker Toolbox](https://docs.docker.com/toolbox/overview/). + +### 2. Install Devilbox + +Just clone the devilbox repository and copy the configuration file. + +```shell +$ git clone https://github.com/cytopia/devilbox +$ cd devilbox +$ cp env-example .env +``` + +You are all set now and can continue with [configuring the devilbox](Configure.md). + + +#### 2.1 Latest git tag + +If you always want a stable development environment, you should stay on the latest git tag. However devilbox git tags are tied to specific Docker container tags. That means you will only get new Docker versions once you switch to the next devilbox git tag. + +To check out the latest git tag, issue the following command: + +```shell +$ git checkout "$(git describe --abbrev=0 --tags)" +``` + +When updating git tags, you do not need to explicitly pull new Docker images, as this will be done automatically once starting up the devilbox. The only thing you will have to do is to compare your current configuration file `.env` with possible new options in `env-example`. Refer to [Update](Update.md) For more information about how to update the devilbox properly. + +#### 2.2 Current master branch + +The devilbox master branch will always reflect the latest changes. However, no commits are pushed directly to master and everything merged into this branch has to go through various tests to make sure the master branch stays as stable as it can get. +The master branch ties each Docker container to their `latest` Docker tags. That means you can regularily `docker-compose pull` in order to obtain updated Docker container. + +**Note:** Always do `git pull origin master` and `docker-compose pull` together. Do not just do one of them. + +For the installation routine, there is nothing else to do here. After cloning you are automatically on the master branch. There are however a few things to pay attention to when updating the master branch. Refer to [Update](Update.md) For more information about how to update the devilbox properly. diff --git a/docs/README.md b/docs/README.md index 02c3f621..e9f5b4bd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,11 +1,12 @@ # Devilbox Documentation **Overview** | -**Installing** | -**Updating** | -**Configuration** | +**[Install](Install.md)** | +**[Update](Update.md)** | +**[Configure](Configure.md)** | **[Run](Run.md)** | **[Usage](Usage.md)** | +**[Backups](Backups.md)** | **[Examples](Examples.md)** | **[Technical](Technical.md)** | **[Hacking](Hacking.md)** | @@ -21,17 +22,18 @@ 4. [Docker documentation](#4-docker-documentation) 5. [Devilbox documentation](#5-devilbox-documentation) 6. [Video Tutorials](#6-video-tutorials) -7. [Supported Frameworks and CMS](#7-supported-frameworks-and-cms) +7. [Available PHP Modules](#7-available-php-modules) +8. [Supported Frameworks and CMS](#8-supported-frameworks-and-cms) --- ### 1. Main idea -The devilbox allows you to have an unlimitted number of projects ready without having to install any external software and without having to configure any virtual hosts. +The devilbox allows you to have an unlimitted number of projects ready without having to install any external software and without having to configure any virtual hosts. As well as providing a very flexible development stack that you can run offline. (Internet is only required to initially pull docker container). The only thing you will have to do is to create a new folder on the filesystem and your virtual host is ready to be served with your custom domain. -The default project catch-all domain is `*.dev` (can be changed). Let's see an example: +The default project catch-all domain is `*.dev` (see [Configure](Configure.md) for how to change it). Let's view an example: ```shell # Inside your main project folder @@ -110,7 +112,22 @@ Have a look at youtube to see some the features in action. [![Devilbox email catch-all](img/devilbox_02-email-catch-all.png "devilbox - email catch-all")](https://www.youtube.com/watch?v=e-U-C5WhxGY) -### 7. Supported Frameworks and CMS +### 7. Available PHP Modules + +The devilbox is a development stack, so it is made sure that a lot of PHP modules are available out of the box in order to work with many different frameworks. + +*apc, apcu, bcmath, bz2, calendar, Core, ctype, curl, date, dom, ereg, exif, fileinfo, filter, ftp, gd, gettext, gmp, hash, iconv, igbinary, imagick, imap, intl, json, ldap, libxml, magickwand, mbstring, mcrypt, memcache, memcached, mhash, mongodb, msgpack, mysql, mysqli, mysqlnd, openssl, pcntl, pcre, PDO, pdo_mysql, pdo_pgsql, pdo_sqlite, pgsql, phalcon, Phar, posix, pspell, readline, recode, redis, Reflection, session, shmop, SimpleXML, soap, sockets, SPL, sqlite3, standard, sysvmsg, sysvsem, sysvshm, tidy, tokenizer, uploadprogress, wddx, xdebug, xml, xmlreader, xmlrpc, xmlwriter, xsl, Zend OPcache, zip, zlib* + +There will however be slight differences between the versions and especially with HHVM. To see the exact bundled modules for each version visit the corresponding docker repositories on Github: + +[PHP 5.4](https://github.com/cytopia/docker-php-fpm-5.4) | +[PHP 5.5](https://github.com/cytopia/docker-php-fpm-5.5) | +[PHP 5.6](https://github.com/cytopia/docker-php-fpm-5.6) | +[PHP 7.0](https://github.com/cytopia/docker-php-fpm-7.0) | +[PHP 7.1](https://github.com/cytopia/docker-php-fpm-7.1) | +[HHVM](https://github.com/cytopia/docker-hhvm-latest) + +### 8. Supported Frameworks and CMS As far as tested there are no limitations and you can use any Framework or CMS just as you would on your live environment. Below are a few examples of extensively tested Frameworks and CMS: diff --git a/docs/Run.md b/docs/Run.md index f8142230..1cbd5d21 100644 --- a/docs/Run.md +++ b/docs/Run.md @@ -1,11 +1,12 @@ # Devilbox Documentation **[Overview](README.md)** | -**Installing** | -**Updating** | -**Configuration** | +**[Install](Install.md)** | +**[Update](Update.md)** | +**[Configure](Configure.md)** | **Run** | **[Usage](Usage.md)** | +**[Backups](Backups.md)** | **[Examples](Examples.md)** | **[Technical](Technical.md)** | **[Hacking](Hacking.md)** | @@ -37,6 +38,8 @@ Starting and stopping containers is done via docker-compose. If you have never worked with it before, have a look at their documentation for an [overview](https://docs.docker.com/compose/reference/overview/), [up](https://docs.docker.com/compose/reference/up/) and [stop](https://docs.docker.com/compose/reference/stop/) commands. +By starting up the devilbox all attached containers will send their stdout and stderr to docker logs (foreground or background), you can increase/decrease the containers startup verbosity by configuring the `.env` file. See [Configure](Configure.md) for how to change that behavior. + #### 1.1 Foreground Start The normal start will bring up **all** container defined in *docker-compose.yml* and will stay in forground making it possible to stop them via Ctrl+c. @@ -113,6 +116,14 @@ If you started up docker compose in foreground mode (without `-d`), you can hit If you started up docker compose in background mode (with `-d`), go back to the devilbox directory (where the `docker-compose.yml` file resides and type `docker-compose down` to gracefully stop or `docker-compose kill` to kill them immediately. +```shell +# Gracefully shutdown everything +$ docker-compose down + +# Kill everything immediately +$ docker-compose kill +``` + Best pracice would be to start the container in the background (with `-d`) and use `docker compose down` to gracefully stop all of them. ### 3. Attach/Detach during run-time diff --git a/docs/Technical.md b/docs/Technical.md index 84bb3f5b..3038f33e 100644 --- a/docs/Technical.md +++ b/docs/Technical.md @@ -1,11 +1,12 @@ # Devilbox Documentation **[Overview](README.md)** | -**Installing** | -**Updating** | -**Configuration** | +**[Install](Install.md)** | +**[Update](Update.md)** | +**[Configure](Configure.md)** | **[Run](Run.md)** | **[Usage](Usage.md)** | +**[Backups](Backups.md)** | **[Examples](Examples.md)** | **Technical** | **[Hacking](Hacking.md)** | diff --git a/docs/Update.md b/docs/Update.md new file mode 100644 index 00000000..2b1749a3 --- /dev/null +++ b/docs/Update.md @@ -0,0 +1,116 @@ +# Devilbox Documentation + +**[Overview](README.md)** | +**[Install](Install.md)** | +**Update** | +**[Configure](Configure.md)** | +**[Run](Run.md)** | +**[Usage](Usage.md)** | +**[Backups](Backups.md)** | +**[Examples](Examples.md)** | +**[Technical](Technical.md)** | +**[Hacking](Hacking.md)** | +**[FAQ](FAQ.md)** + +--- + +## Update + +1. [TL;DR](#1-tl-dr) +2. [Git tag vs master branch](#2-git-tag-vs-master-branch) + 1. [Git tag](#2-1-git-tag) + 2. [Git master branch](#2-2-git-master-branch) +3. [Compare .env file](#3-compare-env-file) +4. [Pull new Docker container (Important!)](#4-pull-new-docker-container-important-) + +--- + +### 1. TL;DR + +Shutdown, update and startup. + +```shell +$ docker-compose down +$ git pull origin master +$ vimdiff .env env-example +$ docker-compose pull +$ docker-compose up +``` + +Do not forget to read: [Pull new Docker container (Important!)](#4-pull-new-docker-container-important-) + +### 2. Git tag vs master branch + +#### 2.1 Git tag + +Git tags tie each Docker container to a stable Docker tag. This will look like this in the `docker-compose.yml` + +```shell +$ grep '^[[:space:]]*image:' docker-compose.yml + + image: cytopia/bind:0.9 + image: cytopia/${PHP_SERVER:-php-fpm-7.0}:0.9 + image: cytopia/${HTTPD_SERVER:-nginx-stable}:0.9 + image: cytopia/${MYSQL_SERVER:-mariadb-10.1}:0.9 +``` + +That means within your current git tag, you will not receive any Docker container updates, because the devilbox is bound to specific Docker tagged versions. + +When a new devilbox tag is released, the `docker-compose.yml` file will have new Docker tags. There is no manuall action required. If you start up the devilbox for the first time, it will see that the container with those tags are not available locally and automatically start downloading them. + +#### 2.2 Git master branch + +The git master branch ties each Docker container to their `latest` tag. Latest tagged Docker container always reflect the latest changes and can be compared with a master branch of a git repository. This will look like this in the `docker-compose.yml` + +```shell +$ grep '^[[:space:]]*image:' docker-compose.yml + + image: cytopia/bind:latest + image: cytopia/${PHP_SERVER:-php-fpm-7.0}:latest + image: cytopia/${HTTPD_SERVER:-nginx-stable}:latest + image: cytopia/${MYSQL_SERVER:-mariadb-10.1}:latest +``` + +When you update the devilbox repository by `git pull origin master`, the Docker tags are still `latest` and you will continue using the current version of Docker container. You must also issue `docker-compose pull` in order to also update your Docker container. + +So the update procedure is as follows: + +```shell +$ git pull origin master +$ docker-compose pull +``` + +### 3. Compare .env file + +New devilbox releases will most likeley receive new or improved functionality and features and therefore will have an altered `env-example` file. (This is an example configuration file which holds all current configuration options). +The effective configuration for docker-compose is stored in the `.env` file. However, the `.env` file is ignored by git, so that you can do changes without setting the git state dirty. + +So when you update (master branch or tag) you will always have to compare your current `.env` settings with the new `env-example` file. If you are familiar with vim, just do the following: + +```shell +$ vimdiff .env env-example +``` + +Make sure to transfer all new options from `env-example` to your current `.env` file. + +### 4. Pull new Docker container (Important!) + +As described above, for git master branch updates you will always have to pull new Docker container. **However, there is something very important to keep in mind:** + +1. You have just updated the master branch and pulled new Docker container +2. You edit the `.env` file to switch to a different PHP version +3. You start up the devilbox. Is your new PHP Docker up to date? + +No! You will have to `docker-compose pull` again. Why? + +Lets have another look into `docker-compose.yml`: + +```yml +image: cytopia/${PHP_SERVER:-php-fpm-7.0}:latest +image: cytopia/${HTTPD_SERVER:-nginx-stable}:latest +image: cytopia/${MYSQL_SERVER:-mariadb-10.1}:latest +``` + +As you can see, the Docker container names are variablized. If you updated `php-fpm-5.4:latest`, you still have to update `php-fpm-5.5:latest` (and all others) as they were not yet enabled/visible in `docker-compose.yml`. + +If there is anything unclear about this behaviour, open an **[Issue on Github](https://github.com/cytopia/devilbox/issues)**. diff --git a/docs/Usage.md b/docs/Usage.md index 1615a334..0de532e8 100644 --- a/docs/Usage.md +++ b/docs/Usage.md @@ -1,11 +1,12 @@ # Devilbox Documentation **[Overview](README.md)** | -**Installing** | -**Updating** | -**Configuration** | +**[Install](Install.md)** | +**[Update](Update.md)** | +**[Configure](Configure.md)** | **[Run](Run.md)** | **Usage** | +**[Backups](Backups.md)** | **[Examples](Examples.md)** | **[Technical](Technical.md)** | **[Hacking](Hacking.md)** | @@ -15,63 +16,134 @@ ## Usage -1. [Work inside the PHP container](#) - 1. [As devilbox user](#) - 2. [As root user](#) - 3. [Available tools](#) - 4. [Available URLs](#) -2. [Creating Projects](#) - 1. [Creating projects on the docker host](#) - 2. [Creating projects from inside the PHP container](#) -3. [Backups](#) - 1. [Backup MySQL database](#) - 2. [Backup PgSQL database](#) -4. [DNS](#) - 1. [/etc/hosts](#) - 2. [Auto-DNS](#) -5. [Intranet](#) -6. [Emails](#) -7. [Log files](#) +1. [Work on the Docker host](#1-work-on-the-docker-host) +2. [Work inside the PHP container](#2-work-inside-the-php-container) + 1. [As devilbox user](#2-1-as-devilbox-user) + 2. [As root user](#2-2-as-root-user) + 3. [Available tools](#2-3-available-tools) + 4. [Available URLs](#2-4-available-urls) +3. [Creating Projects](#3-creating-projects) + 1. [Creating projects on the docker host](#3-1-creating-projects-on-the-docker-host) + 2. [Creating projects from inside the PHP container](#3-2-creating-projects-from-inside-the-php-container) +4. [Project DNS](#4-project-dns) + 1. [/etc/hosts](#4-1-etc-hosts) + 2. [Auto-DNS](#4-2-auto-dns) +5. [Switching container versions](#5-switching-container-versions) + 1. [Httpd versions](#5-1-httpd-versions) + 2. [PHP versions](#5-2-php-versions) + 2. [SQL versions](#5-3-sql-versions) + 3. [NoSQL versions](#5-4-nosql-versions) +6. [Emails](#6-emails) +7. [Log files](#7-log-files) +8. [Intranet](#8-intranet) + 1. [Overview](#8-1-overview) + 2. [vHosts](#8-2-vhosts) + 3. [Tools](#8-3-tools) --- -### 2. Creating Projects +### 1. Work on the Docker host -This section is about how to start, stop, view and enter (all or a selection of some) containers. If you want to know how to choose the container type version (e.g. which mysql version or which php version) refer to the **[Configuration](Configuration.md)** section. +If you do not need to run any command line tools manually (composer, node, etc), it is sufficient to stay on the host. All you need is a browser and an editor/IDE. -**Convention:** The terms *container* and *service* are used interchangeably. +1. Open your browser at http://localhost +2. Open your project inside your editor +3. Start coding -**Assumption:** All `docker-compose` commands must be executed within the devilbox root directory, where the `docker-compose.yml` file resides. -`` +**Note:** If you want to do some command-line PHP tasks and you have PHP installed on your host, make sure it is the same version as your currently started PHP Docker container. If not, just enter the PHP Docker and do the tasks there. -#### 2.2 Show container stdout/stderr output +You could however also invoke the Docker's PHP executeable (or any other binary) from your host via: -Services started in background mode (`-d`) or those that were started as dependencies (`http` and `php`) will always only log to docker logs and not to stdout/stderr. In order to view their output use: ```shell -$ docker-compose logs +# Call a generic command +$ docker-compose exec --user devilbox php + | | | | | + use execute use container the + docker-compose cmd built-in name actual + on the user to command + docker devilbox exec to + container command execute + +# Print PHP version +$ docker-compose exec --user devilbox php php -v ``` -### 3. Enter +### 2. Work inside the PHP container -#### 3.1 Enter the php container +If you need to run some command line tasks manually such as `drush`, `composer` or anything similar which is not available on your host computer, you can do that inside the PHP container, which comes with lots of useful pre-install tools. -The `php` container (which might also have hhvm installed, depending on your version choice) is the container you can use to enter if you want to execute commands with the specified php version. +The situation inside the container is not different from on the Docker host. All services and port bindings are available there as well on `127.0.0.1`. Read up on [Technical](Technical.md) to find out more about the syncronization of both. -> **Note:** If you also have php installed locally on your host machine (and it is the php version of your choice), there is no need to enter the php container, just execute all the required commands on your project dir. +**FYI:** You will always find your projects inside the PHP container at `/shared/httpd/`. -To enter the php container, type the following in the devilbox root directory: -```shel -$ ./bash.sh -``` -You can alternatively also enter as root: -``` -$ ./root_bash.sh +#### 2.1 As devilbox user + +In the devilbox git directory you will find a bash script called `bash.sh`. Just execute this script and it will take you directly into the PHP docker container at the project root directory. + +```shell +host> ./bash.sh +devilbox@php-7.0.19 in /shared/httpd $ ``` -#### 3.2 Find your project files +As you can see, the PS1 prompt will also show you the current configured PHP version. -The `php` container mounts your project files (the path of `HOST_PATH_TO_WWW_DOCROOTS` as specified in the `.env` file) to `/shared/httpd`. +#### 2.2 As root user -So enter the container as described above and once inside the `php` container cd into `/shared/httpd`. +In case you need to perform some tasks that are only possible with root rights (such as installing or updating software), you can also use the `root_bash.sh` script. + +```shell +host> ./root_bash.sh +root@php-7.0.19 in /shared/httpd $ +``` + +**Note:** Performing installations and updates are only temporary for the current session. Any change will be lost at the next start/restart of the devilbox. If you permanently require additional software refer to [Hacking](Hacking.md). + +#### 2.3 Available tools + +For your convenience a few selected tools have been pre-installed in their current version that you can use for your daily development tasks. Some of them are: + +*composer, drush, drupal-console, git, node, npm* + +The complete list of tools including their version can be found at the PHP docker containers git repository Readme: + +[PHP 5.4](https://github.com/cytopia/docker-php-fpm-5.4) | +[PHP 5.5](https://github.com/cytopia/docker-php-fpm-5.5) | +[PHP 5.6](https://github.com/cytopia/docker-php-fpm-5.6) | +[PHP 7.0](https://github.com/cytopia/docker-php-fpm-7.0) | +[PHP 7.1](https://github.com/cytopia/docker-php-fpm-7.1) | +[HHVM](https://github.com/cytopia/docker-hhvm-latest) + +If you permanently require additional software refer to [Hacking](Hacking.md). + +If you think additional tools should always be bundled, [create an issue](https://github.com/cytopia/devilbox/issues). + +#### 2.4 Available URLs + +Your projects will be available by the same URL as they are available from your docker host computer. There is no need to edit the PHP container's `/etc/hosts` file, as it is automatically provide via the DNS container `bind`. + +For example, by doing `curl http://project1.dev` from either your host computer or from inside the PHP container will return the same URL. + +### 3. Creating Projects +#### 3.1 Creating projects on the docker host +#### 3.2 Creating projects from inside the PHP container + +### 4. Project DNS +#### 4.1 /etc/hosts +#### 4.2 Auto-DNS + +### 5. Switching container versions +#### 5.1 Httpd versions +#### 5.2 PHP versions +#### 5.3 SQL versions +#### 5.4 NoSQL versions + +### 6. Emails + +### 7. Log files + +### 8. Intranet +#### 8.1 Overview +#### 8.2 vHosts +#### 8.3 Tools From db10235d59247c3777fb95fbf349118a167926c9 Mon Sep 17 00:00:00 2001 From: cytopia Date: Wed, 14 Jun 2017 09:25:57 +0200 Subject: [PATCH 11/12] DVL-016 Usage documentation --- docs/Backups.md | 27 +++---- docs/Configure.md | 74 ++++++++++++++---- docs/Examples.md | 29 +++---- docs/FAQ.md | 23 +++--- docs/Hacking.md | 29 +++---- docs/Install.md | 27 +++---- docs/Quickstart.md | 130 +++++++++++++++++++++++++++++++ docs/README.md | 86 ++++++++++++++------- docs/Run.md | 31 ++++---- docs/Technical.md | 29 +++---- docs/Update.md | 68 ++++++++++++---- docs/Usage.md | 188 +++++++++++++++++++++++++++++++++++---------- update-docker.sh | 101 ++++++++++++++++++++++++ 13 files changed, 653 insertions(+), 189 deletions(-) create mode 100644 docs/Quickstart.md create mode 100755 update-docker.sh diff --git a/docs/Backups.md b/docs/Backups.md index 75ac506c..64cdede7 100644 --- a/docs/Backups.md +++ b/docs/Backups.md @@ -1,16 +1,17 @@ # Devilbox Documentation -**[Overview](README.md)** | -**[Install](Install.md)** | -**[Update](Update.md)** | -**[Configure](Configure.md)** | -**[Run](Run.md)** | -**[Usage](Usage.md)** | -**Backups** | -**[Examples](Examples.md)** | -**[Technical](Technical.md)** | -**[Hacking](Hacking.md)** | -**[FAQ](FAQ.md)** +[Overview](README.d) | +[Quickstart](Quickstart.md) | +[Install](Install.md) | +[Update](Update.md) | +[Configure](Configure.md) | +[Run](Run.md) | +[Usage](Usage.md) | +Backups | +[Examples](Examples.md) | +[Technical](Technical.md) | +[Hacking](Hacking.md) | +[FAQ](FAQ.md) --- @@ -25,12 +26,12 @@ --- -### 1. MySQL +## 1. MySQL #### 1.1 MySQL Database Backup #### 1.2 MySQL Database Restore -### 2. PostgreSQL +## 2. PostgreSQL #### 2.1 PostgreSQL Database Backup #### 2.2 PostgreSQL Database Restore diff --git a/docs/Configure.md b/docs/Configure.md index 87215769..7f6592a5 100644 --- a/docs/Configure.md +++ b/docs/Configure.md @@ -1,23 +1,71 @@ # Devilbox Documentation -**[Overview](README.md)** | -**[Install](Install.md)** | -**[Update](Update.md)** | -**Configure** | -**[Run](Run.md)** | -**[Usage](Usage.md)** | -**[Backups](Backups.md)** | -**[Examples](Examples.md)** | -**[Technical](Technical.md)** | -**[Hacking](Hacking.md)** | -**[FAQ](FAQ.md)** +[Overview](README.d) | +[Quickstart](Quickstart.md) | +[Install](Install.md) | +[Update](Update.md) | +Configure | +[Run](Run.md) | +[Usage](Usage.md) | +[Backups](Backups.md) | +[Examples](Examples.md) | +[Technical](Technical.md) | +[Hacking](Hacking.md) | +[FAQ](FAQ.md) --- ## Configure -1. TODO +1. [Overview]() +2. [Devilbox general settings](#1-devilbox-general-settings) + 1. [Verbosity]() + 2. [Devilbox base path]() + 3. [Host computer listening address]() +3. [Project settings]() + 1. [Project domain]() + 2. [Project path]() +4. [Container settings]() + 1. [General]() + 1. [Timezone]() + 2. [PHP / HHVM]() + 1. [User id]() + 2. [Group id]() + 3. [Xdebug]() + 4. [php.ini]() + 5. [HHVM]() + 3. [Webserver]() + 1. [Host port]() + 4. [MySQL]() + 1. [Root password]() + 2. [General Log]() + 3. [Host port]() + 4. [Data path]() + 5. [my.cnf]() + 5. [PostgreSQL]() + 1. [Root user]() + 2. [Root password]() + 3. [Host port]() + 4. [Data path]() + 6. [Redis]() + 1. [Host port]() + 7. [Memcached]() + 1. [Host port]() + 8. [MongoDB]() + 1. [Host port]() + 2. [Data path]() + 9. [Bind]() + 1. [Upstream resolver]() + 2. [Host port]() +5. [Intranet settings]() + 1. [DNS check timeout]() +6. [Host computer]() + 1. [DNS]() + 2. [/etc/hosts/]() --- -### 1. TODO +## 1. Overview + +To give you a brief overview about all available settings have a look at the following tags: + diff --git a/docs/Examples.md b/docs/Examples.md index 6361cc61..ccffd6d6 100644 --- a/docs/Examples.md +++ b/docs/Examples.md @@ -1,16 +1,17 @@ # Devilbox Documentation -**[Overview](README.md)** | -**[Install](Install.md)** | -**[Update](Update.md)** | -**[Configure](Configure.md)** | -**[Run](Run.md)** | -**[Usage](Usage.md)** | -**[Backups](Backups.md)** | -**Examples** | -**[Technical](Technical.md)** | -**[Hacking](Hacking.md)** | -**[FAQ](FAQ.md)** +[Overview](README.d) | +[Quickstart](Quickstart.md) | +[Install](Install.md) | +[Update](Update.md) | +[Configure](Configure.md) | +[Run](Run.md) | +[Usage](Usage.md) | +[Backups](Backups.md) | +Examples | +[Technical](Technical.md) | +[Hacking](Hacking.md) | +[FAQ](FAQ.md) --- @@ -22,9 +23,9 @@ --- -### 1. Setup Wordpress +## 1. Setup Wordpress -### 2. Setup Drupal +## 2. Setup Drupal -### 3. Setup Yii +## 3. Setup Yii diff --git a/docs/FAQ.md b/docs/FAQ.md index c1451914..8a63626d 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,16 +1,17 @@ # Devilbox Documentation -**[Overview](README.md)** | -**[Install](Install.md)** | -**[Update](Update.md)** | -**[Configure](Configure.md)** | -**[Run](Run.md)** | -**[Usage](Usage.md)** | -**[Backups](Backups.md)** | -**[Examples](Examples.md)** | -**[Technical](Technical.md)** | -**[Hacking](Hacking.md)** | -**FAQ** +[Overview](README.d) | +[Quickstart](Quickstart.md) | +[Install](Install.md) | +[Update](Update.md) | +[Configure](Configure.md) | +[Run](Run.md) | +[Usage](Usage.md) | +[Backups](Backups.md) | +[Examples](Examples.md) | +[Technical](Technical.md) | +[Hacking](Hacking.md) | +FAQ --- diff --git a/docs/Hacking.md b/docs/Hacking.md index 4f182b00..153eac0d 100644 --- a/docs/Hacking.md +++ b/docs/Hacking.md @@ -1,16 +1,17 @@ # Devilbox Documentation -**[Overview](README.md)** | -**[Install](Install.md)** | -**[Update](Update.md)** | -**[Configure](Configure.md)** | -**[Run](Run.md)** | -**[Usage](Usage.md)** | -**[Backups](Backups.md)** | -**[Examples](Examples.md)** | -**[Technical](Technical.md)** | -**Hacking** | -**[FAQ](FAQ.md)** +[Overview](README.d) | +[Quickstart](Quickstart.md) | +[Install](Install.md) | +[Update](Update.md) | +[Configure](Configure.md) | +[Run](Run.md) | +[Usage](Usage.md) | +[Backups](Backups.md) | +[Examples](Examples.md) | +[Technical](Technical.md) | +Hacking | +[FAQ](FAQ.md) --- @@ -28,7 +29,7 @@ --- -### 1. Rebuilding bundled Docker container +## 1. Rebuilding bundled Docker container The devilbox Docker container are rebuild frequently and pushed to [dockerhub](https://hub.docker.com/r/cytopia/). 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. @@ -69,7 +70,7 @@ If your devilbox git repository is checkout out on the `master` branch, then all -### 2. Customizing the bundled Docker container +## 2. Customizing the bundled Docker container Customizing a Docker container is almost as simple as rebuilding it. @@ -80,7 +81,7 @@ Customizing a Docker container is almost as simple as rebuilding it. 5. Read the rebuild section above to apply necessary steps -### 3. Adding your own Docker container +## 3. Adding your own Docker container You can add your custom docker container including its configuration to `docker-compose.yml`. diff --git a/docs/Install.md b/docs/Install.md index 4ee7f604..33fb936f 100644 --- a/docs/Install.md +++ b/docs/Install.md @@ -1,16 +1,17 @@ # Devilbox Documentation -**[Overview](README.md)** | -**Install** | -**[Update](Update.md)** | -**[Configure](Configure.md)** | -**[Run](Run.md)** | -**[Usage](Usage.md)** | -**[Backups](Backups.md)** | -**[Examples](Examples.md)** | -**[Technical](Technical.md)** | -**[Hacking](Hacking.md)** | -**[FAQ](FAQ.md)** +[Overview](README.d) | +[Quickstart](Quickstart.md) | +Install | +[Update](Update.md) | +[Configure](Configure.md) | +[Run](Run.md) | +[Usage](Usage.md) | +[Backups](Backups.md) | +[Examples](Examples.md) | +[Technical](Technical.md) | +[Hacking](Hacking.md) | +[FAQ](FAQ.md) --- @@ -26,7 +27,7 @@ --- -### 1. Install Docker +## 1. Install Docker Only requirement for the devilbox is to have docker and docker-compose installed, everything else is bundled and provided within the Docker container. @@ -46,7 +47,7 @@ Refer to the official [Docker for Mac documentation](https://docs.docker.com/doc **Note:** You should install the [Native Mac Docker](https://docs.docker.com/docker-for-mac/install/) and not the [Docker Toolbox](https://docs.docker.com/toolbox/overview/). -### 2. Install Devilbox +## 2. Install Devilbox Just clone the devilbox repository and copy the configuration file. diff --git a/docs/Quickstart.md b/docs/Quickstart.md new file mode 100644 index 00000000..c1ecfef0 --- /dev/null +++ b/docs/Quickstart.md @@ -0,0 +1,130 @@ +# Devilbox Documentation + +[Overview](README.md) | +Quickstart | +[Install](Install.md) | +[Update](Update.md) | +[Configure](Configure.md) | +[Run](Run.md) | +[Usage](Usage.md) | +[Backups](Backups.md) | +[Examples](Examples.md) | +[Technical](Technical.md) | +[Hacking](Hacking.md) | +[FAQ](FAQ.md) + +--- + +## Quickstart + +1. [Installation](#1-installation) +2. [Update](#2-update) + 1. [Tagged release](#2-1-tagged-release) + 2. [Master branch](#2-2-master-branch) +3. [Configuration](#3-configuration) + 1. [.env](#3-1-env) + 2. [Services](#3-2-services) +4. [Run](#4-run) + 1. [Run all](#4-1-run-all) + 2. [Run selection](#4-2-run-selection) +5. [Project setup](#5-project-setup) + +--- + +## 1. Installation + +```shell +$ git clone https://github.com/cytopia/devilbox +$ cd devilbox/ +$ cp env-example .env +``` + +## 2. Update + +#### 2.1 Tagged release + +```shell +$ docker-compose stop +$ git fetch --all +$ git checkout "$(git describe --abbrev=0 --tags)" +``` + +#### 2.2 Master branch + +```shell +$ docker-compose stop +$ git fetch --all +$ git pull origin master +$ ./update-docker.sh +``` + +## 3. Configuration + +#### 3.1 .env + +Edit all general settings inside the .env file (file paths, what version to run, debug, timezeon, etc) +```shell +$ vim .env +``` + +#### 3.2 Services + +Configure PHP 5.6 +```shell +$ cd cfg/ +$ echo "max_execution_time = 180" > php-fpm-5.6/config.ini +``` + +Configure MySQL 5.5 +```shell +$ cd cfg/ +$ echo "[mysqld]\nslow_query_log = 1" > mysql-5.5/config.cnf +``` + +## 4. Run + +#### 4.1 Run all + +```shell +$ docker-compose up -d +``` + +#### 4.2 Run selection + +```shell +$ docker-compose up -d httpd php mysql redis +``` + +## 5. Project setup + +**Assumption:** + +1. HOST_PATH_TO_HTTPD_DATADIR=**./data/www** +2. TLD_SUFFIX=**local** +3. Three Projects: project1, project2 and wordpress + +**Folder setup on your Host system:** + +| VirtualHost directory | DocumentRoot directory | URL | +|-----------------------|-----------------------------|------------------------| +| ./data/www/project1 | ./data/www/project1/htdocs | `http://project1.local` | +| ./data/www/project2 | ./data/www/project2/htdocs | `http://project2.local` | +| ./data/www/wordpress| ./data/www/wordpress/htdocs | `http://wordpress.local` | + +Each VirtualHost will serve files from the **htdocs/** folder. + +**DNS setup on your Host system:** + +| Project folder | `/etc/hosts` entry | +|----------------|----------------------------| +| project1 | `127.0.0.1 project1.local` | +| project2 | `127.0.0.1 project2.local` | +| wordpress | `127.0.0.1 wordpress.local`| + +Some frameworks have a nested www directory and require you to use a symlink instead of explicitly setting a **htdocs/** folder. See the CakePHP folder setup below: + +```shell +$ ls -l +drwxrwxr-x 2 cytopia 4096 Jun 14 08:29 cakephp +lrwxrwxrwx 1 cytopia 11 Jun 14 08:29 htdocs -> cakephp/app/webroot/ +``` diff --git a/docs/README.md b/docs/README.md index e9f5b4bd..daf94203 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,33 +1,35 @@ # Devilbox Documentation -**Overview** | -**[Install](Install.md)** | -**[Update](Update.md)** | -**[Configure](Configure.md)** | -**[Run](Run.md)** | -**[Usage](Usage.md)** | -**[Backups](Backups.md)** | -**[Examples](Examples.md)** | -**[Technical](Technical.md)** | -**[Hacking](Hacking.md)** | -**[FAQ](FAQ.md)** +Overview | +[Quickstart](Quickstart.md) | +[Install](Install.md) | +[Update](Update.md) | +[Configure](Configure.md) | +[Run](Run.md) | +[Usage](Usage.md) | +[Backups](Backups.md) | +[Examples](Examples.md) | +[Technical](Technical.md) | +[Hacking](Hacking.md) | +[FAQ](FAQ.md) --- ## Overview 1. [Main idea](#1-main-idea) -2. [Supported Host OS](#2-supported-host-os) -3. [Requirements](#3-requirements) -4. [Docker documentation](#4-docker-documentation) -5. [Devilbox documentation](#5-devilbox-documentation) -6. [Video Tutorials](#6-video-tutorials) -7. [Available PHP Modules](#7-available-php-modules) -8. [Supported Frameworks and CMS](#8-supported-frameworks-and-cms) +2. [Features](#2-features) +3. [Supported Host OS](#3-supported-host-os) +4. [Requirements](#4-requirements) +5. [Docker documentation](#5-docker-documentation) +6. [Devilbox documentation](#6-devilbox-documentation) +7. [Video Tutorials](#7-video-tutorials) +8. [Available PHP Modules](#8-available-php-modules) +9. [Supported Frameworks and CMS](#9-supported-frameworks-and-cms) --- -### 1. Main idea +## 1. Main idea The devilbox allows you to have an unlimitted number of projects ready without having to install any external software and without having to configure any virtual hosts. As well as providing a very flexible development stack that you can run offline. (Internet is only required to initially pull docker container). @@ -55,7 +57,39 @@ By having the above folders, the devilbox will automatically be able to serve th New folders can be created, deleted and removed during run-time and corresponding virtual hosts will be available instantly without having to restart anything. -### 2. Supported Host OS +## 2. Features + +| Feature | Description | +|---------|-------------| +| **Internet** | | +| No always-on | Internet connection is only required during initial setup or update (to pull containers), afterwards you can always work offline. | +| **Projects** | | +| Unlimitted Projects | Add as many Projects as you need. | +| Auto VirtualHosts | New VirtualHosts are added instantly without a restart or reload. Just create a new directory and you are ready to go. | +| Auto DNS | Use the built-in DNS server to stop worrying about `/etc/hosts` setup per project. | +| Email catch-all | All outgoing emails are intercepted and stored locally. Use the intranet to view any sent email. | +| Custom VirtualHost domains | Whatever project domain you desire: `*.dev`, `*.loc`, `*.local` or even subdomains like `*.sub.example` - you can adjust it to your needs. | +| **Run** | | +| Selective start | Run only the Docker container you actually need. | +| Version choice | Use your development stack with whatever version combination needed. | +| Stack choice | Attach SQL or NoSQL container and use Nginx or Apache to simulate your live env. | +| Log files | Log files are available for each chosen version. | +| **Configuration** | | +| HHVM | You can choose between PHP 5.6 and PHP 7 mode for HHVM | +| php.ini | You an overwrite PHP settings for each PHP version. | +| my.cnf | You an overwrite MySQL settings for each MySQL version. | +| **Intranet** | | +| phpMyAdmin | Manage your MySQL databases here. | +| Adminer | Manage your SQL and NoSQL databases here. | +| OpCacheGUI | Visualize the state of opcache usage. | +| EmailGUI | See all sent emails at a glance | +| **Docker Tools**| +| Work inside container | You can completely work inside the PHP container and use all bundled tools in order to keep your host system clean. | +| **Hacking** | +| Add custom container | You can add any other Docker container to `docker-compose.yml` and start using them in your development stack. | + + +## 3. Supported Host OS The devilbox runs on all major operating systems. Below you can quickly check the recommended docker versions and current issues per OS. @@ -75,7 +109,7 @@ The devilbox runs on all major operating systems. Below you can quickly check th [osx-issues]: https://github.com/cytopia/devilbox/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3A%22host%3Aosx%22 -### 3. Requirements +## 4. Requirements * **Internet connection** - only required during initial setup for cloning the devilbox repository and pulling the required docker container. Afterwards you can always work offline. * [Docker Engine 1.12.0+](https://docs.docker.com/compose/compose-file/compose-versioning/#version-21) @@ -84,12 +118,12 @@ The devilbox runs on all major operating systems. Below you can quickly check th * On OSX use [Docker for Mac][d4m] (not tested on [Docker Toolbox][dtb]) -### 4. Docker documentation +## 5. Docker documentation If you have never worked with docker/docker-compose before, you should check up on their documentation to get you started: [docker docs](https://docs.docker.com/). -### 5. Devilbox documentation +## 6. Devilbox documentation | Topic | Description | |-------------------------|-------------| @@ -104,7 +138,7 @@ If you have never worked with docker/docker-compose before, you should check up | **[FAQ](FAQ.md)** | Questions and Troubleshooting | -### 6. Video Tutorials +## 7. Video Tutorials Have a look at youtube to see some the features in action. @@ -112,7 +146,7 @@ Have a look at youtube to see some the features in action. [![Devilbox email catch-all](img/devilbox_02-email-catch-all.png "devilbox - email catch-all")](https://www.youtube.com/watch?v=e-U-C5WhxGY) -### 7. Available PHP Modules +## 8. Available PHP Modules The devilbox is a development stack, so it is made sure that a lot of PHP modules are available out of the box in order to work with many different frameworks. @@ -127,7 +161,7 @@ There will however be slight differences between the versions and especially wit [PHP 7.1](https://github.com/cytopia/docker-php-fpm-7.1) | [HHVM](https://github.com/cytopia/docker-hhvm-latest) -### 8. Supported Frameworks and CMS +## 9. Supported Frameworks and CMS As far as tested there are no limitations and you can use any Framework or CMS just as you would on your live environment. Below are a few examples of extensively tested Frameworks and CMS: diff --git a/docs/Run.md b/docs/Run.md index 1cbd5d21..b989e9ac 100644 --- a/docs/Run.md +++ b/docs/Run.md @@ -1,16 +1,17 @@ # Devilbox Documentation -**[Overview](README.md)** | -**[Install](Install.md)** | -**[Update](Update.md)** | -**[Configure](Configure.md)** | -**Run** | -**[Usage](Usage.md)** | -**[Backups](Backups.md)** | -**[Examples](Examples.md)** | -**[Technical](Technical.md)** | -**[Hacking](Hacking.md)** | -**[FAQ](FAQ.md)** +[Overview](README.d) | +[Quickstart](Quickstart.md) | +[Install](Install.md) | +[Update](Update.md) | +[Configure](Configure.md) | +Run | +[Usage](Usage.md) | +[Backups](Backups.md) | +[Examples](Examples.md) | +[Technical](Technical.md) | +[Hacking](Hacking.md) | +[FAQ](FAQ.md) --- @@ -34,7 +35,7 @@ --- -### 1. Start the devilbox +## 1. Start the devilbox Starting and stopping containers is done via docker-compose. If you have never worked with it before, have a look at their documentation for an [overview](https://docs.docker.com/compose/reference/overview/), [up](https://docs.docker.com/compose/reference/up/) and [stop](https://docs.docker.com/compose/reference/stop/) commands. @@ -104,7 +105,7 @@ $ docker-compose up -d pgsql redis **Log Note:** When you do not specify httpd, php and bind in foreground start, their docker-logs will not be shown and you will have to explicitly use `docker-compose logs` to view their stdout/stderr output. Refer to the Log section below. -### 2. Stop the devilbox +## 2. Stop the devilbox #### 2.1 Foreground stop @@ -126,7 +127,7 @@ $ docker-compose kill Best pracice would be to start the container in the background (with `-d`) and use `docker compose down` to gracefully stop all of them. -### 3. Attach/Detach during run-time +## 3. Attach/Detach during run-time #### 3.1 Attach during run-time @@ -151,7 +152,7 @@ You can also stop specific containers during runtime if they are not needed anym $ docker-compose stop redis ``` -### 4. Docker Logs +## 4. Docker Logs Services started in background mode (`-d`) or those that were started as dependencies (`http` and `php`) will always only log to docker logs and not to stdout/stderr. diff --git a/docs/Technical.md b/docs/Technical.md index 3038f33e..50618b19 100644 --- a/docs/Technical.md +++ b/docs/Technical.md @@ -1,16 +1,17 @@ # Devilbox Documentation -**[Overview](README.md)** | -**[Install](Install.md)** | -**[Update](Update.md)** | -**[Configure](Configure.md)** | -**[Run](Run.md)** | -**[Usage](Usage.md)** | -**[Backups](Backups.md)** | -**[Examples](Examples.md)** | -**Technical** | -**[Hacking](Hacking.md)** | -**[FAQ](FAQ.md)** +[Overview](README.d) | +[Quickstart](Quickstart.md) | +[Install](Install.md) | +[Update](Update.md) | +[Configure](Configure.md) | +[Run](Run.md) | +[Usage](Usage.md) | +[Backups](Backups.md) | +[Examples](Examples.md) | +Technical | +[Hacking](Hacking.md) | +[FAQ](FAQ.md) --- @@ -24,7 +25,7 @@ --- -### 1. Networking +## 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. @@ -41,7 +42,7 @@ It is best to use the hostnames and not to rely on the ip addresses as they migh | Memcached | memcd | memcd | 172.16.238.15 | | MongoDB | mongo | mongo | 172.16.238.16 | -### 2. Ports and forwarding +## 2. Ports and forwarding #### 2.1 PHP Container @@ -95,7 +96,7 @@ The following container can be reached from the Docker host via the following me | Memcached | 127.0.0.1 | 11211 | | MongoDB | 127.0.0.1 | 27017 | -### 3. Works the same on Host and PHP Container +## 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: diff --git a/docs/Update.md b/docs/Update.md index 2b1749a3..584f94d9 100644 --- a/docs/Update.md +++ b/docs/Update.md @@ -1,16 +1,17 @@ # Devilbox Documentation -**[Overview](README.md)** | -**[Install](Install.md)** | -**Update** | -**[Configure](Configure.md)** | -**[Run](Run.md)** | -**[Usage](Usage.md)** | -**[Backups](Backups.md)** | -**[Examples](Examples.md)** | -**[Technical](Technical.md)** | -**[Hacking](Hacking.md)** | -**[FAQ](FAQ.md)** +[Overview](README.d) | +[Quickstart](Quickstart.md) | +[Install](Install.md) | +Update | +[Configure](Configure.md) | +[Run](Run.md) | +[Usage](Usage.md) | +[Backups](Backups.md) | +[Examples](Examples.md) | +[Technical](Technical.md) | +[Hacking](Hacking.md) | +[FAQ](FAQ.md) --- @@ -25,21 +26,31 @@ --- -### 1. TL;DR +## 1. TL;DR Shutdown, update and startup. ```shell +# Stop container and update git $ docker-compose down +$ git fetch --all $ git pull origin master + +# Check for changes $ vimdiff .env env-example + +# Pull all available container +$ ./update-docker.sh +# Or just pull currently enabled versions in .env $ docker-compose pull + +# Ready and run $ docker-compose up ``` Do not forget to read: [Pull new Docker container (Important!)](#4-pull-new-docker-container-important-) -### 2. Git tag vs master branch +## 2. Git tag vs master branch #### 2.1 Git tag @@ -58,6 +69,20 @@ That means within your current git tag, you will not receive any Docker containe When a new devilbox tag is released, the `docker-compose.yml` file will have new Docker tags. There is no manuall action required. If you start up the devilbox for the first time, it will see that the container with those tags are not available locally and automatically start downloading them. +So the update procedure is as follows: + +```shell +$ git fetch --all +$ git checkout "$(git describe --abbrev=0 --tags)" +``` + + +**Note:** If you want to pre-download all available versions for later offline-usage, run the `update-docker.sh` script. + +```shell +$ ./update-docker.sh +``` + #### 2.2 Git master branch The git master branch ties each Docker container to their `latest` tag. Latest tagged Docker container always reflect the latest changes and can be compared with a master branch of a git repository. This will look like this in the `docker-compose.yml` @@ -76,11 +101,18 @@ When you update the devilbox repository by `git pull origin master`, the Docker So the update procedure is as follows: ```shell +$ git fetch --all $ git pull origin master $ docker-compose pull ``` -### 3. Compare .env file +**Note:** If you want to pre-download all available versions for later offline-usage, run the `update-docker.sh` script. + +```shell +$ ./update-docker.sh +``` + +## 3. Compare .env file New devilbox releases will most likeley receive new or improved functionality and features and therefore will have an altered `env-example` file. (This is an example configuration file which holds all current configuration options). The effective configuration for docker-compose is stored in the `.env` file. However, the `.env` file is ignored by git, so that you can do changes without setting the git state dirty. @@ -93,7 +125,7 @@ $ vimdiff .env env-example Make sure to transfer all new options from `env-example` to your current `.env` file. -### 4. Pull new Docker container (Important!) +## 4. Pull new Docker container (Important!) As described above, for git master branch updates you will always have to pull new Docker container. **However, there is something very important to keep in mind:** @@ -113,4 +145,8 @@ image: cytopia/${MYSQL_SERVER:-mariadb-10.1}:latest As you can see, the Docker container names are variablized. If you updated `php-fpm-5.4:latest`, you still have to update `php-fpm-5.5:latest` (and all others) as they were not yet enabled/visible in `docker-compose.yml`. -If there is anything unclear about this behaviour, open an **[Issue on Github](https://github.com/cytopia/devilbox/issues)**. +So instead of pulling everything manually, use the bundled update script to do that for all available Docker container. That will also allow you to work offline, as every available docker image will be download in their latest version. + +```shell +$ ./update-docker.sh +``` diff --git a/docs/Usage.md b/docs/Usage.md index 0de532e8..c8f7dc3f 100644 --- a/docs/Usage.md +++ b/docs/Usage.md @@ -1,16 +1,17 @@ # Devilbox Documentation -**[Overview](README.md)** | -**[Install](Install.md)** | -**[Update](Update.md)** | -**[Configure](Configure.md)** | -**[Run](Run.md)** | -**Usage** | -**[Backups](Backups.md)** | -**[Examples](Examples.md)** | -**[Technical](Technical.md)** | -**[Hacking](Hacking.md)** | -**[FAQ](FAQ.md)** +[Overview](README.d) | +[Quickstart](Quickstart.md) | +[Install](Install.md) | +[Update](Update.md) | +[Configure](Configure.md) | +[Run](Run.md) | +Usage | +[Backups](Backups.md) | +[Examples](Examples.md) | +[Technical](Technical.md) | +[Hacking](Hacking.md) | +[FAQ](FAQ.md) --- @@ -22,27 +23,31 @@ 2. [As root user](#2-2-as-root-user) 3. [Available tools](#2-3-available-tools) 4. [Available URLs](#2-4-available-urls) -3. [Creating Projects](#3-creating-projects) - 1. [Creating projects on the docker host](#3-1-creating-projects-on-the-docker-host) - 2. [Creating projects from inside the PHP container](#3-2-creating-projects-from-inside-the-php-container) -4. [Project DNS](#4-project-dns) - 1. [/etc/hosts](#4-1-etc-hosts) - 2. [Auto-DNS](#4-2-auto-dns) -5. [Switching container versions](#5-switching-container-versions) +3. [Creating new Projects](#3-creating-new-projects) + 1. [How does it work?](#3-1-) + 2. [Directory structure explained](#3-2-) + 3. [Creating new Projects](#3-3-) + 1. [From Docker Host](#3-3-1-) + 2. [From inside the PHP container](#3-3-2-) + 3. [Using symlinks](#3-3-3-) + 4. [Adding DNS records](#3-4-) + 1. [/etc/hosts](#3-4-1-) + 2. [Auto-DNS](#3-4-2-) +4. [Switching container versions](#5-switching-container-versions) 1. [Httpd versions](#5-1-httpd-versions) 2. [PHP versions](#5-2-php-versions) 2. [SQL versions](#5-3-sql-versions) 3. [NoSQL versions](#5-4-nosql-versions) -6. [Emails](#6-emails) -7. [Log files](#7-log-files) -8. [Intranet](#8-intranet) +5. [Emails](#6-emails) +6. [Log files](#7-log-files) +7. [Intranet](#8-intranet) 1. [Overview](#8-1-overview) 2. [vHosts](#8-2-vhosts) 3. [Tools](#8-3-tools) --- -### 1. Work on the Docker host +## 1. Work on the Docker host If you do not need to run any command line tools manually (composer, node, etc), it is sufficient to stay on the host. All you need is a browser and an editor/IDE. @@ -64,12 +69,15 @@ $ docker-compose exec --user devilbox php on the user to command docker devilbox exec to container command execute +``` +Here is an example to list the PHP inside the container from the Docker host. +```shell # Print PHP version $ docker-compose exec --user devilbox php php -v ``` -### 2. Work inside the PHP container +## 2. Work inside the PHP container If you need to run some command line tasks manually such as `drush`, `composer` or anything similar which is not available on your host computer, you can do that inside the PHP container, which comes with lots of useful pre-install tools. @@ -124,26 +132,126 @@ Your projects will be available by the same URL as they are available from your For example, by doing `curl http://project1.dev` from either your host computer or from inside the PHP container will return the same URL. -### 3. Creating Projects -#### 3.1 Creating projects on the docker host -#### 3.2 Creating projects from inside the PHP container +## 3. Creating new Projects +[![Devilbox setup and workflow](img/devilbox_01-setup-and-workflow.png "devilbox - setup and workflow")](https://www.youtube.com/watch?v=reyZMyt2Zzo) -### 4. Project DNS -#### 4.1 /etc/hosts -#### 4.2 Auto-DNS +#### 3.1 How does it work? -### 5. Switching container versions -#### 5.1 Httpd versions -#### 5.2 PHP versions -#### 5.3 SQL versions -#### 5.4 NoSQL versions +Creating new projects is really simple and just involves a few steps. -### 6. Emails +1. Create a new **project folder** for your VirtualHost +2. Create a subfolder named **htdocs/** for the DocumentRoot +2. Create a **DNS record** pointing to your VirtualHost (via `/etc/hosts`) -### 7. Log files +The **project folder** will be the name of your VirtualHost. The **htdocs/** folder holds all files that will be server by the VirtualHost (called DocumentRoot). The **DNS record** will be the domain name that points to the webserver's IP address (127.0.0.1). -### 8. Intranet -#### 8.1 Overview -#### 8.2 vHosts -#### 8.3 Tools +#### 3.2 Directory structure explained + +Your project folder is determined by the value of `HOST_PATH_TO_HTTPD_DATADIR` which can be set in `.env`. The default is `./data/www`. + +| Location | Project directory | +|--------------|-------------------| +| Host system | `HOST_PATH_TO_HTTPD_DATADIR` (default: `./data/www`) | +| PHP Docker | `/shared/httpd` | +| HTTPD Docker | `/shared/httpd` | + + +**What directory structure is required to serve a new project?** + +1. Each folder inside your project directory is an independent VirtualHost. +2. Each VirtualHost folder requires the `htdocs/` folder which is the DocumentRoot. + +In order to make the following examples easier let's work with some assumed default values. The first one represents the project base directory and the second one is for the project domains. + +1. HOST_PATH_TO_HTTPD_DATADIR=**./data/www** +2. TLD_SUFFIX=**local** + +| VirtualHost directory | DocumentRoot directory | URL | +|-----------------------|-----------------------------|------------------------| +| ./data/www/project1 | ./data/www/project1/htdocs | `http://project1.local` | +| ./data/www/project2 | ./data/www/project2/htdocs | `http://project2.local` | +| ./data/www/wordpress| ./data/www/wordpress/htdocs | `http://wordpress.local` | + +The VirtualHost directory make a new VirtualHost available under the specified URL. However the actual files that will be served are always expected to be in a subfolder called `htdocs/`. By having an additional sub-directory for the Document root you are able to store non-www files inside the project folder and even **symlink** you www dir to htdocs. + + +#### 3.3 Creating new Projetcs + +##### 3.3.1 From Docker host + +The following will create a VirtualHost for `http://project1.local`. + +```shell +# replace HOST_PATH_TO_HTTPD_DATADIR with the actual project base dir +$ cd HOST_PATH_TO_HTTPD_DATADIR +$ mkdir project1 +$ mkdir project1/htdocs +``` + +If you want to know how to change the TLD_SUFFIX `local` to something else, refer to [Configure](Configure.md). + +##### 3.3.2 From inside the PHP container + +If you prefer to work directly inside the PHP Docker container, you can do the same. The following will create a VirtualHost for `http://project1.local`. + +```shell +$ cd /shared/httpd +$ mkdir project1 +$ mkdir project1/htdocs +``` + +If you want to know how to go into the PHP container, check the section above **2. Work inside the PHP container**. + +##### 3.3.3 Using symlinks + +Instead of creating a **htdocs/** folder explicitly, you can also make a symlink by the same name. This is required as some frameworks have nested www folders. + +Keep the actual versioned wordpress name and symlink it to htdocs. +```shell +$ ls -l +drwxrwxr-x 2 cytopia 4096 Jun 14 08:29 wordpress-4.8 +lrwxrwxrwx 1 cytopia 11 Jun 14 08:29 htdocs -> wordpress-4.8/ +``` + +CakePHP serves its files from a nested folder, a symlink is required here. +```shell +$ ls -l +drwxrwxr-x 2 cytopia 4096 Jun 14 08:29 cakephp +lrwxrwxrwx 1 cytopia 11 Jun 14 08:29 htdocs -> cakephp/app/webroot/ +``` + +#### 3.4 Adding DNS record + +In order to actually visit the newly created project in your browser, there must be a DNS entry pointing to the webserver's listening IP address. This can either be done automatically by a DNS server or you can do it manually for each project by editing your `/etc/hosts` file every time you create a new project. + +##### 3.4.1 /etc/hosts + +If you have not setup Auto-DNS, you will need to create your own DNS records for every project. Let's assume your `TLD_SUFFIX` is set to `local`. + +| Project folder | `/etc/hosts` entry | +|----------------|-------------------------------| +| my-project1 | `127.0.0.1 my-project1.local` | +| drupal-test | `127.0.0.1 drupal-test.local` | +| playground | `127.0.0.1 playground.local` | + + +##### 3.4.2 Auto-DNS + +When using the devilbox built-in DNS server, there is nothing to do. DNS catch-all records for your `TLD_SUFFIX` exist and will always point to `127.0.0.1`. See [Configure](Configure.md) for how to setup Auto-DNS. + + +## 4. Switching container versions +#### 4.1 Httpd versions +#### 4.2 PHP versions +#### 4.3 SQL versions +#### 4.4 NoSQL versions + +## 5. Emails + +## 5. Log files + +## 6. Intranet +#### 6.1 Overview +#### 6.2 vHosts +#### 6.3 Tools diff --git a/update-docker.sh b/update-docker.sh new file mode 100755 index 00000000..5d771c89 --- /dev/null +++ b/update-docker.sh @@ -0,0 +1,101 @@ +#!/bin/sh +# +# This script will pull all Docker images that are currently +# bound to your devilbox git state. +# +# When updating the devilbox via git, do run this script once +# in order to download all images locally. +# + +### +### Path of devilbox repository +### +CWD="$(cd -P -- "$(dirname -- "$0")" && pwd -P)" + +### +### DNS +### +TAG="$( grep '^[[:space:]]*image:[[:space:]]*cytopia/bind' "${CWD}/docker-compose.yml" | sed 's/^.*://g' )" +docker pull cytopia/bind:${TAG} + +### +### PHP +### +TAG="$( grep '^[[:space:]]*image:.*\${PHP_SERVER' "${CWD}/docker-compose.yml" | sed 's/^.*://g' )" +docker pull cytopia/php-fpm-5.4:${TAG} +docker pull cytopia/php-fpm-5.5:${TAG} +docker pull cytopia/php-fpm-5.6:${TAG} +docker pull cytopia/php-fpm-7.0:${TAG} +docker pull cytopia/php-fpm-7.1:${TAG} +docker pull cytopia/hhvm-latest:${TAG} + +### +### HTTPD +### +TAG="$( grep '^[[:space:]]*image:.*\${HTTPD_SERVER' "${CWD}/docker-compose.yml" | sed 's/^.*://g' )" +docker pull cytopia/nginx-stable:${TAG} +docker pull cytopia/nginx-mainline:${TAG} +docker pull cytopia/apache-2.2:${TAG} +docker pull cytopia/apache-2.4:${TAG} + +### +### MYSQL +### +TAG="$( grep '^[[:space:]]*image:.*\${MYSQL_SERVER' "${CWD}/docker-compose.yml" | sed 's/^.*://g' )" +docker pull cytopia/mysql-5.5:${TAG} +docker pull cytopia/mysql-5.6:${TAG} +docker pull cytopia/mysql-5.7:${TAG} +docker pull cytopia/mysql-8.0:${TAG} +docker pull cytopia/mariadb-5.5:${TAG} +docker pull cytopia/mariadb-10.0:${TAG} +docker pull cytopia/mariadb-10.1:${TAG} +docker pull cytopia/mariadb-10.2:${TAG} +docker pull cytopia/mariadb-10.3:${TAG} + +### +### PGSQL +### +docker pull postgres:9.1 +docker pull postgres:9.2 +docker pull postgres:9.3 +docker pull postgres:9.4 +docker pull postgres:9.5 +docker pull postgres:9.6 + +### +### REDIS +### +docker pull redis:2.8 +docker pull redis:3.0 +docker pull redis:3.2 + +### +### MEMCACHED +### +docker pull memcached:1.4.21 +docker pull memcached:1.4.22 +docker pull memcached:1.4.23 +docker pull memcached:1.4.24 +docker pull memcached:1.4.25 +docker pull memcached:1.4.26 +docker pull memcached:1.4.27 +docker pull memcached:1.4.28 +docker pull memcached:1.4.29 +docker pull memcached:1.4.30 +docker pull memcached:1.4.31 +docker pull memcached:1.4.32 +docker pull memcached:1.4.33 +docker pull memcached:1.4.34 +docker pull memcached:1.4.35 +docker pull memcached:1.4.36 +docker pull memcached:latest + +### +### MONGODB +### +docker pull mongo:2.8 +docker pull mongo:3.0 +docker pull mongo:3.2 +docker pull mongo:3.4 +docker pull mongo:3.5 + From 148657b11db33f5cf0314be5a8181ae6ab81f228 Mon Sep 17 00:00:00 2001 From: cytopia Date: Thu, 15 Jun 2017 08:46:50 +0200 Subject: [PATCH 12/12] DVL-016 Usage documentation --- docs/Backups.md | 2 +- docs/Configure.md | 3 +- docs/Examples.md | 17 ++++-- docs/FAQ.md | 24 +++++++- docs/Hacking.md | 2 +- docs/Install.md | 2 +- docs/Run.md | 2 +- docs/Technical.md | 2 +- docs/Update.md | 2 +- docs/Usage.md | 136 ++++++++++++++++++++++++++++++++++------------ 10 files changed, 144 insertions(+), 48 deletions(-) diff --git a/docs/Backups.md b/docs/Backups.md index 64cdede7..ec5412f5 100644 --- a/docs/Backups.md +++ b/docs/Backups.md @@ -1,6 +1,6 @@ # Devilbox Documentation -[Overview](README.d) | +[Overview](README.md) | [Quickstart](Quickstart.md) | [Install](Install.md) | [Update](Update.md) | diff --git a/docs/Configure.md b/docs/Configure.md index 7f6592a5..3cc51171 100644 --- a/docs/Configure.md +++ b/docs/Configure.md @@ -1,6 +1,6 @@ # Devilbox Documentation -[Overview](README.d) | +[Overview](README.md) | [Quickstart](Quickstart.md) | [Install](Install.md) | [Update](Update.md) | @@ -67,5 +67,4 @@ Configure | ## 1. Overview -To give you a brief overview about all available settings have a look at the following tags: diff --git a/docs/Examples.md b/docs/Examples.md index ccffd6d6..9fe4795e 100644 --- a/docs/Examples.md +++ b/docs/Examples.md @@ -1,6 +1,6 @@ # Devilbox Documentation -[Overview](README.d) | +[Overview](README.md) | [Quickstart](Quickstart.md) | [Install](Install.md) | [Update](Update.md) | @@ -17,15 +17,22 @@ Examples | ## Examples -1. [Setup Wordpress](#1-setup-wordpress) +1. [Setup CakePHP](#1-setup-cakephp) 2. [Setup Drupal](#2-setup-drupal) -3. [Setup Yii](#3-setup-yii) +3. [Setup Symfony](#3-setup-symfony) +4. [Setup Wordpress](#4-setup-wordpress) +5. [Setup Yii](#5-setup-yii) --- -## 1. Setup Wordpress + +## 1. Setup CakePHP ## 2. Setup Drupal -## 3. Setup Yii +## 3. Setup Symfony + +## 4. Setup Wordpress + +## 5. Setup Yii diff --git a/docs/FAQ.md b/docs/FAQ.md index 8a63626d..0ccba120 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,6 +1,6 @@ # Devilbox Documentation -[Overview](README.d) | +[Overview](README.md) | [Quickstart](Quickstart.md) | [Install](Install.md) | [Update](Update.md) | @@ -48,10 +48,32 @@ Yes. `http` and `php` will automatically always be started (due to dependencies **What PHP Modules are available?** +The devilbox is a development stack, so it is made sure that a lot of PHP modules are available out of the box in order to work with many different frameworks. + +*apc, apcu, bcmath, bz2, calendar, Core, ctype, curl, date, dom, ereg, exif, fileinfo, filter, ftp, gd, gettext, gmp, hash, iconv, igbinary, imagick, imap, intl, json, ldap, libxml, magickwand, mbstring, mcrypt, memcache, memcached, mhash, mongodb, msgpack, mysql, mysqli, mysqlnd, openssl, pcntl, pcre, PDO, pdo_mysql, pdo_pgsql, pdo_sqlite, pgsql, phalcon, Phar, posix, pspell, readline, recode, redis, Reflection, session, shmop, SimpleXML, soap, sockets, SPL, sqlite3, standard, sysvmsg, sysvsem, sysvshm, tidy, tokenizer, uploadprogress, wddx, xdebug, xml, xmlreader, xmlrpc, xmlwriter, xsl, Zend OPcache, zip, zlib* + +There will however be slight differences between the versions and especially with HHVM. To see the exact bundled modules for each version visit the corresponding docker repositories on Github: + +[PHP 5.4](https://github.com/cytopia/docker-php-fpm-5.4) | +[PHP 5.5](https://github.com/cytopia/docker-php-fpm-5.5) | +[PHP 5.6](https://github.com/cytopia/docker-php-fpm-5.6) | +[PHP 7.0](https://github.com/cytopia/docker-php-fpm-7.0) | +[PHP 7.1](https://github.com/cytopia/docker-php-fpm-7.1) | +[HHVM](https://github.com/cytopia/docker-hhvm-latest) + + **Can I add other PHP Modules?** +Yes, if there are any PHP modules you require that are not yet available in the PHP Docker container, you can install it during run-time, or create your own container. See [Hacking](Hacking.md) for more informatino. + **Can I change php.ini?** +Yes, php.ini directives can be changes on a per PHP version base. Go to `./cfg/` inside devilbox git diretory. There you will find configuration directories for each php version. Just put a \*.ini file there and restart the devilbox. + **Can I change my.cnf?** +Yes, my.cnf directives can be changes on a per MySQL version base. Go to `./cfg/` inside devilbox git diretory. There you will find configuration directories for each MySQL version. Just put a \*.cnf file there and restart the devilbox. + **Can I switch HHVM between PHP 5.6 and PHP 7 mode?** + +Yes, this can be done by adding a \*.ini file to `./cfg/hhvm-latest/` with the following content: `hhvm.php7.all = 0` to disable PHP 7. The default is to use PHP 7 mode. diff --git a/docs/Hacking.md b/docs/Hacking.md index 153eac0d..d228dcc9 100644 --- a/docs/Hacking.md +++ b/docs/Hacking.md @@ -1,6 +1,6 @@ # Devilbox Documentation -[Overview](README.d) | +[Overview](README.md) | [Quickstart](Quickstart.md) | [Install](Install.md) | [Update](Update.md) | diff --git a/docs/Install.md b/docs/Install.md index 33fb936f..6f8fbdc5 100644 --- a/docs/Install.md +++ b/docs/Install.md @@ -1,6 +1,6 @@ # Devilbox Documentation -[Overview](README.d) | +[Overview](README.md) | [Quickstart](Quickstart.md) | Install | [Update](Update.md) | diff --git a/docs/Run.md b/docs/Run.md index b989e9ac..b14557d4 100644 --- a/docs/Run.md +++ b/docs/Run.md @@ -1,6 +1,6 @@ # Devilbox Documentation -[Overview](README.d) | +[Overview](README.md) | [Quickstart](Quickstart.md) | [Install](Install.md) | [Update](Update.md) | diff --git a/docs/Technical.md b/docs/Technical.md index 50618b19..74453afb 100644 --- a/docs/Technical.md +++ b/docs/Technical.md @@ -1,6 +1,6 @@ # Devilbox Documentation -[Overview](README.d) | +[Overview](README.md) | [Quickstart](Quickstart.md) | [Install](Install.md) | [Update](Update.md) | diff --git a/docs/Update.md b/docs/Update.md index 584f94d9..2a031df1 100644 --- a/docs/Update.md +++ b/docs/Update.md @@ -1,6 +1,6 @@ # Devilbox Documentation -[Overview](README.d) | +[Overview](README.md) | [Quickstart](Quickstart.md) | [Install](Install.md) | Update | diff --git a/docs/Usage.md b/docs/Usage.md index c8f7dc3f..f850605f 100644 --- a/docs/Usage.md +++ b/docs/Usage.md @@ -1,6 +1,6 @@ # Devilbox Documentation -[Overview](README.d) | +[Overview](README.md) | [Quickstart](Quickstart.md) | [Install](Install.md) | [Update](Update.md) | @@ -23,24 +23,24 @@ Usage | 2. [As root user](#2-2-as-root-user) 3. [Available tools](#2-3-available-tools) 4. [Available URLs](#2-4-available-urls) -3. [Creating new Projects](#3-creating-new-projects) - 1. [How does it work?](#3-1-) - 2. [Directory structure explained](#3-2-) - 3. [Creating new Projects](#3-3-) - 1. [From Docker Host](#3-3-1-) - 2. [From inside the PHP container](#3-3-2-) - 3. [Using symlinks](#3-3-3-) - 4. [Adding DNS records](#3-4-) - 1. [/etc/hosts](#3-4-1-) - 2. [Auto-DNS](#3-4-2-) -4. [Switching container versions](#5-switching-container-versions) +3. [Managing Projects explained](#3-managing-projects-explained) + 1. [How does it work?](#3-1-how-does-it-work-) + 2. [Directory structure explained](#3-2-directory-structure-explained) +4. [Creating new Projects](#4-creating-new-projetcs) + 1. [From Docker Host](#4-1-from-docker-host) + 2. [From inside the PHP container](#4-2-from-inside-the-php-container) + 3. [Using symlinks](#4-3-using-symlinks) + 4. [Adding DNS records](#4-4-adding-dns-record) + 1. [/etc/hosts](#4-4-1-etc-hosts) + 2. [Auto-DNS](#4-4-2-auto-dns) +5. [Switching container versions](#5-switching-container-versions) 1. [Httpd versions](#5-1-httpd-versions) 2. [PHP versions](#5-2-php-versions) 2. [SQL versions](#5-3-sql-versions) 3. [NoSQL versions](#5-4-nosql-versions) -5. [Emails](#6-emails) -6. [Log files](#7-log-files) -7. [Intranet](#8-intranet) +6. [Emails](#6-emails) +7. [Log files](#7-log-files) +8. [Intranet](#8-intranet) 1. [Overview](#8-1-overview) 2. [vHosts](#8-2-vhosts) 3. [Tools](#8-3-tools) @@ -132,7 +132,7 @@ Your projects will be available by the same URL as they are available from your For example, by doing `curl http://project1.dev` from either your host computer or from inside the PHP container will return the same URL. -## 3. Creating new Projects +## 3. Managing Projects explained [![Devilbox setup and workflow](img/devilbox_01-setup-and-workflow.png "devilbox - setup and workflow")](https://www.youtube.com/watch?v=reyZMyt2Zzo) #### 3.1 How does it work? @@ -175,9 +175,11 @@ In order to make the following examples easier let's work with some assumed defa The VirtualHost directory make a new VirtualHost available under the specified URL. However the actual files that will be served are always expected to be in a subfolder called `htdocs/`. By having an additional sub-directory for the Document root you are able to store non-www files inside the project folder and even **symlink** you www dir to htdocs. -#### 3.3 Creating new Projetcs +## 4. Creating new Projetcs -##### 3.3.1 From Docker host +This is a general overview about creating projects. If you want to see some real examples how to setup **Wordpress**, **Drupal**, **CakePHP**, **Yii**, **Symfony** and others, visit the [Example Section](Examples.md). + +#### 4.1 From Docker host The following will create a VirtualHost for `http://project1.local`. @@ -190,7 +192,7 @@ $ mkdir project1/htdocs If you want to know how to change the TLD_SUFFIX `local` to something else, refer to [Configure](Configure.md). -##### 3.3.2 From inside the PHP container +#### 4.2 From inside the PHP container If you prefer to work directly inside the PHP Docker container, you can do the same. The following will create a VirtualHost for `http://project1.local`. @@ -202,7 +204,7 @@ $ mkdir project1/htdocs If you want to know how to go into the PHP container, check the section above **2. Work inside the PHP container**. -##### 3.3.3 Using symlinks +#### 4.3 Using symlinks Instead of creating a **htdocs/** folder explicitly, you can also make a symlink by the same name. This is required as some frameworks have nested www folders. @@ -220,11 +222,11 @@ drwxrwxr-x 2 cytopia 4096 Jun 14 08:29 cakephp lrwxrwxrwx 1 cytopia 11 Jun 14 08:29 htdocs -> cakephp/app/webroot/ ``` -#### 3.4 Adding DNS record +#### 4.4 Adding DNS record In order to actually visit the newly created project in your browser, there must be a DNS entry pointing to the webserver's listening IP address. This can either be done automatically by a DNS server or you can do it manually for each project by editing your `/etc/hosts` file every time you create a new project. -##### 3.4.1 /etc/hosts +##### 4.4.1 /etc/hosts If you have not setup Auto-DNS, you will need to create your own DNS records for every project. Let's assume your `TLD_SUFFIX` is set to `local`. @@ -235,23 +237,89 @@ If you have not setup Auto-DNS, you will need to create your own DNS records for | playground | `127.0.0.1 playground.local` | -##### 3.4.2 Auto-DNS +##### 4.4.2 Auto-DNS When using the devilbox built-in DNS server, there is nothing to do. DNS catch-all records for your `TLD_SUFFIX` exist and will always point to `127.0.0.1`. See [Configure](Configure.md) for how to setup Auto-DNS. -## 4. Switching container versions -#### 4.1 Httpd versions -#### 4.2 PHP versions -#### 4.3 SQL versions -#### 4.4 NoSQL versions +## 5. Switching container versions -## 5. Emails +Being able to combine all kinds of different container version is one of the main goals of the devilbox. Changing the versions is kept simple and consistent for all container. -## 5. Log files +1. Open the `.env` file in your favorite editor +2. Find the `*_SERVER=` block for the container to change the version +3. Comment all lines you do not want to activate +4. Uncomment the one line you want to use. +5. Restart the devilbox for the changes to take effect -## 6. Intranet -#### 6.1 Overview -#### 6.2 vHosts -#### 6.3 Tools +Be aware that if multiple lines are uncommented, the last one takes effect. +#### 5.1 Httpd versions + +1. Open the `.env` file in your favorite editor +2. Find the `HTTPD_SERVER=` block + +You can choose between Apache and Nginx in different version. All of them are configured to work the same, there is nothing to worry about when changing them. + + +#### 5.2 PHP versions + +1. Open the `.env` file in your favorite editor +2. Find the `PHP_SERVER=` block + +You can choose between different PHP versions and HHVM. + +**Important:** Keep in mind that if you have a custom php.ini config at `./cfg/php-*/`, it is only effective for one version. Custom php configurations are separted per version. + +#### 5.3 SQL versions + +1. Open the `.env` file in your favorite editor +2. Find the `MYSQL_SERVER=` or `PGSQL_SERVER=` block + +**Important:** Each version has a different data directory. This is a security precautions. Imagine you startup MySQL 5.5 for the first time. New databases will be created. Now you startup MySQL 8. All existing databases would be upgraded to work flawlessly with MySQL 8, however this is not downwards compatible. So by startup up MySQL 5.5 again, it would say the database is corrupt. + +#### 5.4 NoSQL versions + +1. Open the `.env` file in your favorite editor +2. Find the `MONGO_SERVER=`, 'MEMCD_SERVER=` or `REDIS_SERVER=` block + +There is nothing to pay attention to here. + +## 6. Emails + +All your projects can send emails to whatever recipient. You do not have to worry that they will actually being sent. Each PHP container runs a local postfix mailserver that intercepts all outgoing mails and puts them all in the local devilbox user mail account. + +In order to view sent emails open up the devilbox intranet http://localhost/mail.php. There you can also test email sending and verify that they really stay locally. + +## 7. Log files + +Log files are available on the Host system and separated per service version. See `./log/` (inside devilbox git directory) for all log files. + +## 8. Intranet + +The devilbox bundled intranet is not required for project management or creation, however it offers a few useful tools. + +#### 8.1 Overview + +The overview page presents you the current state of the running stack and any errors it might have encountered. + +http://localhost + +#### 8.2 vHosts + +The vHost page shows you all available projects and any configuation errors that need to be resolved. Errors could be: missing `htdocs/` folder and incorrect DNS settings. So make sure to first visit this page if any of your vHost does not work. + +http://localhost/vhosts.php + +#### 8.3 Tools + +The intranet also offers a few common as well as self-made tools. These include: + +* phpMyAdmin +* Adminer +* Mail viewer +* OpCacheGUI +* SQL/NoSQL database viewer +* Info pages (showing detailed configurations for the attached container) + +If you are interested in doing database backups, either use phpMyAdmin or Adminer. You can however also use the PHP container itself. Read more about this on [Backups](Backups.md)