ExternalVendorCode/devilbox
1
0
Fork 0
mirror of https://github.com/cytopia/devilbox.git synced 2025-03-14 16:26:41 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

DVL-16 Finalized doc structure

Browse Source
This commit is contained in:
cytopia 2017-06-11 15:16:01 +02:00
parent 4b8889bef9
commit 40401dda85
No known key found for this signature in database
GPG Key ID: 6D56EDB8695128A2
11 changed files with 424 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
docs/Backups.md Normal file
View File

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

23
docs/Configure.md Normal file
View File

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

7
docs/Examples.md
View File

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

7
docs/FAQ.md
View File

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

7
docs/Hacking.md
View File

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

81
docs/Install.md Normal file
View File

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

31
docs/README.md
View File

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

17
docs/Run.md
View File

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

7
docs/Technical.md
View File

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

116
docs/Update.md Normal file
View File

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

156
docs/Usage.md
View File

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