ExternalVendorCode/devilbox
1
0
Fork 0
mirror of https://github.com/cytopia/devilbox.git synced 2025-04-08 03:24:15 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

DVL-016 Documentation Intro page

Browse Source
This commit is contained in:
cytopia 2017-06-08 09:25:03 +02:00
parent a8c1513bb7
commit d70879ea9e
No known key found for this signature in database
GPG Key ID: 6D56EDB8695128A2
11 changed files with 144 additions and 762 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
docs/Configuration.md
View File

@ -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 `<SERVICE_NAME>_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 `<SERVICE>-<VERSION>`.
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.<ext>-example
```
Only files which have the correct file extensions will be read, all others such as `*.<ext>-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.

23
docs/Emails.md
View File

@ -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.

28
docs/Examples.md Normal file
View File

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

22
docs/FAQ.md
View File

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

73
docs/Info.md
View File

@ -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
<?php
mysql_connect('127.0.0.1', 'user', 'pass');
```
This setup can then either be served by the docker or by your host computer (if you shutdown docker and start your local lamp stack)

18
docs/Intranet.md
View File

@ -1,18 +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](Emails.md) |
[Logs](Logs.md) |
Intranet |
[FAQ](FAQ.md)
----
## Intranet

58
docs/Logs.md
View File

@ -1,58 +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](Emails.md) |
Logs |
[Intranet](Intranet.md) |
[FAQ](FAQ.md)
----
## Logs
Log information is available in two forms.
1. Mounted log directories
2. Docker logs
### Mounted log directories
Inside the devilbox directory you will find a folder `log/`.
This itself will contain subdirectories in the form `<service>-<version>` 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.

120
docs/PHP_Projects.md
View File

@ -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
<?php
echo 'hello world';
?>
```
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/<user>/<some-project>
# Symlink the project to htdocs
$ ln -s <some-project> htdocs
$ ls -l
drwxr-xr-x 4 cytopia 1286676289 136 Oct 30 14:24 <some-project>/
lrwxr-xr-x 1 cytopia 1286676289 549 Nov 6 15:13 htdocs -> <some-project>/
```
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
```

319
docs/README.md
View File

@ -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)
<p class="center">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.</p>
---
<img src="img/devilbox-dash.png" alt="Devilbox" style="max-width:100%"/>
### 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] |
<p class="center">Don't worry about switching computers. The devilbox will run on all major operating systems.</p>
**Note:** There is also the deprecated [Docker Toolbox][dtb] (for Windows and OSX). It is however not recommended to use with the devilbox.
<div class="center">
<img class="battery" style="height:64px;" title="Linux support" alt="Linux support" src="https://raw.githubusercontent.com/cytopia/icons/master/64x64/linux.png" />
<img class="battery" style="height:64px;" title="OSX support" alt="OSX support" src="https://raw.githubusercontent.com/cytopia/icons/master/64x64/osx.png" />
<img class="battery" style="height:64px;" title="Windows support" alt="Windows support" src="https://raw.githubusercontent.com/cytopia/icons/master/64x64/windows.png" />
</div>
[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
<p class="center">Your whole development stack is up and running in a few simple steps.</p>
* [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
<p class="center">Choose your required daemons and select a version. Any combination is possible.<br/>This will allow you, to always exactly simulate your production environment locally during development.</p>
| 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 |
<table>
<thead>
<tr>
<th>Apache</th>
<th>Nginx</th>
<th>PHP</th>
<th>MySQL</th>
<th>MariaDB</th>
<th>PgSQL</th>
<th>Redis</th>
<th>Memcached</th>
<th>MongoDB</th>
</tr>
</thead>
<tbody>
<tr>
<td><a target="_blank" title="Apache 2.2" href="https://github.com/cytopia/docker-apache-2.2">2.2</a></td>
<td><a target="_blank" title="Nginx stable" href="https://github.com/cytopia/docker-nginx-stable">stable</a></td>
<td><a target="_blank" title="PHP 5.4" href="https://github.com/cytopia/docker-php-fpm-5.4">5.4</a></td>
<td><a target="_blank" title="MySQL 5.5" href="https://github.com/cytopia/docker-mysql-5.5">5.5</a></td>
<td><a target="_blank" title="MariaDB 5.5" href="https://github.com/cytopia/docker-mariadb-5.5">5.5</a></td>
<td><a target="_blank" title="PgSQL 9.1" href="https://github.com/docker-library/postgres">9.1</a></td>
<td><a target="_blank" title="Redis 2.8" href="https://github.com/docker-library/redis">2.8</a></td>
<td><a target="_blank" title="Memcached 1.4.21" href="https://github.com/docker-library/memcached">1.4.21</a></td>
<td><a target="_blank" title="MongoDB 2.8" href="https://github.com/docker-library/mongo">2.8</a></td>
</tr>
<tr>
<td><a target="_blank" title="Apache 2.4" href="https://github.com/cytopia/docker-apache-2.4">2.4</a></td>
<td><a target="_blank" title="Nginx mainline" href="https://github.com/cytopia/docker-nginx-mainline">mainline</a></td>
<td><a target="_blank" title="PHP 5.5" href="https://github.com/cytopia/docker-php-fpm-5.5">5.5</a></td>
<td><a target="_blank" title="MySQL 5.6" href="https://github.com/cytopia/docker-mysql-5.6">5.6</a></td>
<td><a target="_blank" title="MariaDB 10.0" href="https://github.com/cytopia/docker-mariadb-10.0">10.0</a></td>
<td><a target="_blank" title="PgSQL 9.2" href="https://github.com/docker-library/postgres">9.2</a></td>
<td><a target="_blank" title="Redis 3.0" href="https://github.com/docker-library/redis">3.0</a></td>
<td><a target="_blank" title="Memcached 1.4.22" href="https://github.com/docker-library/memcached">1.4.22</a></td>
<td><a target="_blank" title="MongoDB 3.0" href="https://github.com/docker-library/mongo">3.0</a></td>
</tr>
<tr>
<td></td>
<td></td>
<td><a target="_blank" title="PHP 5.6" href="https://github.com/cytopia/docker-php-fpm-5.6">5.6</a></td>
<td><a target="_blank" title="MySQL 5.7" href="https://github.com/cytopia/docker-mysql-5.7">5.7</a></td>
<td><a target="_blank" title="MariaDB 10.1" href="https://github.com/cytopia/docker-mariadb-10.1">10.1</a></td>
<td><a target="_blank" title="PgSQL 9.3" href="https://github.com/docker-library/postgres">9.3</a></td>
<td><a target="_blank" title="Redis 3.2" href="https://github.com/docker-library/redis">3.2</a></td>
<td><a target="_blank" title="Memcached 1.4.23" href="https://github.com/docker-library/memcached">1.4.23</a></td>
<td><a target="_blank" title="MongoDB 3.2" href="https://github.com/docker-library/mongo">3.2</a></td>
</tr>
<tr>
<td></td>
<td></td>
<td><a target="_blank" title="PHP 7.0" href="https://github.com/cytopia/docker-php-fpm-7.0">7.0</a></td>
<td><a target="_blank" title="MySQL 8.0" href="https://github.com/cytopia/docker-mysql-8.0">8.0</a></td>
<td><a target="_blank" title="MariaDB 10.2" href="https://github.com/cytopia/docker-mariadb-10.2">10.2</a></td>
<td><a target="_blank" title="PgSQL 9.4" href="https://github.com/docker-library/postgres">9.4</a></td>
<td></td>
<td>...</td>
<td><a target="_blank" title="MongoDB 3.4" href="https://github.com/docker-library/mongo">3.4</a></td>
</tr>
<tr>
<td></td>
<td></td>
<td><a target="_blank" title="PHP 7.1" href="https://github.com/cytopia/docker-php-fpm-7.1">7.1</a></td>
<td></td>
<td><a target="_blank" title="MariaDB 10.3" href="https://github.com/cytopia/docker-mariadb-10.3">10.3</a></td>
<td><a target="_blank" title="PgSQL 9.5" href="https://github.com/docker-library/postgres">9.5</a></td>
<td></td>
<td><a target="_blank" title="Memcached 1.4.36" href="https://github.com/docker-library/memcached">1.4.36</a></td>
<td><a target="_blank" title="MongoDB 3.5" href="https://github.com/docker-library/mongo">3.5</a></td>
</tr>
<tr>
<td></td>
<td></td>
<td><a target="_blank" title="HHVM" href="https://github.com/cytopia/docker-hhvm-latest">HHVM</a></td>
<td></td>
<td></td>
<td><a target="_blank" title="PgSQL 9.6" href="https://github.com/docker-library/postgres">9.6</a></td>
<td></td>
<td><a target="_blank" title="Memcached latest" href="https://github.com/docker-library/memcached">latest</a></td>
<td></td>
</tr>
</tbody>
</table>
### 5. Video Tutorials
### Run only what you need
Have a look at youtube to see all the features in action.
<p class="center">You are not forced to load the whole stack everytime. Only bring up what you really need.<br/>It is also possible to add or remove daemons while the stack is already running.</p>
[![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
<p class="center">Head over to youtube for a quick introduction and see for yourself how easily new projects can be created.</p>
<div class="center">
<a target="_blank" href="https://www.youtube.com/watch?v=reyZMyt2Zzo" alt="Devilbox introduction video" title="Devilbox introduction video"><img src="img/devilbox_01-setup-and-workflow.png" /></a>
<a target="_blank" href="https://www.youtube.com/watch?v=e-U-C5WhxGY" alt="Devilbox Email catch-all introduction" title="Devilbox Email catch-all introduction"><img src="img/devilbox_02-email-catch-all.png" /></a>
</div>
### PHP Modules
<div class="center">
<p>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:</p>
<img class="battery" style="height:64px;" title="PHP" alt="PHP" src="img/logos/php.png" />
<img class="battery" style="height:64px;" title="HHVM" alt="HHVM" src="img/logos/hhvm.png" />
<p>
<strong><a target="_blank" title="PHP 5.4" href="https://github.com/cytopia/docker-php-fpm-5.4">PHP 5.4</a></strong> |
<strong><a target="_blank" title="PHP 5.5" href="https://github.com/cytopia/docker-php-fpm-5.5">PHP 5.5</a></strong> |
<strong><a target="_blank" title="PHP 5.6" href="https://github.com/cytopia/docker-php-fpm-5.5">PHP 5.6</a></strong> |
<strong><a target="_blank" title="PHP 7.0" href="https://github.com/cytopia/docker-php-fpm-5.5">PHP 7.0</a></strong> |
<strong><a target="_blank" title="PHP 7.1" href="https://github.com/cytopia/docker-php-fpm-5.5">PHP 7.1</a></strong> |
<strong><a target="_blank" title="HHVM" href="https://github.com/cytopia/docker-hhvm-latest">HHVM</a></strong>
</p>
<p>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</p>
</div>
### Email catch-all
<div class="center">
<img class="battery" style="height:64px;" title="Email catch-all" alt="Email catch-all" src="img/logos/email.png"/>
<p>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.</p>
</div>
### Auto-DNS
<div class="center">
<img class="battery" style="height:64px;" title="Auto-DNS" alt="Auto-DNS" src="img/logos/dns.png" />
<p>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.</p>
</div>
### Batteries included
<p class="center">No need to download external tools. Everything is bundled, up-to-date and available inside the containers.</p>
<div class="center">
<a target="_blank" title="phpMyAdmin" href="https://www.phpmyadmin.net"><img class="battery" style="height:64px;" src="img/logos/phpmyadmin.png" alt="Devilbox"/></a>
<a target="_blank" title="Adminer" href="https://www.adminer.org"><img class="battery" style="height:64px;" src="img/logos/adminer.png" alt="Devilbox"/></a>
<a target="_blank" title="OpCache GUI" href="https://github.com/amnuts/opcache-gui"><img class="battery" style="height:64px;" src="img/logos/opcachegui.png" alt="Devilbox"/></a>
<br/>
<a target="_blank" title="Composer" href="https://getcomposer.org"><img class="battery" style="height:64px;" src="img/logos/composer.png" alt="Devilbox"/></a>
<a target="_blank" title="Drush" href="https://www.drupal.org/project/drush"><img class="battery" style="height:64px;" src="img/logos/drush.png" alt="Devilbox"/></a>
<a target="_blank" title="Drupal Console" href="https://drupalconsole.com"><img class="battery" style="height:64px;" src="img/logos/drupal-console.png" alt="Devilbox"/></a>
<a target="_blank" title="NodeJS" href="https://nodejs.org"><img class="battery" style="height:64px;" src="img/logos/nodejs.png" alt="Devilbox"/></a>
<a target="_blank" title="WP-CLI" href="https://wp-cli.org"><img class="battery" style="height:64px;" src="img/logos/wp-cli.png" alt="Devilbox"/></a>
<a target="_blank" title="NPM" href="https://www.npmjs.com"><img class="battery" style="height:64px;" src="img/logos/npm.png" alt="Devilbox"/></a>
<a target="_blank" title="Git" href="https://git-scm.com"><img class="battery" style="height:64px;" src="img/logos/git.png" alt="Devilbox"/></a>
</div>
### Supported Frameworks and CMS
<p class="center">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.</p>
<div class="center">
<a target="_blank" title="CakePHP" href="https://cakephp.org" ><img alt="CakePHP" class="battery" style="height:64px;" src="img/logos/cake.png" /></a>
<a target="_blank" title="Drupal" href="https://www.drupal.org/" ><img alt="Drupal" class="battery" style="height:64px;" src="img/logos/drupal.png" /></a>
<a target="_blank" title="PhalconPHP" href="https://phalconphp.com" ><img alt="PhalconPHP" class="battery" style="height:64px;" src="img/logos/phalcon.png" /></a>
<a target="_blank" title="Wordpress" href="https://wordpress.org" ><img alt="Wordpress" class="battery" style="height:64px;" src="img/logos/wordpress.png" /></a>
<a target="_blank" title="Yii" href="http://www.yiiframework.com" ><img alt="Yii" class="battery" style="height:64px;" src="img/logos/yii.png" /></a>
</div>
### Devilbox Intranet
<p class="center">Once the devilbox is up and running, you can visit the bundled intranet on <a target="_blank" href="http://localhost">http://localhost</a>.<br/>The intranet is not just a simple dash, it provides many useful tools:</p>
<div class="center">
Container Health | DNS Status | Available vHosts | Emails | Databases | Effective Configuration<br/>
<img alt="" title="" src="img/02_intranet_vhosts.png "/>
<img alt="" title="" src="img/04_intranet_emails.png "/>
</div>
### Security
<p class="center">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 <a target="_blank" href="https://github.com/cytopia/devilbox#run-time-matrix">Github</a> and can be reviewed at any time.</p>
### Up-to-dateness
<p class="center">Docker containers are pushed to <a target="_blank" href="https://hub.docker.com/r/cytopia">Docker Hub</a> frequently.<br/>It should be enough for you to pull updated images on a regeular basis.</p>
```shell
$ docker-compose pull
```
<p class="center">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.</p>
```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
<div class="center">
<a target="_blank" href="https://travis-ci.org/cytopia/devilbox"><img src="https://travis-ci.org/cytopia/devilbox.svg?branch=master" /></a>
</div>
<p class="center">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 <a target="_blank" href="https://travis-ci.org/cytopia/devilbox">Travis-CI</a> and have a look at stable and nightly builds.</p>
### Contribute
<div class="center">
<p>Contributers are welcome in any way.</p>
<p>First of all, if you like the project, please <a href="https://github.com/cytopia/devilbox">do star it</a>. 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.</p>
<p>You can also get actively involved. <a href="https://github.com/cytopia/devilbox">Do clone the project</a> and start improving whatever you think is useful. There is quite a lot todo and planned. If you like to contribute, view <a href="https://github.com/cytopia/devilbox/blob/master/CONTRIBUTING.md">CONTRIBUTING.md</a> and <a href="https://github.com/cytopia/devilbox/issues/23">ROADMAP</a>.</p>
<p>Major contributors will be credited within the intranet and on the github page.</p>
</div>
### License
<div class="center">
<p>MIT License</p>
<p>Copyright (c) 2016 cytopia</p>
</div>

68
docs/Updating.md
View File

@ -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 <tag>
# 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
```

63
docs/Usage.md
View File

@ -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.