ExternalVendorCode/devilbox
1
0
Fork 0
mirror of https://github.com/cytopia/devilbox.git synced 2025-02-21 17:56:44 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

DVL-016 Usage documentation

Browse Source
This commit is contained in:
cytopia 2017-06-14 09:25:57 +02:00
parent 1fb4a4a53b
commit f435fac2a0
No known key found for this signature in database
GPG Key ID: 6D56EDB8695128A2
13 changed files with 653 additions and 189 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
docs/Backups.md
View File

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

74
docs/Configure.md
View File

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

29
docs/Examples.md
View File

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

23
docs/FAQ.md
View File

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

29
docs/Hacking.md
View File

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

27
docs/Install.md
View File

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

130
docs/Quickstart.md Normal file
View File

@ -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 |
|-----------------------|-----------------------------|------------------------|
| <code>./data/www/<b>project1</b></code> | <code>./data/www/project1/<b>htdocs</b></code> | `http://project1.local` |
| <code>./data/www/<b>project2</b></code> | <code>./data/www/project2/<b>htdocs</b></code> | `http://project2.local` |
| <code>./data/www/<b>wordpress</b></code>| <code>./data/www/wordpress/<b>htdocs</b></code> | `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/
```

86
docs/README.md
View File

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

31
docs/Run.md
View File

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

29
docs/Technical.md
View File

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

68
docs/Update.md
View File

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

188
docs/Usage.md
View File

@ -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 <command>
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 |
|-----------------------|-----------------------------|------------------------|
| <code>./data/www/<b>project1</b></code> | <code>./data/www/project1/<b>htdocs</b></code> | `http://project1.local` |
| <code>./data/www/<b>project2</b></code> | <code>./data/www/project2/<b>htdocs</b></code> | `http://project2.local` |
| <code>./data/www/<b>wordpress</b></code>| <code>./data/www/wordpress/<b>htdocs</b></code> | `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
```
<sub>If you want to know how to change the TLD_SUFFIX `local` to something else, refer to [Configure](Configure.md).</sub>
##### 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
```
<sub>If you want to know how to go into the PHP container, check the section above **2. Work inside the PHP container**.</sub>
##### 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

101
update-docker.sh Executable file
View File

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