ExternalVendorCode/devilbox
1
0
Fork 0
mirror of https://github.com/cytopia/devilbox.git synced 2025-02-20 09:26:36 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Documentation: Update legacy docs

Browse Source
This commit is contained in:
cytopia 2018-04-11 08:43:15 +02:00
parent 2b1dc0efc2
commit 76a825b887
No known key found for this signature in database
GPG Key ID: 6D56EDB8695128A2
14 changed files with 80 additions and 3024 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

375
docs/Backups.md
View File

@ -1,374 +1,7 @@
# Devilbox Documentation
[Overview](README.md) |
[Quickstart](Quickstart.md) |
[Install](Install.md) |
[Update](Update.md) |
[Configure](Configure.md) |
[Run](Run.md) |
[Usage](Usage.md) |
[OS](OS.md) |
Backups |
[Examples](Examples.md) |
[Technical](Technical.md) |
[Hacking](Hacking.md) |
[FAQ](FAQ.md)
#### Devilbox documentation has moved to [devilbox.readthedocs.io](https://devilbox.readthedocs.io)
---
## Backups
1. [Info](#1-info)
2. [MySQL](#2-mysql)
1. [MySQL Database Backup](#21-mysql-database-backup)
1. [mysqldump-secure](#211-mysqldump-secure)
2. [mysqldump](#212-mysqldump)
3. [phpMyAdmin](#213-phpmyadmin)
4. [Adminer](#214-adminer)
2. [MySQL Database Restore](#22-mysql-database-restore)
1. [mysql](#221-mysql)
2. [phpMyAdmin](#222-phpmyadmin)
3. [Adminer](#223-adminer)
3. [PostgreSQL](#3-postgresql)
1. [PostgreSQL Database Backup](#31-postgresql-database-backup)
1. [pg_dump](#311-pg_dump)
2. [Adminer](#312-adminer)
2. [PostgreSQL Database Restore](#32-postgresql-database-restore)
1. [psql](#321-psql)
2. [Adminer](#322-adminer)
4. [MongoDB](#4-mongodb)
1. [MongoDB Database Backup](#41-mongodb-database-backup)
1. [mongodump](#411-mongodump)
2. [MongoDB Database Restore](#42-mongodb-database-restore)
1. [mongorestore](#421-mongorestore)
---
## 1. Info
Backup and restore will be necessary when you are going to change MySQL, PostgreSQL or MongoDB versions. Each version has its own data directory and different versions do not pick up the databases from another version.
**Example**
```
./data/mysql/mysql-5.5
./data/mysql/mysql-5.7
./data/mysql/mariadb-10.1
./data/pgsql/9.5
./data/pgsql/9.6
./data/mongo/3.2
./data/mongo/3.4
```
This is necessary as later MySQL, PostgreSQL and MongoDB versions will upgrade the databases making it unusable for older versions.
So before you change to a new database version you will have to make a backup and restore the backup in the new version.
If you use the devilbox bundled tools, you will find all backups in the main directory under `./backups/`.
## 2. MySQL
#### 2.1 MySQL Database Backup
There are many different options to backup your MySQL database including some for the command line and some for using the Web interface. The recommended and fastest method is to use mysqldump-secure, as it will also add info files (`*.info`) to each database recording checksums, dump date, dump options and from which version the backup come from.
##### 2.1.1 mysqldump-secure
**[mysqldump-secure](https://mysqldump-secure.org)** is bundled, setup and ready to use in every PHP/HHVM container. You can run it without any arguments and it will dump each available database as a separated compressed file. Backups will be located in `./backups/mysql/` on the Docker host or in `/shared/backups/mysql/` inside the Docker container.
```shell
# Enter the Container
host> ./shell.sh
# Start the backup
devilbox@php-7.1.6 in /shared/httpd $ mysqldump-secure
[INFO] (OPT): Logging enabled
[INFO] (OPT): MySQL SSL connection disabled
[INFO] (OPT): Compression enabled
[INFO] (OPT): Encryption disabled
[INFO] (OPT): Deletion disabled
[INFO] (OPT): Nagios log disabled
[INFO] (OPT): Info files enabled
[INFO] (SQL): 1/3 Skipping: information_schema (DB is ignored)
[INFO] (SQL): 2/3 Dumping: mysql (0.66 MB) 1 sec (0.13 MB)
[INFO] (SQL): 3/3 Skipping: performance_schema (DB is ignored)
[OK] Finished successfully
# List backups inside the container
devilbox@php-7.1.6 in /shared/httpd $ ls -l /shared/backups/mysql/
-rw-r--r-- 1 devilbox 136751 Jun 17 13:31 2017-06-17_13-31__mysql.sql.gz
-rw-r--r-- 1 devilbox 2269 Jun 17 13:31 2017-06-17_13-31__mysql.sql.gz.info
# Quit the docker container
devilbox@php-7.1.6 in /shared/httpd $ exit
# List backups on your hostsystem (from devilbox root directory)
host> ls -l backups/mysql/
-rw-r--r-- 1 cytopia 136751 Jun 17 13:31 2017-06-17_13-31__mysql.sql.gz
-rw-r--r-- 1 cytopia 2269 Jun 17 13:31 2017-06-17_13-31__mysql.sql.gz.info
```
The `*.info` file will hold many useful information in case you need to debug any problems occured during backups.
```shell
$ cat ./backups/mysql/2017-06-17_13-31__mysql.sql.gz.info
```
```ini
; mysqldump-secure backup record
; Do not alter this file!
; Creation of this file can be turned off via config file.
; ============================================================
; = Local system information
; ============================================================
[mysqldump-secure]
version = /usr/local/bin/mysqldump-secure (0.16.3)
vdate = 2016-08-18
config = /etc/mysqldump-secure.conf
[system]
uname = Linux 4.4.0-79-generic
hostname =
user = devilbox
group = devilbox
[tools]
mysqldump = /usr/bin/mysqldump (10.14 Distrib 5.5.52-MariaDB) [for Linux (x86_64)]
mysql = /usr/bin/mysql (15.1 Distrib 5.5.52-MariaDB) [for Linux (x86_64) using readline 5.1]
compressor = /usr/bin/gzip (gzip 1.5)
encryptor = Not used
; ============================================================
; = Database / File information
; ============================================================
[database]
db_name = mysql
db_size = 687326 Bytes (0.66 MB)
tbl_cnt = 30
[file]
file_path = /shared/backups/mysql
file_name = 2017-06-17_13-31__mysql.sql.gz
file_size = 136751 Bytes (0.13 MB)
file_chmod = 0644
file_owner = devilbox
file_group = devilbox
file_mtime = 1497699116 (2017-06-17 13:31:56 CEST [+0200])
file_md5 = 8d1a6c38f81c691bc4b490e7024a4f72
file_sha = 11fb85282ea866dfc69d29dc02a0418bebfea30e7e566c3c588a50987aceac2f
; ============================================================
; = Dump procedure information
; ============================================================
[mysqldump]
encrypted = 0
compressed = 1
arguments = --opt --default-character-set=utf8 --events --triggers --routines --hex-blob --complete-insert --extended-insert --compress --lock-tables --skip-quick
duration = 1 sec
[compression]
compressor = gzip
arguments = -9 --stdout
[encryption]
encryptor =
algorithm =
pubkey =
; ============================================================
; = Server information
; ============================================================
[connection]
protocol = mysql via TCP/IP
secured = No SSL
arguments = --defaults-file=/etc/mysqldump-secure.cnf
[server]
hostname = 001b3750b549
port = 3306
replica = master
version = MariaDB 10.1.23-MariaDB MariaDB Server
```
You can alternatively also execute it directly from your host computer. For that to work, you must be inside the devilbox root directory.
```shell
$ docker-compose exec --user devilbox php mysqldump-secure
```
To find out more about the configuration and options of mysqldump-secure, visit its project page under: [https://mysqldump-secure.org](https://mysqldump-secure.org).
##### 2.1.2 mysqldump
**[mysqldump](https://dev.mysql.com/doc/refman/5.7/en/mysqldump.html)** is bundled with each PHP/HHVM container and ready to use. To backup a database named `my_db_name` follow the below listed example:
```shell
# Enter the Container
host> ./shell.sh
# Start the backup
devilbox@php-7.1.6 in /shared/httpd $ mysqldump -h mysql -u root -p my_db_name > /shared/backups/mysql/my_db_name.sql
```
To find out more about the configuration and options of mysqldump, visit its project page under: [https://dev.mysql.com/doc/refman/5.7/en/mysqldump.html](https://dev.mysql.com/doc/refman/5.7/en/mysqldump.html).
##### 2.1.3 phpMyAdmin
If you do not like to use the command line for backups, you can use **[phpMyAdmin](https://www.phpmyadmin.net)**. It comes bundled with the devilbox intranet. View [Usage](Usage.md) to read more about the devilbox intranet.
To find out more about the usage of phpMyAdmin, visit its project page under: [https://www.phpmyadmin.net](https://www.phpmyadmin.net).
##### 2.1.4 Adminer
If you do not like to use the command line for backups, you can use **[Adminer](https://www.adminer.org)**. It comes bundled with the devilbox intranet. View [Usage](Usage.md) to read more about the devilbox intranet.
To find out more about the usage of Adminer, visit its project page under: [https://www.adminer.org](https://www.adminer.org).
#### 2.2 MySQL Database Restore
##### 2.2.1 mysql
In order to restore or import mysql databases on the command line, you need to use `mysql`. Here are a few examples for different file types:
###### 2.2.1.1 `*.sql` files
```shell
# Enter the Container
host> ./shell.sh
# Start the import
devilbox@php-7.1.6 in /shared/httpd $ mysql -h mysql -u root -p my_db_name < /shared/backups/mysql/my_db_name.sql
```
###### 2.2.1.2 `*.sql.gz` files
```shell
# Enter the Container
host> ./shell.sh
# Start the import
devilbox@php-7.1.6 in /shared/httpd $ zcat /shared/backups/mysql/my_db_name.sql.gz | mysql -h mysql -u root -p my_db_name
```
###### 2.2.1.3 `*.sql.tar.gz` files
```shell
# Enter the Container
host> ./shell.sh
# Start the import
devilbox@php-7.1.6 in /shared/httpd $ tar xzOf /shared/backups/mysql/my_db_name.sql.tar.gz | mysql -h mysql -u root -p my_db_name
```
##### 2.2.2 phpMyAdmin
**[phpMyAdmin](https://www.phpmyadmin.net)** supports importing of many different formats out-of-the-box. Simply select the compressed or uncompressed file and press `Go` in the Web interface.
##### 2.2.3 Adminer
**[Adminer](https://www.adminer.org)** supports importing of plain (`*.sql`) or gzipped compressed (`*.sql.gz`) files out-of-the-box. Simply select the compressed or uncompressed file and press `Execute` in the Web interface.
## 3. PostgreSQL
#### 3.1 PostgreSQL Database Backup
##### 3.1.1 pg_dump
**[pg_dump](https://www.postgresql.org/docs/current/static/backup-dump.html)** is bundled with each PHP/HHVM container and ready to use. To backup a database named `my_db_name` follow the below listed example:
```shell
# Enter the Container
host> ./shell.sh
# Start the import
devilbox@php-7.1.6 in /shared/httpd $ pg_dump -h pgsql -U postgres -W my_db_name > /shared/backups/pgsql/my_db_name.sql
```
To find out more about the configuration and options of pg_dump, visit its project page under: [https://www.postgresql.org/docs/current/static/backup-dump.html](https://www.postgresql.org/docs/current/static/backup-dump.html#BACKUP-DUMP).
##### 3.1.2 Adminer
If you do not like to use the command line for backups, you can use **[Adminer](https://www.adminer.org)**. It comes bundled with the devilbox intranet. View [Usage](Usage.md) to read more about the devilbox intranet.
To find out more about the usage of Adminer, visit its project page under: [https://www.adminer.org](https://www.adminer.org).
#### 3.2 PostgreSQL Database Restore
##### 3.2.1 psql
In order to restore or import PostgreSQL databases on the command line, you need to use **[psql](https://www.postgresql.org/docs/current/static/backup-dump.html#BACKUP-DUMP-RESTORE)**. Here are a few examples for different file types:
###### 3.2.1.1 `*.sql` files
```shell
# Enter the Container
host> ./shell.sh
# Start the import
devilbox@php-7.1.6 in /shared/httpd $ psql -h pgsql -U postgres -W my_db_name < /shared/backups/pgsql/my_db_name.sql
```
###### 3.2.1.2 `*.sql.gz` files
```shell
# Enter the Container
host> ./shell.sh
# Start the import
devilbox@php-7.1.6 in /shared/httpd $ zcat /shared/backups/pgsql/my_db_name.sql.gz | psql -h pgsql -U postgres -W my_db_name
```
###### 3.2.1.3 `*.sql.tar.gz` files
```shell
# Enter the Container
host> ./shell.sh
# Start the import
devilbox@php-7.1.6 in /shared/httpd $ tar xzOf /shared/backups/pgsql/my_db_name.sql.tar.gz | psql -h pgsql -U postgres -W my_db_name
```
##### 3.2.2 Adminer
**[Adminer](https://www.adminer.org)** supports importing of plain (`*.sql`) or gzipped compressed (`*.sql.gz`) files out-of-the-box. Simply select the compressed or uncompressed file and press `Execute` in the Web interface.
## 4. MongoDB
#### 4.1 MongoDB Database Backup
##### 4.1.1 mongodump
**[mongodump](https://docs.mongodb.com/manual/reference/program/mongodump/)** is bundled with each PHP/HHVM container and ready to use. To backup all MongoDB databases follow the below listed example:
```shell
# Enter the Container
host> ./shell.sh
# Start the dump into /shared/backups/mongo
devilbox@php-7.1.6 in /shared/httpd $ mongodump --out /shared/backups/mongo
```
To find out more about the configuration and options of mongodump, visit its project page under: [https://docs.mongodb.com/manual/reference/program/mongodump/](https://docs.mongodb.com/manual/reference/program/mongodump/).
#### 4.2 MongoDB Database Restore
##### 4.2.1 mongorestore
**[mongorestore](https://docs.mongodb.com/manual/reference/program/mongorestore/)** is bundled with each PHP/HHVM container and ready to use. To restore all MongoDB databases follow the below listed example:
```shell
# Enter the Container
host> ./shell.sh
# Start the restore/import from /shared/backups/mongo
devilbox@php-7.1.6 in /shared/httpd $ mongorestore /shared/backups/mongo
```
To find out more about the configuration and options of mongorestore, visit its project page under: [https://docs.mongodb.com/manual/reference/program/mongorestore/](https://docs.mongodb.com/manual/reference/program/mongorestore/).
<a href="https://devilbox.readthedocs.io" title="Devilbox Documentation">
<img style="width:200px;height:200px;" widh="200" height="200" title="Devilbox Documentation" name="Devilbox Documentation" src="https://raw.githubusercontent.com/cytopia/icons/master/400x400/readthedocs.png" />
</a>

1030
docs/Configure.md
View File

File diff suppressed because it is too large Load Diff

7
docs/Examples.md Normal file
View File

@ -0,0 +1,7 @@
# Devilbox Documentation
#### Devilbox documentation has moved to [devilbox.readthedocs.io](https://devilbox.readthedocs.io)
<a href="https://devilbox.readthedocs.io" title="Devilbox Documentation">
<img style="width:200px;height:200px;" widh="200" height="200" title="Devilbox Documentation" name="Devilbox Documentation" src="https://raw.githubusercontent.com/cytopia/icons/master/400x400/readthedocs.png" />
</a>

208
docs/FAQ.md
View File

@ -1,207 +1,7 @@
# Devilbox Documentation
[Overview](README.md) |
[Quickstart](Quickstart.md) |
[Install](Install.md) |
[Update](Update.md) |
[Configure](Configure.md) |
[Run](Run.md) |
[Usage](Usage.md) |
[OS](OS.md) |
[Backups](Backups.md) |
[Examples](Examples.md) |
[Technical](Technical.md) |
[Hacking](Hacking.md) |
FAQ
#### Devilbox documentation has moved to [devilbox.readthedocs.io](https://devilbox.readthedocs.io)
---
## FAQ
1. **[General](#1-general)**
- [Are there any differences between Linux, Windows and OSX?](#are-there-any-differences-between-linux-windows-and-osx)
- [Why are mounted MySQL data directories separated by version?](#why-are-mounted-mysql-data-directories-separated-by-version)
- [Why are mounted PostgreSQL data directories separated by version?](#why-are-mounted-postgresql-data-directories-separated-by-version)
- [Why are mounted MongoDB data directories separated by version?](#why-are-mounted-mongodb-data-directories-separated-by-version)
- [Why do the user/group permissions of log/ or cfg/ directories show 1000?](#why-do-the-usergroup-permissions-of-log-or-cfg-directories-show-1000)
- [Can I not just comment out the service in the .env file?](#can-i-not-just-comment-out-the-service-in-the-env-file)
- [Are there any required services that must/will always be started?](#are-there-any-required-services-that-mustwill-always-be-started)
- [What PHP Modules are available?](#what-php-modules-are-available)
- [Can I load custom PHP modules without rebuilding the Docker container?](#can-i-load-custom-php-modules-without-rebuilding-the-docker-container)
2. **[Configuration](#2-configuration)**
- [Can I change the MySQL root password?](#can-i-change-the-mysql-root-password)
- [Can I add other PHP Modules?](#can-i-add-other-php-modules)
- [Can I change php.ini?](#can-i-change-phpini)
- [Can I change my.cnf?](#can-i-change-mycnf)
- [Can I switch HHVM between PHP 5.6 and PHP 7 mode?](#can-i-switch-hhvm-between-php-56-and-php-7-mode)
- [Can I change the project virtual host domain .loc?](#can-i-change-the-project-virtual-host-domain-loc)
- [Can I just start PHP and MySQL instead of all container?](#can-i-just-start-php-and-mysql-instead-of-all-container)
- [Do I always have to edit /etc/hosts for new projects?](#do-i-always-have-to-edit-etchosts-for-new-projects)
3. **[Usage](#3-usage)**
- [Does it work with CakePHP?](#does-it-work-with-cakephp)
- [Does it work with Drupal?](#does-it-work-with-drupal)
- [Does it work with Joomla?](#does-it-work-with-joomla)
- [Does it work with Laravel?](#does-it-work-with-laravel)
- [Does it work with PhalconPHP?](#does-it-work-with-phalconphp)
- [Does it work with Symfony?](#does-it-work-with-symfony)
- [Does it work with Wordpress?](#does-it-work-with-wordpress)
- [Does it work with Yii?](#does-it-work-with-yii)
- [Does it work with Zend Framework?](#does-it-work-with-zend-framework)
4. **[Troubleshooting](#4-troubleshooting)**
- [Invalid bind mount spec after changing the path of MySQL, PgSQL, Mongo or the Data dir.](#invalid-bind-mount-spec-after-changing-the-path-of-mysql-pgsql-mongo-or-the-data-dir)
---
## 1. General
#### Are there any differences between Linux, Windows and OSX?
Yes, have a look at **[OS](OS.md)** to read up about the differences.
#### Why are mounted MySQL data directories separated by version?
This is just a pre-caution. Imagine they would link to the same datadir. You start the devilbox with mysql 5.5, create a database and add some data. Now you decide to switch to mysql 5.7 and restart the devilbox. The newer mysql version will probably upgrade the data leaving it unable to start with older mysql versions.
#### Why are mounted PostgreSQL data directories separated by version?
See: *Why are mounted MySQL data directories separated by version?*
#### Why are mounted MongoDB data directories separated by version?
See: *Why are mounted MySQL data directories separated by version?*
#### Why do the user/group permissions of log/ or cfg/ directories show 1000?
Uid and Gid are set to 1000 by default. You can alter them to match the uid/gid of your current user. Open the `.env` file and change the sections `NEW_UID` and `NEW_GID`. When you start up the devilbox, the php-container will use these values for its user.
#### Can I not just comment out the service in the `.env` file?
No, don't do this. This will lead to unexpected behaviour (different versions will be loaded).
The `.env` file allows you to configure the devilbox, but not to start services selectively.
#### Are there any required services that must/will always be started?
Yes. `http` and `php` will automatically always be started (due to dependencies inside `docker-compose.yml`) if you specify them or not.
#### What PHP Modules are available?
The devilbox is a development stack, so it is made sure that a lot of PHP modules are available out of the box in order to work with many different frameworks.
> *apc, apcu, bcmath, bz2, calendar, Core, ctype, curl, date, dom, ereg, exif, fileinfo, filter, ftp, gd, gettext, gmp, hash, iconv, igbinary, imagick, imap, intl, json, ldap, libxml, magickwand, mbstring, mcrypt, memcache, memcached, mhash, mongodb, msgpack, mysql, mysqli, mysqlnd, openssl, pcntl, pcre, PDO, pdo_mysql, pdo_pgsql, pdo_sqlite, pgsql, phalcon, Phar, posix, pspell, readline, recode, redis, Reflection, session, shmop, SimpleXML, soap, sockets, SPL, sqlite3, standard, sysvmsg, sysvsem, sysvshm, tidy, tokenizer, uploadprogress, wddx, xdebug, xml, xmlreader, xmlrpc, xmlwriter, xsl, Zend OPcache, zip, zlib*
There will however be slight differences between the versions and especially with HHVM. To see the exact bundled modules for each version visit the corresponding docker repositories on Github:
[PHP 5.4](https://github.com/cytopia/docker-php-fpm-5.4) |
[PHP 5.5](https://github.com/cytopia/docker-php-fpm-5.5) |
[PHP 5.6](https://github.com/cytopia/docker-php-fpm-5.6) |
[PHP 7.0](https://github.com/cytopia/docker-php-fpm-7.0) |
[PHP 7.1](https://github.com/cytopia/docker-php-fpm-7.1) |
[PHP 7.2](https://github.com/cytopia/docker-php-fpm-7.2) |
[HHVM](https://github.com/cytopia/docker-hhvm-latest)
#### Can I load custom PHP modules without rebuilding the Docker container?
Yes. You can load custom PHP modules for each PHP version separately. See [Custom PHP Modules](Configure.md#425-custom-php-modules) in the Configuration documentation.
## 2. Configuration
#### Can I change the MySQL root password?
Yes, you can change the password of the MySQL root user. If you do so, you must also set the new password in your `.env` file. See **[Configure](Configure.md)** for how to change the values.
#### Can I add other PHP Modules?
Yes, if there are any PHP modules you require that are not yet available in the PHP Docker container, you can install it during run-time, or create your own container. See **[Hacking](Hacking.md)** for more information.
#### Can I change php.ini?
Yes, php.ini directives can be changes on a per PHP version base. Go to `./cfg/` inside devilbox git diretory. There you will find configuration directories for each php version. Just put a \*.ini file there and restart the devilbox.
#### Can I change my.cnf?
Yes, my.cnf directives can be changes on a per MySQL version base. Go to `./cfg/` inside devilbox git diretory. There you will find configuration directories for each MySQL version. Just put a \*.cnf file there and restart the devilbox.
#### Can I switch HHVM between PHP 5.6 and PHP 7 mode?
Yes, this can be done by adding a \*.ini file to `./cfg/hhvm-latest/` with the following content to disable PHP 7 mode:
```ini
hhvm.php7.all = 0
```
The default is to use PHP 7 mode.
#### Can I change the project virtual host domain `.loc`?
Yes, the `.env` variable `TLD_SUFFIX` can be adjusted with whatever domain or subdomain your require. A few examples to get you started:
| Project folder | TLD_SUFFIX | Project URL |
|----------------|------------|--------------------------|
| project1 | loc | http://project1.loc |
| project1 | local | http://project1.local |
| project1 | dev | http://project1.dev |
| project1 | work.loc | http://project1.work.loc |
#### Can I just start PHP and MySQL instead of all container?
Yes, every Docker container is optional. The devilbox allows for selective startup. See **[Run: selective start](Run.md#13-selective-start)** for more detail.
#### Do I always have to edit `/etc/hosts` for new projects?
You need a valid DNS entry for every project that points to the Httpd server. As those records don't exists by default, you will have to create them. However, the devilbox has a bundled DNS server that can automate this for you. The only thing you have to do for that to work is to add this DNS server's IP address to your `/etc/resolv.conf`. See **[Configure: AutoDNS](Configure.md#62-auto-dns)** for instructions.
## 3. Usage
#### Does it work with CakePHP?
Yes, see **[How to setup CakePHP](Examples.md#21-setup-cakephp)**.
#### Does it work with Drupal?
Yes, see **[How to setup Drupal](Examples.md#22-setup-drupal)**.
#### Does it work with Joomla?
Yes, see **[How to setup Joomla](Examples.md#23-setup-joomla)**.
#### Does it work with Laravel?
Yes, see **[How to setup Laravel](Examples.md#24-setup-laravel)**.
#### Does it work with PhalconPHP?
Yes, see **[How to setup Phalcon](Examples.md#25-setup-phalcon)**.
#### Does it work with Symfony?
Yes, see **[How to setup Symfony](Examples.md#26-setup-symfony)**.
#### Does it work with Wordpress?
Yes, see **[How to setup Wordpress](Examples.md#27-setup-wordpress)**.
#### Does it work with Yii?
Yes, see **[How to setup Yii](Examples.md#28-setup-yii)**.
#### Does it work with Zend Framework?
Yes, see **[How to setup Zend](Examples.md#29-setup-zend)**.
## 4. Troubleshooting
#### `Invalid bind mount spec` after changing the path of MySQL, PgSQL, Mongo or the Data dir.
When you change any paths inside `.env` that affect Docker mountpoints, the container need to be *removed* and re-created during the next startup. *Removing* the container is sufficient as they will always be created during run if they don't exist.
In order to *remove* the container do the following:
```shell
$ docker-compose stop
# Remove the stopped container (IMPORTANT!)
# After the removal it will be re-created during next run
$ docker-compose rm -f
```
<a href="https://devilbox.readthedocs.io" title="Devilbox Documentation">
<img style="width:200px;height:200px;" widh="200" height="200" title="Devilbox Documentation" name="Devilbox Documentation" src="https://raw.githubusercontent.com/cytopia/icons/master/400x400/readthedocs.png" />
</a>

157
docs/Hacking.md
View File

@ -1,156 +1,7 @@
# Devilbox Documentation
[Overview](README.md) |
[Quickstart](Quickstart.md) |
[Install](Install.md) |
[Update](Update.md) |
[Configure](Configure.md) |
[Run](Run.md) |
[Usage](Usage.md) |
[OS](OS.md) |
[Backups](Backups.md) |
[Examples](Examples.md) |
[Technical](Technical.md) |
Hacking |
[FAQ](FAQ.md)
#### Devilbox documentation has moved to [devilbox.readthedocs.io](https://devilbox.readthedocs.io)
---
## Hacking
1. [Rebuilding bundled Docker container](#1-rebuilding-bundled-docker-container)
1. [Why rebuild yourself?](#11-why-rebuild-yourself)
2. [How to rebuild yourself?](#12-how-to-rebuild-yourself)
3. [How to use the rebuild container?](#13-how-to-use-the-rebuild-container)
2. [Customizing the bundled Docker container](#2-customizing-the-bundled-docker-container)
3. [Adding your own Docker container](#3-adding-your-own-docker-container)
1. [What information will you need?](#31-what-information-will-you-need)
2. [How to add your service?](#32-how-to-add-your-service)
3. [How to start your service?](#33-how-to-start-your-service)
---
## 1. Rebuilding bundled Docker container
The devilbox Docker container are rebuild frequently and pushed to [dockerhub](https://hub.docker.com/r/cytopia/). However there might be cases in which you want to rebuild right away in order to use a new minor version of a tool inside the container.
#### 1.1 Why rebuild yourself?
Imagine for example you are using the [PHP 7.1](https://github.com/cytopia/docker-php-fpm-7.1) container which currently is available with the version 7.1.6. You found that PHP 7.1.7 has just been released, but the container wasn't yet updated to that version. If you can't wait and need that version now, you can just update the container to that version yourself.
#### 1.2 How to rebuild yourself?
Rebuilding yourself has been made pretty easy. The devilbox docker container repositories come with two scripts for automatic rebuilding. `build/docker-build.sh` and `build/docker-rebuild.sh`.
1. *Clone* or *fork and clone* the desired docker repository to your computer
2. Run `build/docker-build.sh` (cached build) or `build/docker-rebuild.sh` (uncached build)
Either of the two above scripts will rebuild the desired docker container with the latest available versions. The rebuild docker container will then be available locally by the tag `latest`
#### 1.3 How to use the rebuild container?
##### 1.3.1 Tagged devilbox repository
If your devilbox git repository is checked out on a `git tag`, then also the docker container are bound to specific docker tags. It will look like this in `docker-compose.yml`:
```yml
php:
image: cytopia/${PHP_SERVER:-php-fpm-7.0}:0.10
```
Your newly rebuild `latest` docker container will not yet be available for the next run. You still need to change the `docker-compose.yml` and set the container to `latest`:
```yml
php:
image: cytopia/${PHP_SERVER:-php-fpm-7.0}:latest
```
##### 1.3.2 devilbox repository on master branch
If your devilbox git repository is checkout out on the `master` branch, then all docker container are always bound to the `latest` docker tag inside `docker-compose.yml` and you do not need to change anything. Just rebuilding the container is enough to be picked up for the next start.
## 2. Customizing the bundled Docker container
Customizing a Docker container is almost as simple as rebuilding it.
1. Fork the desired docker repository
2. Clone your forked docker repository locally
3. Edit `Dockerfile` with your customization
4. Run `build/docker-build.sh` (cached build) or `build/docker-rebuild.sh` (uncached build)
5. Read the rebuild section above to apply necessary steps
## 3. Adding your own Docker container
You can add your custom docker container including its configuration to `docker-compose.yml`.
#### 3.1 What information will you need?
1. A name that you can use to refer to in the docker-compose command
2. The Docker image name
3. The Docker image version or `latest`
4. An unused IP address from the devilbox network
#### 3.2 How to add your service?
##### 3.2.1 General example
1. Open `docker-compose.yml`
2. Paste the following snippet with your replaced values just below the `services:` line (with one level of indentation)
```yml
...
services:
# Your custom Docker container here:
<name>:
image: <image-name>:<image-version>
networks:
app_net:
ipv4_address: <unused-ip-address>
# For ease of use always automatically start these:
depends_on:
- bind
- php
- httpd
# End of custom Docker container
...
```
##### 3.2.2 Specific example
Lets make a real example for adding [Cockroach DB](https://hub.docker.com/r/cockroachdb/cockroach/)
1. Name: `cockroach`
2. Image: `cockroachdb/cockroach`
3. Version: `latest`
4. IP: `172.16.238.200`
Now add the information to `docker-compose.yml` just below the `services:` line:
```yml
...
services:
# Your custom Docker container here:
cockroach:
image: cockroachdb/cockroach:latest
networks:
app_net:
ipv4_address: 172.16.238.200
# For ease of use always automatically start these:
depends_on:
- bind
- php
- httpd
# End of custom Docker container
...
```
#### 3.3 How to start your service?
```shell
# The following will bring up your service including all the
# dependent services (bind, php and httpd)
$ docker-compose up <name>
```
<a href="https://devilbox.readthedocs.io" title="Devilbox Documentation">
<img style="width:200px;height:200px;" widh="200" height="200" title="Devilbox Documentation" name="Devilbox Documentation" src="https://raw.githubusercontent.com/cytopia/icons/master/400x400/readthedocs.png" />
</a>

84
docs/Install.md
View File

@ -1,83 +1,7 @@
# Devilbox Documentation
[Overview](README.md) |
[Quickstart](Quickstart.md) |
Install |
[Update](Update.md) |
[Configure](Configure.md) |
[Run](Run.md) |
[Usage](Usage.md) |
[OS](OS.md) |
[Backups](Backups.md) |
[Examples](Examples.md) |
[Technical](Technical.md) |
[Hacking](Hacking.md) |
[FAQ](FAQ.md)
#### Devilbox documentation has moved to [devilbox.readthedocs.io](https://devilbox.readthedocs.io)
---
## Install
1. [Install Docker](#1-install-docker)
1. [Linux](#11-linux)
2. [Windows](#12-windows)
3. [OSX](#13-osx)
2. [Install Devilbox](#2-install-devilbox)
1. [Latest git tag](#21-latest-git-tag)
2. [Current master branch](#22-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.
<a href="https://devilbox.readthedocs.io" title="Devilbox Documentation">
<img style="width:200px;height:200px;" widh="200" height="200" title="Devilbox Documentation" name="Devilbox Documentation" src="https://raw.githubusercontent.com/cytopia/icons/master/400x400/readthedocs.png" />
</a>

54
docs/OS.md
View File

@ -1,53 +1,7 @@
# Devilbox Documentation
[Overview](README.md) |
[Quickstart](Quickstart.md) |
[Install](Install.md) |
[Update](Update.md) |
[Configure](Configure.md) |
[Run](Run.md) |
[Usage](Usage.md) |
OS |
[Backups](Backups.md) |
[Examples](Examples.md) |
[Technical](Technical.md) |
[Hacking](Hacking.md) |
[FAQ](FAQ.md)
#### Devilbox documentation has moved to [devilbox.readthedocs.io](https://devilbox.readthedocs.io)
---
## Operating System differences
1. [Linux](#1-linux)
2. [Windows](#2-windows)
1. [/etc/hosts](#21-etchosts)
1. [/etc/resolv.conf](#22-etcresolvconf)
3. [OSX](#3-osx)
---
## 1. Linux
Documentation is written from a Linux point of view, so there will be no differences.
## 2. Windows
On Windows you will have to edit different files on the Docker host than on Linux or OSX.
#### 2.1 `/etc/hosts`
To set custom DNS entries on windows you will have to edit `C:\WINDOWS\system32\drivers\etc` instead.
#### 2.2 `/etc/resolv.conf`
In order to add a custom DNS resolver in Windows, you will have to use the GUI tools of your network interfaces.
Check out this blog entry for how to adjust it:
http://www.pc-freak.net/blog/configure-equivalent-linux-etcresolvconf-search-domaincom-ms-windows-dns-suffixes/
## 3. OSX
OSX behaves the same as Linux and will not have any differences from the documentation.
<a href="https://devilbox.readthedocs.io" title="Devilbox Documentation">
<img style="width:200px;height:200px;" widh="200" height="200" title="Devilbox Documentation" name="Devilbox Documentation" src="https://raw.githubusercontent.com/cytopia/icons/master/400x400/readthedocs.png" />
</a>

220
docs/Quickstart.md
View File

@ -1,219 +1,7 @@
# Devilbox Documentation
[Overview](README.md) |
Quickstart |
[Install](Install.md) |
[Update](Update.md) |
[Configure](Configure.md) |
[Run](Run.md) |
[Usage](Usage.md) |
[OS](OS.md) |
[Backups](Backups.md) |
[Examples](Examples.md) |
[Technical](Technical.md) |
[Hacking](Hacking.md) |
[FAQ](FAQ.md)
#### Devilbox documentation has moved to [devilbox.readthedocs.io](https://devilbox.readthedocs.io)
---
## Quickstart
1. [Installation](#1-installation)
2. [Update](#2-update)
1. [Tagged release](#21-tagged-release)
2. [Master branch](#22-master-branch)
3. [Configuration](#3-configuration)
1. [.env](#31-env)
2. [Services](#32-services)
4. [Run](#4-run)
1. [Run all](#41-run-all)
2. [Run selection](#42-run-selection)
5. [Project setup](#5-project-setup)
1. [General setup](#51-general-setup)
2. [Specific Frameworks](#52-specific-frameworks)
6. [Enter the PHP Docker container](#6-enter-the-php-docker-container)
---
## 1. Installation
Installing the devilbox is as easy as this:
```shell
$ git clone https://github.com/cytopia/devilbox
$ cd devilbox/
$ cp env-example .env
```
To find out in more detail for different operating systems have a look at **[Install](Install.md)**.
## 2. Update
You will have the choice to stay on stable git tags or on the latest master branch. Both options have slightly different update procedures. View the quick instructions below and for more information have a look at **[Update](Update.md)**
#### 2.1 Tagged release
```shell
$ docker-compose stop
$ docker-compose rm
$ git fetch --all
$ git checkout "$(git describe --abbrev=0 --tags)"
```
#### 2.2 Master branch
```shell
$ docker-compose stop
$ docker-compose rm
$ git fetch --all
$ git pull origin master
$ ./update-docker.sh
```
## 3. Configuration
The devilbox will work out-of-the box after the above installation routine has been done. However there are lots of options to configure. Read up on it on **[Configure](Configure.md)**. A brief overview is shown below.
#### 3.1 .env
Edit all general settings inside the .env file (file paths, what version to run, debug, timezeon, etc). The `.env` file is well documented and self-explanatory.
```shell
$ vim .env
```
**Important:** When changing any path variables, you will have to stop all container, delete them so that they can be re-created during the next startup.
```shell
$ docker-compose stop
# Remove the stopped container (IMPORTANT!)
# After the removal it will be re-created during next run
$ docker-compose rm -f
```
#### 3.2 Services
Additionally to configure the devilbox in general, you can also configure each service separately by adding/altering service specific configuration files.
**Example:** Configure PHP 5.6
```shell
$ cd cfg/
$ echo "max_execution_time = 180" > php-fpm-5.6/config.ini
```
**Example:** Configure MySQL 5.5
```shell
$ cd cfg/
$ echo "[mysqld]\nslow_query_log = 1" > mysql-5.5/config.cnf
```
## 4. Run
Starting up the devilbox is done via docker-compose commands. You will have the choice to start-up everything or just a selection of the services you need. To get more more information about this view **[Run](Run.md)**.
#### 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
The heart of the devilbox is the easy configuration of an unlimitted numbder of projects. Most stuff configures itself automatically in the background, but a few things are still left up to you. The following will give you a kick-start for setting up a few projects. To find out in more detail view **[Usage](Usage.md)**.
#### 5.1 General setup
**Assumption:**
1. HOST_PATH_TO_HTTPD_DATADIR=**./data/www**
2. TLD_SUFFIX=**loc**
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.loc` |
| <code>./data/www/<b>project2</b></code> | <code>./data/www/project2/<b>htdocs</b></code> | `http://project2.loc` |
| <code>./data/www/<b>wordpress</b></code>| <code>./data/www/wordpress/<b>htdocs</b></code> | `http://wordpress.loc` |
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.loc` |
| project2 | `127.0.0.1 project2.loc` |
| wordpress | `127.0.0.1 wordpress.loc`|
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/
```
#### 5.2 Specific Frameworks
One example of the above mentioned nested directory structure is CakePHP. Its actual www dats is serveed from:
```shell
<project>/cake/app/webroot
```
instead of
```shell
<project>/htdocs
```
You can easily achieve this by symlinking this folder to `htdocs`:
```shell
$ ls -l <project>/
drwxrwxr-x 2 cytopia 4096 Jun 14 08:29 cakephp
lrwxrwxrwx 1 cytopia 11 Jun 14 08:29 htdocs -> cakephp/app/webroot/
```
To quickly find setup instructions for your framework of choice head over to **[Examples](Examples.md)**:
> 2. [Project setup](Examples.md#2-project-setup)
> 1. [Setup CakePHP](Examples.md#21-setup-cakephp)
> 2. [Setup Drupal](Examples.md#22-setup-drupal)
> 3. [Setup Joomla](Examples.md#23-setup-joomla)
> 4. [Setup Laravel](Examples.md#24-setup-laravel)
> 5. [Setup Phalcon](Examples.md#25-setup-phalcon)
> 6. [Setup Symfony](Examples.md#26-setup-symfony)
> 7. [Setup Wordpress](Examples.md#27-setup-wordpress)
> 8. [Setup Yii](Examples.md#28-setup-yii)
> 9. [Setup Zend](Examples.md#29-setup-zend)
## 6. Enter the PHP Docker container
The PHP Docker container is your workhorse which has many tools pre-installed and you can do every task inside instead of doing it on the docker host. Entering the container is done via a shipped script:
```shell
host> ./shell.sh
devilbox@php-7.0.19 in /shared/httpd $
```
Or on windows
```shell
path> ./shell.bat
devilbox@php-7.0.19 in /shared/httpd $
```
See **[Usage](Usage.md)** for a detailed explanation.
<a href="https://devilbox.readthedocs.io" title="Devilbox Documentation">
<img style="width:200px;height:200px;" widh="200" height="200" title="Devilbox Documentation" name="Devilbox Documentation" src="https://raw.githubusercontent.com/cytopia/icons/master/400x400/readthedocs.png" />
</a>

195
docs/README.md
View File

@ -1,192 +1,37 @@
# Devilbox Documentation
Overview |
[Quickstart](Quickstart.md) |
[Install](Install.md) |
[Update](Update.md) |
[Configure](Configure.md) |
[Run](Run.md) |
[Usage](Usage.md) |
[OS](OS.md) |
[Backups](Backups.md) |
[Examples](Examples.md) |
[Technical](Technical.md) |
[Hacking](Hacking.md) |
[FAQ](FAQ.md)
The Devilbox documentation is build via [sphinx](http://www.sphinx-doc.org/en/master) and
automatically updated on [readthedocs](https://devilbox.readthedocs.io) by every git push.
---
## Overview
## Documentation
1. [Main idea](#1-main-idea)
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)
The documentation is available online: https://devilbox.readthedocs.io
---
<a href="https://devilbox.readthedocs.io" title="Devilbox Documentation">
<img style="width:200px;height:200px;" widh="200" height="200" title="Devilbox Documentation" name="Devilbox Documentation" src="https://raw.githubusercontent.com/cytopia/icons/master/400x400/readthedocs.png" />
</a>
## 1. Main idea
The devilbox allows you to have an unlimited 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).
## Local setup
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.
You can also build the documentation locally before pushing to ensure everything looks fine:
The default project catch-all domain is `*.loc` (see [Configure](Configure.md) for how to change it). Let's view an example:
#### Requirements
```shell
# Inside your main project folder
$ ls -l
drwxr-xr-x 3 cytopia 4096 Jun 10 13:10 my-drupal
drwxr-xr-x 3 cytopia 4096 Jun 10 13:10 my-wordpress
drwxr-xr-x 3 cytopia 4096 Jun 10 13:10 project1
drwxr-xr-x 3 cytopia 4096 Jun 10 13:10 project2
drwxr-xr-x 3 cytopia 4096 Jun 10 13:10 yii-test
```
sudo pip install sphinx sphinx-autobuild
sudo pip install sphinx_rtd_theme
```
By having the above folders, the devilbox will automatically be able to serve the following vhosts:
#### How to build
```
cd docs/
sphinx-autobuild . _build/html
```
* http://my-drupal.loc
* http://my-wordpress.loc
* http://project1.loc
* http://project2.loc
* http://yii-test.loc
#### How to view
New folders can be created, deleted and removed during run-time and corresponding virtual hosts will be available instantly without having to restart anything.
Open you browser on http://127.0.0.1:8000
## 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** | |
| Unlimited 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. |
| Custom PHP modules | You can add any custom PHP modules without having to rebuild the Docker container. |
| 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.
| | ![linux][lin-logo] | ![windows][win-logo] | ![osx][osx-logo] |
|-------------|----------------------|---------------------------|----------------------|
| **Docker Version** | normal | [Docker for Windows][d4w] | [Docker for Mac][d4m]|
| **Current Issues** | [here][lin-issues] | [here][win-issues] | [here][osx-issues] |
[win-logo]: https://raw.githubusercontent.com/cytopia/icons/master/64x64/windows.png
[lin-logo]: https://raw.githubusercontent.com/cytopia/icons/master/64x64/linux.png
[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
**How about FreeBSD?**
The devilbox has not been tested on FreeBSD yet. Current milestones include to make it rock-solid on the above listed operating systems. However, if you want it to run on FreeBSD open up an issue on Github and you will receive support making it work on FreeBSD.
## 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)
* [Docker Compose 1.9.0+](https://docs.docker.com/compose/compose-file/compose-versioning/#version-21)
* 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])
## 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/).
## 6. Devilbox documentation
| Topic | Description |
|-------------------------|-------------|
| **[Quickstart](Quickstart.md)** | Command overview to get you started quickly |
| **[Install](Install.md)** | How to install docker, docker-compose and the devilbox |
| **[Update](Update.md)** | Update best practise |
| **[Configure](Configure.md)** | How to configure the devilbox, switch versions (PHP, MySQL, PgSQL, ...) and how to set custom options (php.ini, my.cnf, httpd.conf, ...) |
| **[Run](Run.md)** | How to operate the devilbox, start and stop all or only required Docker container. |
| **[Usage](Usage.md)** | How to create projects, Email and DNS usage, tools (`composer`, `npm`, `node`, `drush`, ...), entering the container, Log files, Xdebug, Backups, Intranet, ...|
| **[OS](OS.md)** | Operating System differences between Linux, Windows and OSX. |
| **[Backups](Backups.md)** | How to backup and restore your databases for different versions. |
| **[Examples](Examples.md)** | Some project examples for popular CMS/Frameworks. How to setup Wordpress, Drupal, Yii, ... |
| **[Technical](Technical.md)** | Technical background information |
| **[Hacking](Hacking.md)** | How to extend the devilbox with your own docker container |
| **[FAQ](FAQ.md)** | Questions and Troubleshooting |
## 7. Video Tutorials
Have a look at youtube to see some the features in action.
[![Devilbox setup and workflow](img/devilbox_01-setup-and-workflow.png "devilbox - setup and workflow")](https://www.youtube.com/watch?v=reyZMyt2Zzo)
[![Devilbox email catch-all](img/devilbox_02-email-catch-all.png "devilbox - email catch-all")](https://www.youtube.com/watch?v=e-U-C5WhxGY)
## 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.
> *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) |
[PHP 7.2](https://github.com/cytopia/docker-php-fpm-7.2) |
[HHVM](https://github.com/cytopia/docker-hhvm-latest)
** Custom PHP Modules**
Apart from asking for new modules to be bundled with each Docker container, you can simply also just place any missing modules into `mod/(php-fpm|hhvm)-<VERSION>` and add a custom `*.ini` file to load them. See [Custom PHP Modules](Configure.md#425-custom-php-modules) in the Configuration documentation for how to do that in two simple steps.
## 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:
[![CakePHP](img/logo_fw/cake.png)](https://cakephp.org)
[![Drupal](img/logo_fw/drupal.png)](https://www.drupal.org)
[![Laravel](img/logo_fw/laravel.png)](https://laravel.com)
[![Phalcon](img/logo_fw/phalcon.png)](https://phalconphp.com)
[![Symfony](img/logo_fw/symfony.png)](https://symfony.com)
[![Wordpress](img/logo_fw/wordpress.png)](https://wordpress.org)
[![Yii](img/logo_fw/yii.png)](http://www.yiiframework.com)
[![Zend](img/logo_fw/zend.png)](https://framework.zend.com)
Have a look at **[Examples](Examples.md)** for how to set them up on the devilbox.

184
docs/Run.md
View File

@ -1,183 +1,7 @@
# Devilbox Documentation
[Overview](README.md) |
[Quickstart](Quickstart.md) |
[Install](Install.md) |
[Update](Update.md) |
[Configure](Configure.md) |
Run |
[Usage](Usage.md) |
[OS](OS.md) |
[Backups](Backups.md) |
[Examples](Examples.md) |
[Technical](Technical.md) |
[Hacking](Hacking.md) |
[FAQ](FAQ.md)
#### Devilbox documentation has moved to [devilbox.readthedocs.io](https://devilbox.readthedocs.io)
---
## Run
1. [Start the devilbox](#1-start-the-devilbox)
1. [Foreground Start](#11-foreground-start)
2. [Background Start](#12-background-start)
3. [Selective Start](#13-selective-start)
2. [Stop the devilbox](#2-stop-the-devilbox)
1. [Foreground Stop](#21-foreground-stop)
2. [Background Stop](#22-background-stop)
3. [Attach/Detach during run-time](#3-attach-detach-during-run-time)
1. [Attach during run-time](#31-attach-during-run-time)
2. [Detach during run-time](#32-detach-during-run-time)
4. [Docker logs](#4-docker-logs)
1. [All logs](#41-all-logs)
1. [Specific logs](#42-specific-logs)
1. [Tail logs](#43-tail-logs)
---
## 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.
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.
```shell
$ docker-compose up
```
#### 1.2 Background Start
Instead of having the docker-compose run stay in foreground, you can also send it to the background by adding `-d` as an argument. The following will bring up **all** container and send docker-compose to background.
```shell
$ docker-compose up -d
```
#### 1.3 Selective Start
There is no need to always bring up **all** container, if you just need a few at the moment. In order to do so, simply specify the container by name that you actually need.
##### 1.3.1 Starting httpd, php, bind and mysql
```shell
# Foreground
$ docker-compose up httpd php bind mysql
# Background
$ docker-compose up -d httpd php bind mysql
```
**Start Note:** `httpd`, `php` and `bind` are base container that will **always** be started if specified or not. (Defined by `depends_on` in `docker-compose.yml`). So the above could also be achieved by simply specifying `mysql` only.
```shell
# Foreground
$ docker-compose up mysql
# Background
$ docker-compose up -d mysql
```
**Log Note:** When you do not specify httpd, php and bind in foreground start, their docker-logs will not be shown and you will have to explicitly use `docker-compose logs` to view their stdout/stderr output. Refer to the Log section below.
##### 1.3.2 Starting httpd, php, bind, pgsql and redis
```shell
# Foreground
$ docker-compose up httpd php bind pgsql redis
# Background
$ docker-compose up -d httpd php bind pgsql redis
```
**Start Note:** `httpd`, `php` and `bind` are base container that will **always** be started if specified or not. (Defined by `depends_on` in `docker-compose.yml`). So the above could also be achieved by simply specifying `pgsql` and `redis` only.
```shell
# Foreground
$ docker-compose up pgsql redis
# Background
$ docker-compose up -d pgsql redis
```
**Log Note:** When you do not specify httpd, php and bind in foreground start, their docker-logs will not be shown and you will have to explicitly use `docker-compose logs` to view their stdout/stderr output. Refer to the Log section below.
## 2. Stop the devilbox
#### 2.1 Foreground stop
If you started up docker compose in foreground mode (without `-d`), you can hit `ctrl+c` to gracefull stop or **twice** `ctrl+c` to kill the running containers.
**Note:** Automatically started containers that were not specified (such as `http` or `php`) will have to be stopped manually via `docker-compose down` afterwards.
#### 2.2 Background stop
If you started up docker compose in background mode (with `-d`), go back to the devilbox directory (where the `docker-compose.yml` file resides and type `docker-compose down` to gracefully stop or `docker-compose kill` to kill them immediately.
```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
#### 3.1 Attach during run-time
You can also add/attach containers during runtime if you need them. You might have started httpd, php, bind and mysql and decided that you will also require redis. So go ahead and add redis to the running container stack.
```shell
# Foreground
$ docker-compose up redis
# Background
$ docker-compose up -d redis
```
It is recommended to always use background starts, this way you can intially start your desired stack and re-use the current terminal window to start or stop other services.
#### 3.2 Detach during run-time
You can also stop specific containers during runtime if they are not needed anymore. You might have started httpd, php, bind, mysql and redis and decided that redis was not needed. So go ahead and remove redis from the running container stack.
```shell
$ docker-compose stop redis
```
## 4. Docker Logs
Services started in background mode (`-d`) or those that were started as dependencies (`http` and `php`) will always only log to docker logs and not to stdout/stderr.
#### 4.1 All logs
In order to view logs of all started containers type:
```shell
$ docker-compose logs
```
#### 4.2 Specific logs
In order to view logs of a specific container, name it explicitly:
```shell
$ docker-compose logs redis
```
#### 4.3 Tail logs
There is also a version similar to `tail -f` to keep logs updated all the time.
```shell
$ docker-compose logs -f
```
<a href="https://devilbox.readthedocs.io" title="Devilbox Documentation">
<img style="width:200px;height:200px;" widh="200" height="200" title="Devilbox Documentation" name="Devilbox Documentation" src="https://raw.githubusercontent.com/cytopia/icons/master/400x400/readthedocs.png" />
</a>

7
docs/Technical.md Normal file
View File

@ -0,0 +1,7 @@
# Devilbox Documentation
#### Devilbox documentation has moved to [devilbox.readthedocs.io](https://devilbox.readthedocs.io)
<a href="https://devilbox.readthedocs.io" title="Devilbox Documentation">
<img style="width:200px;height:200px;" widh="200" height="200" title="Devilbox Documentation" name="Devilbox Documentation" src="https://raw.githubusercontent.com/cytopia/icons/master/400x400/readthedocs.png" />
</a>

167
docs/Update.md
View File

@ -1,166 +1,7 @@
# Devilbox Documentation
[Overview](README.md) |
[Quickstart](Quickstart.md) |
[Install](Install.md) |
Update |
[Configure](Configure.md) |
[Run](Run.md) |
[Usage](Usage.md) |
[OS](OS.md) |
[Backups](Backups.md) |
[Examples](Examples.md) |
[Technical](Technical.md) |
[Hacking](Hacking.md) |
[FAQ](FAQ.md)
#### Devilbox documentation has moved to [devilbox.readthedocs.io](https://devilbox.readthedocs.io)
---
## Update
1. [TL;DR](#1-tldr)
2. [Git tag vs master branch](#2-git-tag-vs-master-branch)
1. [Git tag](#21-git-tag)
2. [Git master branch](#22-git-master-branch)
3. [Compare .env file](#3-compare-env-file)
4. [Pull new Docker container (Important!)](#4-pull-new-docker-container-important)
5. [Remove anonymous volumes](#5-remove-anonymous-volumes)
---
## 1. TL;DR
Shutdown, update and startup.
```shell
# Stop container, remove deprecated volumes and update git
$ docker-compose down
$ docker-compose rm
$ 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.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.
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`
```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 fetch --all
$ git pull origin master
$ docker-compose pull
```
**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.
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`.
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
```
## 5. Remove anonymous volumes
The devilbox is not yet at a feature-ready stable release and volumes mounts might change from release to release until version 1.0 will be released. This can cause errors during startup. To solve those issues after updating, you should remove all anonymouse volumes with the following command:
```shell
$ docker-compose rm
```
<a href="https://devilbox.readthedocs.io" title="Devilbox Documentation">
<img style="width:200px;height:200px;" widh="200" height="200" title="Devilbox Documentation" name="Devilbox Documentation" src="https://raw.githubusercontent.com/cytopia/icons/master/400x400/readthedocs.png" />
</a>

404
docs/Usage.md
View File

@ -1,403 +1,7 @@
# Devilbox Documentation
[Overview](README.md) |
[Quickstart](Quickstart.md) |
[Install](Install.md) |
[Update](Update.md) |
[Configure](Configure.md) |
[Run](Run.md) |
Usage |
[OS](OS.md) |
[Backups](Backups.md) |
[Examples](Examples.md) |
[Technical](Technical.md) |
[Hacking](Hacking.md) |
[FAQ](FAQ.md)
#### Devilbox documentation has moved to [devilbox.readthedocs.io](https://devilbox.readthedocs.io)
---
## Usage
1. [Mounted directories](#1-mounted-directories)
2. [Work on the Docker host](#2-work-on-the-docker-host)
3. [Work inside the PHP container](#3-work-inside-the-php-container)
1. [As devilbox user](#31-as-devilbox-user)
2. [As root user](#32-as-root-user)
3. [Available tools](#33-available-tools)
4. [Available URLs](#34-available-urls)
4. [Managing Projects explained](#4-managing-projects-explained)
1. [How does it work?](#41-how-does-it-work)
2. [Directory structure explained](#42-directory-structure-explained)
5. [Creating new Projects](#5-creating-new-projetcs)
1. [From Docker Host](#51-from-docker-host)
2. [From inside the PHP container](#52-from-inside-the-php-container)
3. [Using symlinks](#53-using-symlinks)
4. [Adding DNS records](#54-adding-dns-record)
1. [/etc/hosts](#541-etchosts)
2. [Auto-DNS](#542-auto-dns)
6. [Switching container versions](#6-switching-container-versions)
1. [Httpd versions](#61-httpd-versions)
2. [PHP versions](#62-php-versions)
2. [SQL versions](#63-sql-versions)
3. [NoSQL versions](#64-nosql-versions)
7. [Emails](#7-emails)
8. [Log files](#8-log-files)
1. [Mounted logs](#81-mounted-logs)
2. [Docker logs](#82-docker-logs)
9. [Intranet](#9-intranet)
1. [Overview](#91-overview)
2. [vHosts](#92-vhosts)
3. [Tools](#93-tools)
---
## 1. Mounted directories
Mounted directories are the bridge between the container and your host computer.
All your projects will be available on your host computer as well as inside the Docker container.
That makes it possible to work from the Docker host, by for example editing your files with your favorite editor/IDE and to run any commands, such as `npm`, `composer` or others inside the PHP container with the correct PHP version.
## 2. 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.
1. Open your browser at http://localhost
2. Open your project inside your editor
3. Start coding
**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.
You could however also invoke the Docker's PHP executeable (or any other binary) from your host via:
```shell
# 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
```
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
```
However, instead of having to type all of the above for a simple command execution, you might be better off to simply enter the PHP container and work on a normal shell. Going into the container is as simple as this:
```
$ ./shell.sh
```
Read more about this in the next section.
## 3. 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.
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.
**FYI:** You will always find your projects inside the PHP container at `/shared/httpd/`.
#### 3.1 As devilbox user
In the devilbox git directory you will find a bash script called `shell.sh`. Just execute this script and it will take you directly into the PHP docker container at the project root directory.
```shell
host> ./shell.sh
devilbox@php-7.0.19 in /shared/httpd $
```
As you can see, the PS1 prompt will also show you the current configured PHP version.
#### 3.2 As root user
In case you need to perform some tasks that are only possible with root rights (such as installing or updating software), you can do so via password-less `sudo`.
```shell
host> ./shell.sh
devilbox@php-7.0.19 in /shared/httpd $ sudo su -
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).
#### 3.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:
| Binary | Tool name |
|------------|-------------------|
| `composer` | [composer](https://getcomposer.org) |
| `drush` | [drush](http://www.drush.org/) |
| `drupal` | [drupal-consol](https://drupalconsole.com) |
| `git` | [git](https://git-scm.com) |
| `laravel` | [laravel installer](https://github.com/laravel/installer) |
| `mysqldump-secure` | [mysqldump-secure](https://mysqldump-secure.org) |
| `node` | [node](https://nodejs.org) |
| `npm` | [npm](https://www.npmjs.com) |
| `phalcon` | [phalcon devtools](https://github.com/phalcon/phalcon-devtools) |
| `symfony` | [symfony installer](https://github.com/symfony/symfony-installer) |
| `wp` | [wp-cli](https://wp-cli.org/) |
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) |
[PHP 7.2](https://github.com/cytopia/docker-php-fpm-7.2) |
[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).
#### 3.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.loc` from either your host computer or from inside the PHP container will return the same URL.
## 4. Managing Projects explained
[![Devilbox setup and workflow](img/devilbox_01-setup-and-workflow.png "devilbox - setup and workflow")](https://www.youtube.com/watch?v=reyZMyt2Zzo)
#### 4.1 How does it work?
Creating new projects is really simple and just involves a few steps.
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`)
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).
#### 4.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=**loc**
| VirtualHost directory | DocumentRoot directory | URL |
|-----------------------|-----------------------------|------------------------|
| <code>./data/www/<b>project1</b></code> | <code>./data/www/project1/<b>htdocs</b></code> | `http://project1.loc` |
| <code>./data/www/<b>project2</b></code> | <code>./data/www/project2/<b>htdocs</b></code> | `http://project2.loc` |
| <code>./data/www/<b>wordpress</b></code>| <code>./data/www/wordpress/<b>htdocs</b></code> | `http://wordpress.loc` |
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.
## 5. Creating new Projetcs
This is a general overview about creating projects. If you want to see some real examples how to setup **Wordpress**, **Drupal**, **CakePHP**, **Yii**, **Symfony** and others, visit the [Example Section](Examples.md).
#### 5.1 From Docker host
The following will create a VirtualHost for `http://project1.loc`.
```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 `loc` to something else, refer to [Configure](Configure.md).</sub>
#### 5.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.loc`.
```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>
#### 5.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/
```
#### 5.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.
##### 5.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 `loc`.
| Project folder | `/etc/hosts` entry |
|----------------|-------------------------------|
| my-project1 | `127.0.0.1 my-project1.loc` |
| drupal-test | `127.0.0.1 drupal-test.loc` |
| playground | `127.0.0.1 playground.loc` |
##### 5.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.
## 6. Switching container versions
Being able to combine all kinds of different container version is one of the main goals of the devilbox. Changing the versions is kept simple and consistent for all container.
1. Open the `.env` file in your favorite editor
2. Find the `*_SERVER=` block for the container to change the version
3. Comment all lines you do not want to activate
4. Uncomment the one line you want to use.
5. Restart the devilbox for the changes to take effect
<sub>Be aware that if multiple lines are uncommented, the last one takes effect.</sub>
For an in-depth explanation about how to configure each service, you should have a look at [Configure](Configure.md).
#### 6.1 Httpd versions
1. Open the `.env` file in your favorite editor
2. Find the `HTTPD_SERVER=` block
You can choose between Apache and Nginx in different version. All of them are configured to work the same, there is nothing to worry about when changing them.
#### 6.2 PHP versions
1. Open the `.env` file in your favorite editor
2. Find the `PHP_SERVER=` block
You can choose between different PHP versions and HHVM.
**Important:** Keep in mind that if you have a custom php.ini config at `./cfg/php-*/`, it is only effective for one version. Custom php configurations are separted per version.
#### 6.3 SQL versions
1. Open the `.env` file in your favorite editor
2. Find the `MYSQL_SERVER=` or `PGSQL_SERVER=` block
**Important:** Each version has a different data directory. This is a security precautions. Imagine you startup MySQL 5.5 for the first time. New databases will be created. Now you startup MySQL 8. All existing databases would be upgraded to work flawlessly with MySQL 8, however this is not downwards compatible. So by startup up MySQL 5.5 again, it would say the database is corrupt.
#### 6.4 NoSQL versions
1. Open the `.env` file in your favorite editor
2. Find the `MONGO_SERVER=`, 'MEMCD_SERVER=` or `REDIS_SERVER=` block
There is nothing to pay attention to here.
## 7. Emails
All your projects can send emails to whatever recipient. You do not have to worry that they will actually being sent. Each PHP container runs a local postfix mailserver that intercepts all outgoing mails and puts them all in the local devilbox user mail account.
In order to view sent emails open up the devilbox intranet http://localhost/mail.php. There you can also test email sending and verify that they really stay locally.
## 8. Log files
#### 8.1 Mounted logs
Log files are available on the Host system and separated per service version. See `./log/` (inside devilbox git directory). The `./log/` folder itself will contain subdirectories in the form `<service>-<version>` which will then hold all available log files.
**Example:**
```
log/
apache-2.2/
access_log
error_log
localhost-access.log
localhost-error.log
other-error.log
apache-2.4/
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
```
#### 8.2 Docker logs
All output printed to stdout or stderr by the started services 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.
## 9. Intranet
The devilbox bundled intranet is not required for project management or creation, however it offers a few useful tools.
#### 9.1 Overview
The overview page presents you the current state of the running stack and any errors it might have encountered.
http://localhost
#### 9.2 vHosts
The vHost page shows you all available projects and any configuation errors that need to be resolved. Errors could be: missing `htdocs/` folder and incorrect DNS settings. So make sure to first visit this page if any of your vHost does not work.
http://localhost/vhosts.php
#### 9.3 Tools
The intranet also offers a few common as well as self-made tools. These include:
* phpMyAdmin
* Adminer
* Mail viewer
* OpCacheGUI
* SQL/NoSQL database viewer
* Info pages (showing detailed configurations for the attached container)
If you are interested in doing database backups, either use phpMyAdmin or Adminer. You can however also use the PHP container itself. Read more about this on [Backups](Backups.md)
<a href="https://devilbox.readthedocs.io" title="Devilbox Documentation">
<img style="width:200px;height:200px;" widh="200" height="200" title="Devilbox Documentation" name="Devilbox Documentation" src="https://raw.githubusercontent.com/cytopia/icons/master/400x400/readthedocs.png" />
</a>

12
docs/conf.py
View File

@ -55,12 +55,12 @@ templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
source_suffix = ['.rst', '.md']
#source_suffix = '.rst'
source_parsers = {
'.md': CommonMarkParser,
}
source_suffix = '.rst'
# Exclude Markdown files for now
#source_suffix = ['.rst', '.md']
#source_parsers = {
# '.md': CommonMarkParser,
#}
# The master toctree document.
master_doc = 'index'