devilbox documentation<a class="headerlink" href="#devilbox-documentation" title="Permalink to this headline">¶

How to update them ¶

There is no need to update the tools itself. All Docker images are rebuilt every night and automatically pushed to Docker hub to ensure versions are outdated at a maximum of 24 hours.

The only thing you have to do, is to update the Docker images itself, simply by pulling a new version.

See also

Update Docker images

Advanced ¶

This is just a short overview about the possibility to work inside the container. If you want to dig deeper into this topic there is also a more advanced tutorial available:

See also

Checklist ¶

You know how to enter the PHP container on Linux, MacOS or Windows
You know how to become root inside the PHP container
You know what tools are available inside the PHP container
You know how to update the tools by pulling new versions of the Docker images

The Intranet¶

The intranet is your command & control center showing all kinds of information and settings currently in effect. It also offers third-party projects to do all sorts of database manipulation.

Table of Contents

Devilbox tools
Third-party tools
Settings
- Password protect the intranet
- Disable the intranet
Checklist

Devilbox tools ¶

Overview ¶

The start page is there to check if everything works as expected. It shows all desired Docker containers you wanted to start and if they succeeded, as well as their ports, mount points and special settings applied via .env.

Virtual hosts ¶

The virtual host page displays all available projects and let’s you know if their configuration is correct, such as DNS settings or document root.

Emails ¶

The email page displays all emails that would have been sent, but were caught by the integrated email catch-all functionality.

Databases ¶

There are several database pages for MySQL and NoSQL databases giving you an overview about what is currently in place, how many databases/schemas and or recors and what size they take up.

The following example shows the database page for MySQL:

Info pages ¶

Info pages also exist for every Docker container which show various settings which are currently applied.

The following example shows you the info page for PHP.

The following example shows you the info page for MySQL:

Third-party tools ¶

phpMyAdmin ¶

phpMyAdmin is a free software tool written in PHP, intended to handle the administration of MySQL over the Web. phpMyAdmin supports a wide range of operations on MySQL and MariaDB. Frequently used operations (managing databases, tables, columns, relations, indexes, users, permissions, etc) can be performed via the user interface, while you still have the ability to directly execute any SQL statement.

Adminer ¶

Adminer (formerly phpMinAdmin) is a full-featured database management tool written in PHP. Conversely to phpMyAdmin, it consist of a single file ready to deploy to the target server. Adminer is available for MySQL, MariaDB, PostgreSQL, SQLite, MS SQL, Oracle, Firebird, SimpleDB, Elasticsearch and MongoDB.

OpcacheGUI ¶

OpcacheGui is a clean and responsive interface for Zend OPcache information, showing statistics, settings and cached files, and providing a real-time update for the information (using jQuery and React).

Settings ¶

Password protect the intranet ¶

If you share your projects over a LAN, but do not want anybody to view the Devilbox intranet, you can also password protect it.

See also

In order to do so, have a look at the following .env variables:

Disable the intranet ¶

If you want a more production-like setup, you can also fully disable the Devilbox intranet. This is achieved internally by removing the default virtual host which serves the intranet. When the intranet is disabled, there is no way to access it.

See also

In order to do so, have a look at the following .env variable:

DEVILBOX_UI_ENABLE

Checklist ¶

You know what tools are provided by the Devilbox intranet
You know how to password protect the Devilbox intranet
You know how to disable the Devilbox intranet

Best practice¶

If you have already read all documents in the Getting started guide, you should be ready to fully operate the Devilbox. This section builds on top of that and gives you some best-practices as well as tips and tricks.

Table of Contents

Move data out of Devilbox directory
PHP project hostname settings
Timezone

Move data out of Devilbox directory ¶

One thing you should take into serious consideration is to move data such as your projects as well as persistent data of databases out of the Devilbox git directory.

The Devilbox git directory should be something that can be safely deleted and re-created without having to worry about loosing any project data. There could also be the case that you have a dedicated hard-disk to store your projects or you have your own idea about a directory structure where you want to store your projects.

Projects ¶

So let’s assume all of your projects are already in place under /home/user/workspace/web/. Now you decide to use the Devilbox, but still want to keep your projects where they are at the moment.

All you have to to is to adjust the path of HOST_PATH_HTTPD_DATADIR in the .env file.

# Navigate to Devilbox git directory
host> cd path/to/devilbox

# Open the .env file with your favourite editor
host> vim .env

Now Adjust the value of HOST_PATH_HTTPD_DATADIR

.env¶

HOST_PATH_HTTPD_DATADIR=/home/user/workspace/web

That’s it, whenever you start up the Devilbox /home/user/workspace/web/ will be mounted into the PHP and the web server container into /shared/httpd/.

Databases ¶

Moving your projects out of the Devilbox git directory is one step, you still need to take care about persistent data of all available databases as well.

Let’s assume you desired location for database storage is at /home/user/workspace/db/.

MySQL ¶

All you have to to is to adjust the path of HOST_PATH_MYSQL_DATADIR in the .env file.

# Navigate to Devilbox git directory
host> cd path/to/devilbox

# Open the .env file with your favourite editor
host> vim .env

Now Adjust the value of HOST_PATH_MYSQL_DATADIR

.env¶

HOST_PATH_MYSQL_DATADIR=/home/user/workspace/db/mysql

That’s it, whenever you start up the Devilbox /home/user/workspace/db/mysql/ will be mounted into the MySQL container.

PostgreSQL ¶

All you have to to is to adjust the path of HOST_PATH_PGSQL_DATADIR in the .env file.

# Navigate to Devilbox git directory
host> cd path/to/devilbox

# Open the .env file with your favourite editor
host> vim .env

Now Adjust the value of HOST_PATH_PGSQL_DATADIR

.env¶

HOST_PATH_PGSQL_DATADIR=/home/user/workspace/db/pgsql

That’s it, whenever you start up the Devilbox /home/user/workspace/db/pqsql/ will be mounted into the PostgreSQL container.

MongoDB ¶

All you have to to is to adjust the path of HOST_PATH_MONGO_DATADIR in the .env file.

# Navigate to Devilbox git directory
host> cd path/to/devilbox

# Open the .env file with your favourite editor
host> vim .env

Now Adjust the value of HOST_PATH_MONGO_DATADIR

.env¶

HOST_PATH_MONGO_DATADIR=/home/user/workspace/db/mongo

That’s it, whenever you start up the Devilbox /home/user/workspace/db/mongo/ will be mounted into the MongoDB container.

Version control `.env` file ¶

The .env file is ignored by git, because this is your file to customize and it should be your responsibility to make sure to backup or version controlled.

One concept you can apply here is to have a separate dotfiles git repository. This is a repository that holds all of your configuration files such as vim, bash, zsh, xinit and many more. Those files are usually stored inside this repository and then symlinked to the correct location. By having all configuration files in one place, you can see and track changes easily as well as bein able to jump back to previous configurations.

In case of the Devilbox .env file, just store this file in your repository and symlink it to the Devilbox git directiry. This way you make sure that you keep your file, even when the Devilbox git directory is deleted and you also have a means of keeping track about changes you made.

You could also go further and have several .env files available somewhere. Each of those files holds different configurations e.g. for different projects or customers.

env-customer1
env-php55
env-project3

You would then simply symlink one of those files to the Devilbox git directory.

Version control service config files ¶

Todo

This will require some changes on the Devilbox and will be implemented shortly.

Symlink and have your own git directory
Separate data partition, backups

PHP project hostname settings ¶

When configuring your PHP projects to use MySQL, PostgreSQL, Redis, Mongo and other services, make sure to set the hostname of each of those services to 127.0.0.1.

Why is that?

The PHP container port-forwards each service port to its own listen address on 127.0.0.1. The Devilbox also exposes each of those service ports to the host operating system on 127.0.0.1.

This allows you to keep your project configuration unchanged and have the same behaviour inside the PHP container and on your host operating system.

Important

Do not mix up localhost with 127.0.0.1. They behave differently! Use 127.0.0.1 and do not use localhost.

As an example, if you want to access the MySQL database from within the PHP container, you do the following:

 # Navigate to Devilbox git directory
 host> cd path/to/devilbox

 # Enter the PHP container
 host> ./shell.sh

 # Enter the MySQL console
 php> mysql -u root -h 127.0.0.1 -p
 mysql>

The very same command applies to access the MySQL database from your host operating system:

 # Enter the MySQL console
 host> mysql -u root -h 127.0.0.1 -p
 mysql>

So no matter if you use the Devilbox or have another LAMP stack installed locally on your host operating system, you do not have to change your configuration files if you stick to this tip.

So any of your projects php files that configure MySQL as an example should point the hostname or IP address of the MySQL server to 127.0.0.1:

<?php
// MySQL server connection in your project configuration
mysql_host = '127.0.0.1';
mysql_port = '3306';
mysql_user = 'someusername';
mysql_pass = 'somepassword';
?>

See also

docker-compose.override.yml

Timezone ¶

The TIMEZONE value will affect PHP, web server and MySQL container equally. It does however not affect any other official Docker container that are used within the Devilbox. This is an issue that is currently still being worked on.

Feel free to change this to any timezone you require for PHP and MySQL, but keep in mind that timezone values for databases can be painful, once you want to switch to a different timezone.

A good practice is to always use UTC on databases and have your front-end application calculate the correct time for the user. This way you will be more independent of any changes.

Backup and restore MySQL¶

Backup and restore will be necessary when you are going to switch MySQL versions. Each version has its own data directory and is fully indepentend of other versions. In case you want to switch to a different version, but still want to have your MySQL databases present, you must first backup the databases of your current version and import them into the new version.

There are multiple ways to backup and restore. Chose the one which is most convenient for you.

Table of Contents

Backup
Restore

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 as well as the server version it came from.

Mysqldump-secure ¶

mysqldump-secure is bundled, setup and ready to use in every PHP 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/ inside the Devilbox git directory or in /shared/backups/mysql/ inside the PHP container.

To have your backups in place is just three commands away:

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Enter the PHP container
host> ./shell.sh

# Run mysqldump-secure
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 ¶

Let’s see where to find the backups inside the PHP container:

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Enter the PHP container
host> ./shell.sh

# Show directory output
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

Let’s do the same again and see where to find the backups in the Devilbox git directory

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Show directory output
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

`*.info` files ¶

The *.info file will hold many useful information in case you need to debug any problems occured during backups. Let’s have a look at one of them:

host> cat ./backups/mysql/2017-06-17_13-31__mysql.sql.gz.info

2017-06-17_13-31__mysql.sql.gz.info¶

; 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

mysqldump ¶

mysqldump is bundled with each PHP container and ready to use. To backup a database named my_db_name follow the below listed example which shows you how to do that from within the PHP container:

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Enter the PHP 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

phpMyAdmin ¶

If you do not like to use the command line for backups, you can use phpMyAdmin. It comes bundled with the devilbox intranet.

To find out more about the usage of phpMyAdmin, visit its project page under: https://www.phpmyadmin.net.

Adminer ¶

If you do not like to use the command line for backups, you can use Adminer. It comes bundled with the devilbox intranet.

To find out more about the usage of Adminer, visit its project page under: https://www.adminer.org.

Restore ¶

mysql ¶

In order to restore or import mysql databases on the command line, you need to use the mysql binary. Here are a few examples for different file types:

`*.sql` file ¶

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Enter the PHP 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

`*.sql.gz` file ¶

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Enter the PHP 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

`*.sql.tar.gz` file ¶

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Enter the PHP 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

phpMyAdmin ¶

phpMyAdmin supports importing many different formats out-of-the-box. Simply select the compressed or uncompressed file and press Go in the import section of the web interface.

Adminer ¶

Adminer 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 import section of the web interface.

Backup and restore PostgreSQL¶

Backup and restore will be necessary when you are going to switch PostgreSQL versions. Each version has its own data directory and is fully indepentend of other versions. In case you want to switch to a different version, but still want to have your PostgreSQL databases present, you must first backup the databases of your current version and import them into the new version.

There are multiple ways to backup and restore. Chose the one which is most convenient for you.

Table of Contents

Backup
- pg_dump
- Adminer
Restore
- psql
- Adminer

Backup ¶

pg_dump ¶

pg_dump is bundled with each PHP container and reay to use. To backup a database named my_db_name follow the below listed example:

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Enter the PHP container
host> ./shell.sh

# Run pg_dump
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.

Adminer ¶

If you do not like to use the command line for backups, you can use Adminer. It comes bundled with the devilbox intranet.

To find out more about the usage of Adminer, visit its project page under: https://www.adminer.org.

Restore ¶

psql ¶

In order to restore or import PostgreSQL databases on the command line, you need to use psql. Here are a few examples for different file types:

`*.sql` file ¶

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Enter the PHP 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

`*.sql.gz` file ¶

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Enter the PHP 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

`*.sql.tar.gz` file ¶

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Enter the PHP 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

Adminer ¶

Adminer 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 import section of the web interface.

Backup and restore MongoDB¶

Backup and restore will be necessary when you are going to switch MongoDB versions. Each version has its own data directory and is fully indepentend of other versions. In case you want to switch to a different version, but still want to have your MongoDB databases present, you must first backup the databases of your current version and import them into the new version.

There are multiple ways to backup and restore. Chose the one which is most convenient for you.

Table of Contents

Backup
- mongodump
Restore
- mongorestore

Backup ¶

mongodump ¶

mongodump is bundled with each PHP container and reay to use. To backup all databases follow the below listed example:

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Enter the PHP container
host> ./shell.sh

# Run mongodump
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.

Restore ¶

mongorestore ¶

mongorestore is bundled with each PHP container and ready to use. To restore all MongoDB databases follow the below listed example:

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Enter the PHP 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/.

Communicating with external hosts¶

This tutorial shows you how to connect the Devilbox to running Docker container outside the Devilbox network, i.e. Docker container you have started separately.

Table of Contents

Prerequisites
Make DNS available to the Devilbox
Further reading

Prerequisites ¶

There are two things you need to make sure of are met beforehand:

The external Docker container must expose its ports on all interfaces on your host operating system
The IP by which the host is reachable from within the Devilbox container.

Host IP: Docker on Linux ¶

If you run Docker on Linux the host IP is always 172.16.238.1, which is the default gateway IP address within the Devilbox bridge network (see docker-compose.yml).

By default Docker on Linux does not have CNAME’s of the host computer as for example with MacOS or Windows, therefore two custom CNAME’s have been added by the Devilbox in order to emulate the same behaviour:

CNAME: docker.for.lin.host.internal
CNAME: docker.for.lin.localhost

Host IP: Docker for Mac ¶

If you run Docker for Mac, an IP address is not necessary as it already provides a CNAME which will always point to the IP address of your host operating system. Depending on the Docker version this CNAME will differ:

Docker 18.03.0-ce+ and Docker compose 1.20.1+¶

CNAME: host.docker.internal

Docker 17.12.0-ce+ and Docker compose 1.18.0+¶

CNAME: docker.for.mac.host.internal

Docker 17.06.0-ce+ and Docker compose 1.14.0+¶

CNAME: docker.for.mac.localhost

Host IP: Docker for Windows ¶

If you run Docker for Windows, an IP address is not necessary as it already provides a CNAME which will always point to the IP address of your host operating system. Depending on the Docker version this CNAME will differ:

Docker 18.03.0-ce+ and Docker compose 1.20.1+¶

CNAME: docker.for.win.host.internal

Docker 17.06.0-ce+ and Docker compose 1.14.0+¶

CNAME: docker.for.win.host.localhost

Make DNS available to the Devilbox ¶

Inside each Devilbox Docker container you can already connect to all host ports (if they are bound to all interfaces) by the above specified IP addresses or CNAME’s. You can however also create a custom DNS entry for convenience or if an external web server requires a special vhost name.

Adding extra hosts ¶

Extra hosts (hostname and IP address mappings or hostname and CNAME mappings) can be set in the .env file.

See also

EXTRA_HOSTS

Example ¶

Let’s assume another Docker container is running on your host, which must be accessed by the exact name of mywebserver.loc in order to respond by that virtual host name.

Mapping on Linux ¶

If you are running Linux as your host operating system you would use the IP address of the host computer which was identified as 172.16.238.1.

.env¶

EXTRA_HOSTS=mywebserver.loc=172.16.238.1

or

.env¶

EXTRA_HOSTS=mywebserver.loc=docker.for.lin.host.internal

or

.env¶

EXTRA_HOSTS=mywebserver.loc=docker.for.lin.localhost

Mapping on MacOS ¶

If you are running MacOS as your host operating system you would use one of the identified CNAME’s (depending on your Docker version).

.env¶

EXTRA_HOSTS=mywebserver.loc=host.docker.internal

The CNAME host.docker.internal will be resolved to an IP address during startup and mywebserver.loc ‘s DNS record will point to that IP address.

Mapping on Windows ¶

If you are running Windows as your host operating system you would use one of the identified CNAME’s (depending on your Docker version).

.env¶

EXTRA_HOSTS=mywebserver.loc=docker.for.win.host.internal

The CNAME docker.for.win.host.internal will be resolved to an IP address during startup and mywebserver.loc ‘s DNS record will point to that IP address.

Auto DNS ¶

If you also turned on Auto-DNS these extra hosts will then also be available to your host operating system as well.

Add your own Docker image¶

This section is all about customizing the Devilbox and its Docker images specifically to your needs.

Table of Contents

Prerequisites
What information do you need?
How to add a new service?
- Generic example
  - A single new service
  - Two new services
- CockroachDB example
How to start the new service?
Further reading

Prerequisites ¶

The new Docker image definition will be added to a file called docker-compose.override.yml. So before going any further, read the following section that shows you how to create this file for the Devilbox as well as what pitfalls to watch out for.

See also

What information do you need?¶

<name> - A name, which you can use to refer in the docker-compose command
<image-name> - The Docker image name itself
<image-version> - The Docker image tag
<unused-ip-address> - An unused IP address from the devilbox network (found inside docker-compose.yml)

How to add a new service?¶

Generic example ¶

A single new service ¶

Open docker-compose.override.yml with your favourite editor and paste the following snippets into it.

docker-compose.override.yml¶

version: '2.1'
services:
  # Your custom Docker image 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 image

Note

<name> has to be replaced with any name of your choice
<image-name> has to be replaced with the name of the Docker image
<image-version> has to be replaced with the tag of the Docker image
<unused-ip-address> has to be replaced with an unused IP address

Two new services ¶

docker-compose.override.yml¶

version: '2.1'
services:
  # Your first custom Docker image here:
  <name1>:
    image: <image1-name>:<image1-version>
    networks:
      app_net:
        ipv4_address: <unused-ip-address1>
    # For ease of use always automatically start these:
    depends_on:
      - bind
      - php
      - httpd
  # End of first custom Docker image
  # Your second custom Docker image here:
  <name2>:
    image: <image2-name>:<image2-version>
    networks:
      app_net:
        ipv4_address: <unused-ip-address2>
    # For ease of use always automatically start these:
    depends_on:
      - bind
      - php
      - httpd
  # End of second custom Docker image

Note

<name1> has to be replaced with any name of your choice
<image1-name> has to be replaced with the name of the Docker image
<image1-version> has to be replaced with the tag of the Docker image
<unused-ip-address1> has to be replaced with an unused IP address

Note

<name2> has to be replaced with any name of your choice
<image2-name> has to be replaced with the name of the Docker image
<image2-version> has to be replaced with the tag of the Docker image
<unused-ip-address2> has to be replaced with an unused IP address

CockroachDB example ¶

Gather the requirements for the Cockroach DB Docker image:

Name: cockroach
Image: cockroachdb/cockroach
Tag: latest
IP: 172.16.238.200

Now add the information to docker-compose.override.yml:

docker-compose.override.yml¶

version: '2.1'
services:
  # Your custom Docker image here:
  cockroach:
    image: cockroachdb/cockroach:latest
    command: start --insecure
    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 image

How to start the new service?¶

The following will bring up your service including all of its dependent services, as defined with depends_on (bind, php and httpd). You need to replace <name> with the name you have chosen.

host> docker-compose up <name>

In the example of Cockroach DB the command would look like this

host> docker-compose up cockroach

Overwrite existing Docker image¶

This section is all about customizing the Devilbox and its Docker images specifically to your needs.

Table of Contents

Prerequisites
What information do you need?
How to overwrite a service?
- Generic steps
- Overwrite Docker image for the bind service
Further reading

Prerequisites ¶

The new Docker image overwrite will be added to a file called docker-compose.override.yml. So before going any further, read the following section that shows you how to create this file for the Devilbox as well as what pitfalls to watch out for.

See also

docker-compose.override.yml

What information do you need?¶

The service to overwrite

How to overwrite a service?¶

Generic steps ¶

Copy the whole service definition from docker-compose.yml to docker-compose.override.yml
Remove anything unecessary
Adjust the values you need

Overwrite Docker image for the bind service ¶

The following example is using the bind service and overrides the Docker image to illustrate how this is done :

First you simply copy the while definition of the bind service from docker-compose.yml to docker-compose.override.yml:

docker-compose.override.yml¶

version: '2.1'
services:
  bind:
    image: cytopia/bind:0.11
    restart: always
    ports:
      # [local-machine:]local-port:docker-port
      - "${LOCAL_LISTEN_ADDR}${HOST_PORT_BIND:-1053}:53"
      - "${LOCAL_LISTEN_ADDR}${HOST_PORT_BIND:-1053}:53/udp"

    environment:
      ##
      ## Debug?
      ##
      - DEBUG_ENTRYPOINT=${DEBUG_COMPOSE_ENTRYPOINT}
      - DOCKER_LOGS=1

      ##
      ## Bind settings
      ##
      - WILDCARD_ADDRESS=172.16.238.11
      - DNS_FORWARDER=${BIND_DNS_RESOLVER:-8.8.8.8,8.8.4.4}

    dns:
      - 127.0.0.1

    networks:
      app_net:
        ipv4_address: 172.16.238.100

The second step is to remove everything that you do not need to overwrite:

docker-compose.override.yml¶

version: '2.1'
services:
  bind:
    image: cytopia/bind:0.11

The last step is to actually adjust the value you want to change for the bind service:

docker-compose.override.yml¶

version: '2.1'
services:
  bind:
    image: someother/bind:latest

Adding Sub domains¶

This tutorial gives you a brief overview how to serve your project under one subdomain via the project directory name as well as how to serve one projcet with multiple subdomains with a customized virtual host config via vhost-gen.

Table of Contents

Single sub domain for one project ¶

When you just want to serve your project under a sub domain, you simply name your project directory by the name of it. See the following examples how you build up your project URL.

Project dir	`TLD_SUFFIX`	Project URL
my-test	`loc`	`http://my-test.loc`
www.my-test	`loc`	`http://www.my-test.loc`
t1.www.my-test	`loc`	`http://t1.www.my-test.loc`
my-test	`com`	`http://my-test.com`
www.my-test	`com`	`http://www.my-test.com`
t2.www.my-test	`com`	`http://t2.www.my-test.com`

Whatever name you want to have in front of the TLD_SUFFIX is actually just the directory you create. Generically, it looks like this:

Project dir	`TLD_SUFFIX`	Project URL
<dir-name>	`<tld>`	`http://<dir-name>.<tld>`

Multiple sub domains for one project ¶

When you want to have multiple domains and/or sub domains for one project (such as in the case of Wordpress multi-sites), you will need to customize your virtual host config for this project and make the web server allow to serve your files by different server names.

Each web server virtual host is auto-generated by a tool called vhost-gen. vhost-gen allows you to overwrite its default generation process via templates. Those templates can be added to each project, giving you the option to customize the virtual host of this specific project.

Note

Customized virtual host (vhost-gen): Ensure you have read and understand how to customize your virtual host with vhost-gen.
HTTPD_TEMPLATE_DIR: Ensure you know what this variable does inside your .env file.

Important

When adjusting vhost-gen templates for a project you have to do one of the following:

Restart the devilbox
Or rename your project directory to some other name and then rename it back to its original name.

More information here: Apply Changes

Warning

Pay close attention that you do not use TAB (\t) characters for indenting the vhost-gen yaml files. Some editors might automatically indent using TABs, so ensure they are replaced with spaces. If TAB characters are present, those files become invalid and won’t work. https://github.com/cytopia/devilbox/issues/142

You can use the bundled yamllint binary inside the container to validate your config.

See also:

Prerequisite ¶

Let’s assume the following settings.

Variable	Value
Devilbox path	`/home/user/devilbox`
HTTPD_TEMPLATE_DIR	`.devilbox`
HOST_PATH_HTTPD_DATADIR	`./data/www`
TLD_SUFFIX	`loc`
Project name/directory	`project-1` (Ensure it exist)

Ensure that the default vhost-gen templates have been copied to your projects template directory:

# Navigate to the Devilbox directory
host> cd ./home/user/devilbox

# Create template directory in your project
host> mkdir ./data/www/project-1/.devilbox

# Copy vhost-gen templates
host> cp templates/vhost-gen/* ./data/www/project-1/.devilbox

By having done all prerequisite, your project should be available under http://my-project-1.loc

Now you are all set and we can dive into the actual configuration.

Apache 2.2 ¶

Adding `www` sub domain ¶

Let’s also make this project available under http://www.my-project-1.loc

Step 1: Add DNS entry ¶

The first step would be to add an additional DNS entry for www.my-project-1.loc. See here how to do that for Linux, MacOS or Windows: Step 4: create a DNS entry

DNS is in place, however when you visit http://www.my-project-1.loc, you will end up seeing the Devilbox intranet, because this is the default host when no match has been found.

Step 2: Adjust apache22.yml ¶

Next you will have to adjust the Apache 2.2 vhost configuration template. The current default template looks similar to the one shown below (Note: Only the vhost: sub section is shown here).

/home/user/devilbox/data/www/project-1/.devilbox/apache22.yml¶

vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName   __VHOST_NAME__

      CustomLog  "__ACCESS_LOG__" combined
      ErrorLog   "__ERROR_LOG__"

  __VHOST_DOCROOT__
  __VHOST_RPROXY__
  __PHP_FPM__
  __ALIASES__
  __DENIES__
  __SERVER_STATUS__
      # Custom directives
  __CUSTOM__
  </VirtualHost>

All you will have to do, is to add another ServerName directive:

/home/user/devilbox/data/www/project-1/.devilbox/apache22.yml¶

vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName   __VHOST_NAME__
      ServerName   www.__VHOST_NAME__

      CustomLog  "__ACCESS_LOG__" combined
      ErrorLog   "__ERROR_LOG__"

  __VHOST_DOCROOT__
  __VHOST_RPROXY__
  __PHP_FPM__
  __ALIASES__
  __DENIES__
  __SERVER_STATUS__
      # Custom directives
  __CUSTOM__
  </VirtualHost>

Step 3: Apply new changes ¶

The last step is to actually to apply those changes. This is equal for all web servers. Go to Apply changes and follow the steps.

Afterwards you can go and visit http://www.my-project-1.loc and you should see the same page as if you visit http://my-project-1.loc

Adding catch-all sub domain ¶

Let’s also make this project available under any sub domain.

Step 1: Add DNS entry ¶

The first step would be to add DNS entries for all sub domains you require. See here how to do that for Linux, MacOS or Windows: Step 4: create a DNS entry

This however is not really convenient. If you have basically infinite sub domains (via catch-all), you should consider using Auto-DNS instead: Auto-DNS.

Step 2: Adjust apache22.yml ¶

Next you will have to adjust the Apache 2.2 vhost configuration template. The current default template looks similar to the one shown below (Note: Only the vhost: sub section is shown here).

/home/user/devilbox/data/www/project-1/.devilbox/apache22.yml¶

vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName   __VHOST_NAME__

      CustomLog  "__ACCESS_LOG__" combined
      ErrorLog   "__ERROR_LOG__"

  __VHOST_DOCROOT__
  __VHOST_RPROXY__
  __PHP_FPM__
  __ALIASES__
  __DENIES__
  __SERVER_STATUS__
      # Custom directives
  __CUSTOM__
  </VirtualHost>

All you will have to do, is to add another ServerName directive which does catch-all:

/home/user/devilbox/data/www/project-1/.devilbox/apache22.yml¶

vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName   __VHOST_NAME__
      ServerName   *.__VHOST_NAME__

      CustomLog  "__ACCESS_LOG__" combined
      ErrorLog   "__ERROR_LOG__"

  __VHOST_DOCROOT__
  __VHOST_RPROXY__
  __PHP_FPM__
  __ALIASES__
  __DENIES__
  __SERVER_STATUS__
      # Custom directives
  __CUSTOM__
  </VirtualHost>

Step 3: Apply new changes ¶

The last step is to actually to apply those changes. This is equal for all web servers. Go to Apply changes and follow the steps.

Apache 2.4 ¶

The procedure for Apache 2.4 is exactly the same as for Apache 2.2, even the syntax is identical. The only difference is that you need to adjust apache24.yml instead of apache22.yml.

Just go up one section: Apache 2.2

Nginx ¶

The procedure for Nginx is also exactly the same as for Apache 2.4, however the syntax of its nginx.yml file is slightly different, that’s why the whole tutorial will be repeated here fitted for Nginx.

Adding `www` sub domain ¶

Let’s also make this project available under http://www.my-project-1.loc

Step 1: Add DNS entry ¶

The first step would be to add an additional DNS entry for www.my-project-1.loc. See here how to do that for Linux, MacOS or Windows: Step 4: create a DNS entry

DNS is in place, however when you visit http://www.my-project-1.loc, you will end up seeing the Devilbox intranet, because this is the default host when no match has been found.

Step 2: Adjust nginx.yml ¶

Next you will have to adjust the Nginx vhost configuration template. The current default template looks similar to the one shown below (Note: Only the vhost: sub section is shown here).

/home/user/devilbox/data/www/project-1/.devilbox/nginx.yml¶

vhost: |
  server {
      listen       __PORT____DEFAULT_VHOST__;
      server_name  __VHOST_NAME__;

      access_log   "__ACCESS_LOG__" combined;
      error_log    "__ERROR_LOG__" warn;

  __VHOST_DOCROOT__
  __VHOST_RPROXY__
  __PHP_FPM__
  __ALIASES__
  __DENIES__
  __SERVER_STATUS__
      # Custom directives
  __CUSTOM__
  }

All you will have to do, is to extend the server_name directive:

/home/user/devilbox/data/www/project-1/.devilbox/nginx.yml¶

vhost: |
  server {
      listen       __PORT____DEFAULT_VHOST__;
      server_name  __VHOST_NAME__ www.__VHOST_NAME__;

      access_log   "__ACCESS_LOG__" combined;
      error_log    "__ERROR_LOG__" warn;

  __VHOST_DOCROOT__
  __VHOST_RPROXY__
  __PHP_FPM__
  __ALIASES__
  __DENIES__
  __SERVER_STATUS__
      # Custom directives
  __CUSTOM__
  }

Step 3: Apply new changes ¶

The last step is to actually to apply those changes. This is equal for all web servers. Go to Apply changes and follow the steps.

Afterwards you can go and visit http://www.my-project-1.loc and you should see the same page as if you visit http://my-project-1.loc

Adding catch-all sub domain ¶

Let’s also make this project available under any sub domain.

Step 1: Add DNS entry ¶

The first step would be to add DNS entries for all sub domains you require. See here how to do that for Linux, MacOS or Windows: Step 4: create a DNS entry

This however is not really convenient. If you have basically infinite sub domains (via catch-all), you should consider using Auto-DNS instead: Auto-DNS.

Step 2: Adjust nginx.yml ¶

Next you will have to adjust the Nginx vhost configuration template. The current default template looks similar to the one shown below (Note: Only the vhost: sub section is shown here).

/home/user/devilbox/data/www/project-1/.devilbox/nginx.yml¶

vhost: |
  server {
      listen       __PORT____DEFAULT_VHOST__;
      server_name  __VHOST_NAME__;

      access_log   "__ACCESS_LOG__" combined;
      error_log    "__ERROR_LOG__" warn;

  __VHOST_DOCROOT__
  __VHOST_RPROXY__
  __PHP_FPM__
  __ALIASES__
  __DENIES__
  __SERVER_STATUS__
      # Custom directives
  __CUSTOM__
  }

All you will have to do, is to extend the server_name directive with a catch-all:

/home/user/devilbox/data/www/project-1/.devilbox/nginx.yml¶

vhost: |
  server {
      listen       __PORT____DEFAULT_VHOST__;
      server_name  __VHOST_NAME__ *.__VHOST_NAME__;

      access_log   "__ACCESS_LOG__" combined;
      error_log    "__ERROR_LOG__" warn;

  __VHOST_DOCROOT__
  __VHOST_RPROXY__
  __PHP_FPM__
  __ALIASES__
  __DENIES__
  __SERVER_STATUS__
      # Custom directives
  __CUSTOM__
  }

Step 3: Apply new changes ¶

The last step is to actually to apply those changes. This is equal for all web servers. Go to Apply changes and follow the steps.

Apply changes ¶

After having edited your vhost-gen template files, you still need to apply these changes. This can be achieved in two ways:

Restart the Devilbox
Rename your project directory back and forth

Let’s cover the second step

# Navigate to the data directory
host> /home/user/devilbox/data/www

# Rename your project to something else
host> mv project-1 project-1.tmp

# Rename your project to its original name
host> mv project-1.tmp project-1

If you want to understand what is going on right now, check the docker logs for the web server.

# Navigate to the devilbox directory
host> /home/user/devilbox

# Check docker logs
host> docker-compose logs httpd

httpd_1  | vhostgen: [2018-03-18 11:46:52] Adding: project-1.tmp.loc
httpd_1  | watcherd: [2018-03-18 11:46:52] [OK]  ADD: succeeded: /shared/httpd/project-1.tmp
httpd_1  | watcherd: [2018-03-18 11:46:52] [OK]  DEL: succeeded: /shared/httpd/project-1
httpd_1  | watcherd: [2018-03-18 11:46:52] [OK]  TRIGGER succeeded: /usr/local/apache2/bin/httpd -k restart

httpd_1  | vhostgen: [2018-03-18 11:46:52] Adding: project-1loc
httpd_1  | watcherd: [2018-03-18 11:46:52] [OK]  ADD: succeeded: /shared/httpd/project-1
httpd_1  | watcherd: [2018-03-18 11:46:52] [OK]  DEL: succeeded: /shared/httpd/project-1.tmp
httpd_1  | watcherd: [2018-03-18 11:46:52] [OK]  TRIGGER succeeded: /usr/local/apache2/bin/httpd -k restart

What happened?

The directory changes have been noticed and a new virtual host has been created. This time however your new vhost-gen template has been read and the changes have applied.

Checklist ¶

Template files are copied from templates/vhost-gen/* to your project template dir (as specified in .env via HTTPD_TEMPLATE_DIR)
Ensure the vhost-gen yaml files are valid (No tab characters)
When templates are edited, the Devilbox is either restarted or the project directory is renamed to something else and then renamed back to its original name

Change container versions¶

One of the core concepts of the Devilbox is to easily change between different versions of a specific service.

Table of Contents

Change PHP version
Change whatever version
Checklist

Change PHP version ¶

Stop the Devilbox ¶

Shut down the Devilbox in case it is still running:

# Navigate to the Devilbox directory
host> /home/user/devilbox

# Stop all container
host> docker-compose stop

Edit the `.env` file ¶

Open the .env file with your favourite editor and navigate to the PHP_SERVER section. It will look something like this:

.env¶

 #PHP_SERVER=5.4
 #PHP_SERVER=5.5
 #PHP_SERVER=5.6
 #PHP_SERVER=7.0
 PHP_SERVER=7.1
 #PHP_SERVER=7.1

As you can see, all available values are already there, but commented. Only one is uncommented. In this example it is 7.1, which is the PHP version that will be started, once the Devilbox starts.

To change this, simply uncomment your version of choice and save this file. Do not forget to comment (disable) any other version.

In order to enable PHP 5.5, you would change the .env file like this:

.env¶

 #PHP_SERVER=5.4
 PHP_SERVER=5.5
 #PHP_SERVER=5.6
 #PHP_SERVER=7.0
 #PHP_SERVER=7.1
 #PHP_SERVER=7.1

Start the Devilbox ¶

Now save the file and you can start the Devilbox again.

# Navigate to the Devilbox directory
host> /home/user/devilbox

# Stop all container
host> docker-compose up php httpd bind

See also

Start the Devilbox

Gotchas ¶

If two versions are uncommented, always the last one takes precedence.

Consider this .env file:

.env¶

 #PHP_SERVER=5.4
 PHP_SERVER=5.5
 #PHP_SERVER=5.6
 PHP_SERVER=7.0
 #PHP_SERVER=7.1
 #PHP_SERVER=7.1

Both, PHP 5.4 and PHP 7.0 are uncommented, however, when you start the Devilbox, it will use PHP 7.0 as this value overwrites any previous ones.

Change whatever version ¶

When you have read how to change the PHP version, it should be fairly simple to change any service version. It behaves in the exact same way.

The variable names of all available services with changable versions are in the following format: <SERVICE>_SERVER. Just look through the .env file.

See also

The following variables control service versions:: PHP_SERVER, HTTPD_SERVER, MYSQL_SERVER, PGSQL_SERVER, REDIS_SERVER, MEMCD_SERVER, MONGO_SERVER

Checklist ¶

Stop the Devilbox
Uncomment version of choice in .env
Start the Devilbox

Work inside the container¶

The Devilbox allows you to completely work inside the PHP container (no matter what version), instead of your host operating system.

This brings a lot of advantages, such as that you don’t have to install any development tool on your OS or if you are on Windows, you get a full blown Linux environment.

Additionally, special port-bindings and forwards are in place that allows you to even interchangably work locally or inside the container without having to alter any php config for database and other connections.

See also

https://xdebug.org/docs/all_settings

Table of Contents

Enter the container
- Entering from Linux or MacOS: shell.sh
- Entering from Windows: shell.bat
Inside the container
- devilbox user
- root user
Leave the container
Host to Container mappings
Checklist

Enter the container ¶

Entering the computer is fairly simple. The Devilbox ships with two scripts to do that. One for Linux and MacOS (shell.sh) and another one for Windows (shell.bat).

Entering from Linux or MacOS: `shell.sh`¶

# Navigate to the Devilbox directory
host> cd /path/to/devilbox

# Run provided script
host> ./shell.sh

# Now you are inside the PHP Linux container
devilbox@php-7.0.19 in /shared/httpd $

Entering from Windows: `shell.bat`¶

# Navigate to the Devilbox directory
C:/> cd C:/Users/user1/devilbox

# Run provided script
C:/Users/user1/devilbox> shell.bat

# Now you are inside the PHP Linux container
devilbox@php-7.0.19 in /shared/httpd $

Inside the container ¶

`devilbox` user ¶

By using the provided scripts to enter the container you will become the user devilbox. This user will have the same uid and gid as the user from your host operating system.

So no matter what files or directories you create inside the container, they will have the same permissions and uid/gid set your host operating system. This of course also works the other way round.

The uid and gid mappings are controlled via two .env variables called NEW_UID and NEW_GID

See also

If you want to find out more about synronized container permissions read up here: Syncronize container permissions

`root` user ¶

Sometimes however it is also necessary to do some actions that require super user privileges. You can always become root inside the container by either impersonating it or by using sudo to issue commands.

By default sudo is configured to be used without passwords, so you can simply do the following:

# As user devilbox inside the container
devilbox@php-7.0.19 in /shared/httpd $ sudo su -

# You are now the root user
root@php-7.0.19 in /shared/httpd $

You can also use sudo to run commands with root privileges without having to become root first.

# As user devilbox inside the container
devilbox@php-7.0.19 in /shared/httpd $ sudo apt update
devilbox@php-7.0.19 in /shared/httpd $ sudo apt install nmap

Leave the container ¶

When you are inside the container and want to return to your host operating, just type exit and you are out.

# As user devilbox inside the container
devilbox@php-7.0.19 in /shared/httpd $ exit

# You are now back on your host operating system
host>

Host to Container mappings ¶

This section will give you an idea that there is actually no difference from inside the container and on your host operating system. Directory permissions, IP addresses, ports and DNS entries are fully syncronized allowing you to switch between container and host without having to change any settings.

File and directory Permissions ¶

The username inside the container (devilbox) might be different from your local host operating system username, however its actual uid and gid will match. This is to ensure file and directory permissions are synronized inside and outside the container and no matter from which side you create files and directories, it will always look as if they are owned by your system user.

The uid and gid mappings are controlled via two .env variables called NEW_UID and NEW_GID

Directory mappings ¶

One thing you should understand is the relation between the directories on your host operating system and the corresponding directory inside the PHP container.

The location of the data directory (HOST_PATH_HTTPD_DATADIR) on your host computer is controlled via the HOST_PATH_HTTPD_DATADIR variable inside the .env file. No matter what location you set it to, inside the container it will always be mapped to /shared/httpd.

See the following table for a few examples:

	Host operating system	Inside PHP container
Data dir	`./www/data`	`/shared/httpd`
Data dir	`/home/user1/www`	`/shared/httpd`
Data dir	`/var/www`	`/shared/httpd`

IP address mappings ¶

The following table shows a mapping of IP addresses of available service from the perspective of your host operating system and from within the PHP container.

Service	IP from host os	IP from within PHP container
PHP	`127.0.0.1`	`127.0.0.1`
Apache/Nginx	`127.0.0.1`	`127.0.0.1`
MySQL	`127.0.0.1`	`127.0.0.1`
PostgreSQL	`127.0.0.1`	`127.0.0.1`
Redis	`127.0.0.1`	`127.0.0.1`
Memcached	`127.0.0.1`	`127.0.0.1`
MongoDB	`127.0.0.1`	`127.0.0.1`

As you can see, everyhing is available under 127.0.0.1.

The PHP container is using socat to forward the services from all other available containers to its own 127.0.0.1 address.

An example to access the MySQL database from either host or within the PHP container is the same:

# Access MySQL from your host operating system
host> mysql -h 127.0.0.1

# Access MySQL from within the PHP container
devilbox@php-7.0.19 in /shared/httpd $ mysql -h 127.0.0.1

Important

Do not use localhost to access the services, it does not map to 127.0.0.1 on all cases.

So when setting up a configuration file from your PHP project you would for example use 127.0.0. as the host for your MySQL database connection:

<?php
// MySQL server connection
mysql_host = '127.0.0.1';
mysql_port = '3306';
mysql_user = 'someusername';
mysql_pass = 'somepassword';
?>

Imagine your PHP framework ships a command line tool to run database migration. You could run it from your host operating system or from within the PHP container. It would work from both sides as the connection to the database is exactly the same locally or within the container.

You could also even switch between the Devilbox and a locally installed LAMP stack and still use the same configuration.

Warning

The mapping of 127.0.0.1 to your host operating system does not work with Docker Toolbox.

Port mappings ¶

By default, ports are also synronized between host operating system (the ports that are exposed) and the ports within the PHP container. This is however also configurable inside the .env file.

Service	Port from host os	Port from within PHP container
PHP	NA	`9000`
Apache/Nginx	`80`	`80`
MySQL	`3306`	`3306`
PostgreSQL	`5432`	`5432`
Redis	`6379`	`6379`
Memcached	`11211`	`11211`
MongoDB	`27017`	`27017`

DNS mappings ¶

All project DNS records are also available from inside the PHP container independent of the value of TLD_SUFFIX.

The PHP container is hooked up by default to the bundled DNS server and makes use Auto-DNS.

See also

You can achieve the same on your host operating system by explicitly enabling auto-dns. See also: Auto-DNS.

Checklist ¶

You know how to enter the PHP container
You know how to become root inside the PHP container
You know how to leave the container
You know that file and directory permissions are synronized
You know that 127.0.0.1 is available on your host and inside the PHP container
You know that ports are the same inside the container and on your host os
You know that project urls are available inside the container and on your host
You know about the limitations of Docker Toolbox

Enable Xdebug¶

This tutorial shows you how to enable and use Xdebug with the Devilbox.

See also

If you are unsure of how to add custom *.ini files to the Devilbox, have a look at this section first: php.ini

Table of Contents

Enable Xdebug ¶

This section shows you the minimum required *.ini ini settings to get xdebug to work with the Devilbox. It will also highlight the differences between operating system and Docker versions.

See also

See here for how to add the *.ini values to the Devilbox: php.ini.

Once you have configured Xdebug, you can verify it at the Devilbox intranet: http://localhost/info_php.php

Required for all OS ¶

Additionally to the specific configurations for each operating system and Docker version you will probably also want to add the following to your ini file:

xdebug.ini¶

xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_handler=dbgp
xdebug.remote_port=9000
xdebug.remote_autostart=1
xdebug.idekey="PHPSTORM"
xdebug.remote_log=/var/log/php/xdebug.log

See also

default_enable ¶

By enabling this, stacktraces will be shown by default on an error event. It is advisable to leave this setting set to 1.

remote_enable ¶

This switch controls whether Xdebug should try to contact a debug client which is listening on the host and port as set with the settings xdebug.remote_host and xdebug.remote_port. If a connection can not be established the script will just continue as if this setting was 0.

remote_handler ¶

Can be either 'php3' which selects the old PHP 3 style debugger output, 'gdb' which enables the GDB like debugger interface or 'dbgp' - the debugger protocol. The DBGp protocol is the only supported protocol.

Note: Xdebug 2.1 and later only support 'dbgp' as protocol.

remote_port ¶

The port to which Xdebug tries to connect on the remote host. Port 9000 is the default for both the client and the bundled debugclient. As many clients use this port number, it is best to leave this setting unchanged.

remote_autostart ¶

Normally you need to use a specific HTTP GET/POST variable to start remote debugging (see Remote Debugging). When this setting is set to 1, Xdebug will always attempt to start a remote debugging session and try to connect to a client, even if the GET/POST/COOKIE variable was not present.

idekey ¶

Controls which IDE Key Xdebug should pass on to the DBGp debugger handler. The default is based on environment settings. First the environment setting DBGP_IDEKEY is consulted, then USER and as last USERNAME. The default is set to the first environment variable that is found. If none could be found the setting has as default ‘’. If this setting is set, it always overrides the environment variables.

For the sake of this tutorial we are going to use PHPSTORM as an example value.

remote_log ¶

Keep the exact path of /var/log/php/xdebug.log. You will then have the log file available in the Devilbox log directory of the PHP version for which you have configured Xdebug.

Important

You can set the value of xdebug.idekey to whatever you like, however it is important to remember what value you have set. Throughout the examples in this tutorial it is assumed, that the value is PHPSTORM.

Linux ¶

xdebug.ini¶

xdebug.remote_connect_back=1

MacOS (Docker for Mac)¶

Docker 18.03.0-ce+ and Docker compose 1.20.1+

xdebug.ini¶

xdebug.remote_host=host.docker.internal
xdebug.remote_connect_back=0

Docker 17.12.0-ce+ and Docker compose 1.18.0+

xdebug.ini¶

xdebug.remote_host=docker.for.mac.host.internal
xdebug.remote_connect_back=0

Docker 17.06.0-ce+ and Docker compose 1.14.0+

xdebug.ini¶

xdebug.remote_host=docker.for.mac.localhost
xdebug.remote_connect_back=0

If you have older versions, upgrade.

MacOS (Docker Toolbox)¶

Warning

This is a legacy solution, upgrade to Docker for Mac https://docs.docker.com/toolbox

Windows (Docker for Windows)¶

Docker 18.03.0-ce+ and Docker compose 1.20.1+

xdebug.ini¶

xdebug.remote_host=docker.for.win.host.internal
xdebug.remote_connect_back=0

Docker 17.06.0-ce+ and Docker compose 1.14.0+

xdebug.ini¶

xdebug.remote_host=docker.for.win.host.localhost
xdebug.remote_connect_back=0

If you have older versions, upgrade.

Windows (Docker Toolbox)¶

Warning

This is a legacy solution, upgrade to Docker for Windows https://docs.docker.com/toolbox

Configure your IDE ¶

Required for all IDE ¶

Path mapping ¶

The path mapping is a mapping between the file path on your host operating system and the one inside the PHP Docker container.

The path on your host operating system is the one you have set in HOST_PATH_HTTPD_DATADIR. In case you have set a relative path in .env, ensure to retrieve the absolute path of it when setting up your IDE config.

The path inside the PHP Docker container is always /shared/httpd.

Important

Even though your path in .env for HOST_PATH_HTTPD_DATADIR might be relative (e.g. ./data/www), you need to get the actualy absolute path of it, when setting up your IDE.

IDE key ¶

This is the value you have set in xdebug.ini for xdebug.idekey. In the example of this tutorial, the value was set to PHPSTORM.

Port ¶

This is the value you have set in xdebug.ini for xdebug.remote_port. In the example of this tutorial, the value was set to 9000.

Atom ¶

Install php-debug
Configure config.cson (File -> Config…)
Adjust your xdebug.ini

For Atom, you need to provide a different xdebug.idekey in your php.ini file xdebug.ini:

xdebug.ini¶

xdebug.idekey=xdebug.atom

Linux ¶

launch.json¶

"php-debug":
 {
   ServerPort: 9000
   PathMaps: [
     "remotepath;localpath"
     "/shared/httpd;/home/cytopia/repo/devilbox/data/www"
   ]
 }

MacOS (Docker for Mac)¶

Todo

Help needed. Please provide your config.

MacOS (Docker Toolbox)¶

Todo

Help needed. Please provide your config.

Windows (Docker for Windows)¶

Todo

Help needed. Please provide your config.

Windows (Docker Toolbox)¶

Todo

Help needed. Please provide your config.

PHPStorm ¶

Linux ¶

Enable Xdebug for the port set in xdebug.ini:

Create a new PHP server and set a path mapping. This tutorial assumes your local Devilbox projects to be in ./data/www of the Devilbox git directory:

_images/xdebug_phpstorm_path_mapping.png

Set DBGp proxy settings:

MacOS (Docker for Mac)¶

Todo

Help needed. Please provide your config.

MacOS (Docker Toolbox)¶

Todo

Help needed. Please provide your config.

Windows (Docker for Windows)¶

Todo

Help needed. Please provide your config.

Windows (Docker Toolbox)¶

Todo

Help needed. Please provide your config.

Sublime Text 3 ¶

Install Xdebug Client via the Sublime Package Control.
Configure Xdebug.sublime-settings (Tools -> Xdebug -> Settings - User)

Linux ¶

Xdebug-sublime-settings¶

{
    "path_mapping": {
        "/shared/httpd" : "/home/cytopia/repo/devilbox/data/www"
    },
    "url": "",
    "ide_key": "PHPSTORM",
    "host": "0.0.0.0",
    "port": 9000
}

MacOS (Docker for Mac)¶

Todo

Help needed. Please provide your config.

MacOS (Docker Toolbox)¶

Todo

Help needed. Please provide your config.

Windows (Docker for Windows)¶

Todo

Help needed. Please provide your config.

Windows (Docker Toolbox)¶

Todo

Help needed. Please provide your config.

Visual Studio Code ¶

Install vscode-php-debug
Configure launch.json

Linux ¶

launch.json¶

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xbebug",
            "type": "php",
            "request": "launch",
            "port": 9000,
            "serverSourceRoot": "/shared/httpd",
            "localSourceRoot": "/home/cytopia/repo/devilbox/data/www"
        }, {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9000
        }
    ]
}

MacOS (Docker for Mac)¶

Todo

Help needed. Please provide your config.

MacOS (Docker Toolbox)¶

Todo

Help needed. Please provide your config.

Windows (Docker for Windows)¶

Todo

Help needed. Please provide your config.

Windows (Docker Toolbox)¶

Todo

Help needed. Please provide your config.

Custom environment variables¶

If your application requires a variable to determine if it is run under development or production, you can easily add it and make PHP aware of it.

Table of Contents

Add custom environment variables
Use custom environment variables

Add custom environment variables ¶

This is fairly simple. Any variable inside the .env file is considered an environment variable and automatically known to PHP.

If you for example require a variable APPLICATION_ENV, with a value of production, you would add the following to the .env file:

.env¶

APPLICATION_ENV=production

You need to restart the Devilbox for the changes to take effect.

Note

There is already a proposed section inside the .env file at the very bottom to add you custom variables to differentiate them from the Devilbox required variables.

Use custom environment variables ¶

Accessing the above defined environment variable on the PHP side is also fairly simple. You can use the PHP’s built-in function getenv to obtain the value:

index.php¶

<?php
// Example use of getenv()
echo getenv('APPLICATION_ENV');
?>

Static Code Analysis¶

This tutorial gives you a general overview how to do static code analysis from within the PHP container.

See also

Table of Contents

Awesome-ci
PHPCS
ESLint

Awesome-ci ¶

Awesome-ci is a collection of tools for analysing your workspace and its files. You can for example check for:

git conflicts
git ignored files that have not been removed from the git index
trailing spaces and newlines
non-utf8 files or utf8 files with bom
windows line feeds
null-byte characters
empty files
syntax errors for various languages
inline css or js code
customized regex

Some of the bundled tools even allow for automatic fixing.

See also

awesome-ci

# 1. Enter your PHP container
host> ./bash

# 2. Go to your project folder
devilbox@php-7.0.20 $ cd /shared/httpd/my-project

# 3. Run the tools
devilbox@php-7.0.20 $ git-conflicts --path=.
devilbox@php-7.0.20 $ git-ignored --path=.
devilbox@php-7.0.20 $ file-cr --path=.
devilbox@php-7.0.20 $ file-crlf --path=.
devilbox@php-7.0.20 $ file-empty --path=.

# 4. Run tools with more options
devilbox@php-7.0.20 $ syntax-php --path=. --extension=php
devilbox@php-7.0.20 $ syntax-php --path=. --shebang=php

# 5. Various syntax checks
devilbox@php-7.0.20 $ syntax-bash --path=. --text --extension=sh
devilbox@php-7.0.20 $ syntax-css --path=. --text --extension=css
devilbox@php-7.0.20 $ syntax-js --path=. --text --extension=js
devilbox@php-7.0.20 $ syntax-json --path=. --text --extension=json
devilbox@php-7.0.20 $ syntax-markdown --path=. --text --extension=md
devilbox@php-7.0.20 $ syntax-perl --path=. --text --extension=pl
devilbox@php-7.0.20 $ syntax-php --path=. --text --extension=php
devilbox@php-7.0.20 $ syntax-python --path=. --text --extension=python
devilbox@php-7.0.20 $ syntax-ruby --path=. --text --extension=rb
devilbox@php-7.0.20 $ syntax-scss --path=. --text --extension=scss

PHPCS ¶

PHPCS is a code style analyser for PHP.

See also

PHPCS

# 1. Enter your PHP container
host> ./bash

# 2. Go to your project folder
devilbox@php-7.0.20 $ cd /shared/httpd/my-project

# 3. Run it
devilbox@php-7.0.20 $ phpcs .

ESLint ¶

ESLint is a Javascript static source code analyzer.

See also

ESLint

# 1. Enter your PHP container
host> ./bash

# 2. Go to your project folder
devilbox@php-7.0.20 $ cd /shared/httpd/my-project

# 3. Run it
devilbox@php-7.0.20 $ eslint .

Setup CakePHP¶

This example will use composer to install CakePHP from within the PHP container.

See also

Official CakePHP Documentation

Table of Contents

Overview
Walk through

Overview ¶

The following configuration will be used:

Project name	VirtualHost directory	Database	TLD_SUFFIX	Project URL
my-cake	/shared/httpd/my-cake	my_cake	loc	http://my-cake.loc

Walk through ¶

It will be ready in eight simple steps:

Enter the PHP container
Create a new VirtualHost directory
Install CakePHP via composer
Symlink webroot directory
Add MySQL database
Configure datbase connection
Setup DNS record
Visit http://my-cake.loc in your browser

See also

1. Enter the PHP container ¶

host> ./shell.sh

See also

Official Drupal Documentation

2. Create new vhost directory ¶

devilbox@php-7.0.20 in /shared/httpd $ mkdir my-cake

3. Install CakePHP ¶

devilbox@php-7.0.20 in /shared/httpd $ cd my-cake
devilbox@php-7.0.20 in /shared/httpd/my-cake $ composer create-project --prefer-dist cakephp/app cakephp

4. Symlink webroot ¶

devilbox@php-7.0.20 in /shared/httpd/my-cake $ ln -s cakephp/webroot/ htdocs

5. Add MySQL Database ¶

devilbox@php-7.0.20 in /shared/httpd/my-cake $ mysql -u root -h 127.0.0.1 -p -e 'CREATE DATABASE my_cake;'

6. Configure database connection ¶

devilbox@php-7.0.20 in /shared/httpd/my-cake $ vi cakephp/config/app.php

cakephp/config/app.php¶

 <?php
   'Datasources' => [
         'default' => [
             'className' => 'Cake\Database\Connection',
             'driver' => 'Cake\Database\Driver\Mysql',
             'persistent' => false,
             'host' => '127.0.0.1',
             /**
              * CakePHP will use the default DB port based on the driver selected
              * MySQL on MAMP uses port 8889, MAMP users will want to uncomment
              * the following line and set the port accordingly
              */
             //'port' => 'non_standard_port_number',
             'username' => 'root',
             'password' => 'secret',
             'database' => 'my_cake',
             'encoding' => 'utf8',
             'timezone' => 'UTC',
             'flags' => [],
             'cacheMetadata' => true,
 ?>

7. DNS record ¶

If you do not have Auto-DNS configured, you will need to add the following line to your host operating systems /etc/hosts file (or C:\Windows\System32\drivers\etc on Windows):

/etc/hosts¶

 127.0.0.1 my-cake.loc

See also

For in-depth info about adding DNS records on Linux, Windows or MacOS see: DNS records or Auto-DNS.

8. Open your browser ¶

All set now, you can visit http://my-cake.loc in your browser.

Setup Drupal¶

This example will use drush to install Drupal from within the PHP container.

See also

Table of Contents

Overview
Walk through

Overview ¶

The following configuration will be used:

Project name	VirtualHost directory	Database	TLD_SUFFIX	Project URL
my-drupal	/shared/httpd/my-drupal	my_drupal	loc	http://my-drupal.loc

Walk through ¶

It will be ready in six simple steps:

Enter the PHP container
Create a new VirtualHost directory
Install Drupal via drush
Symlink webroot directory
Setup DNS record
Visit http://my-drupal.loc in your browser

See also

1. Enter the PHP container ¶

host> ./shell.sh

See also

Official Joomla Documentation

2. Create new vhost directory ¶

devilbox@php-7.0.20 in /shared/httpd $ mkdir my-drupal

3. Install Drupal ¶

devilbox@php-7.0.20 in /shared/httpd $ cd my-drupal
devilbox@php-7.0.20 in /shared/httpd/my-drupal $ drush dl drupal

4. Symlink webroot ¶

devilbox@php-7.0.20 in /shared/httpd/my-drupal $ ln -s drupal-8.3.3/ htdocs

5. DNS record ¶

If you do not have Auto-DNS configured, you will need to add the following line to your host operating systems /etc/hosts file (or C:\Windows\System32\drivers\etc on Windows):

/etc/hosts¶

 127.0.0.1 my-drupal.loc

See also

For in-depth info about adding DNS records on Linux, Windows or MacOS see: DNS records or Auto-DNS.

6. Open your browser ¶

Open your browser at http://my-drupal.loc and follow the Drupal installation steps.

Note

When asked about MySQL hostname, choose 127.0.0.1.

Setup Joomla¶

This example will install Joomla from within the PHP container.

See also

Table of Contents

Overview
Walk through

Overview ¶

The following configuration will be used:

Project name	VirtualHost directory	Database	TLD_SUFFIX	Project URL
my-joomla	/shared/httpd/my-joomla	n.a.	loc	http://my-joomla.loc

Walk through ¶

It will be ready in six simple steps:

Enter the PHP container
Create a new VirtualHost directory
Download and extract Joomla
Symlink webroot directory
Setup DNS record
Visit http://my-joomla.loc in your browser

See also

1. Enter the PHP container ¶

host> ./shell.sh

See also

Official Laravel Documentation

2. Create new vhost directory ¶

devilbox@php-7.0.20 in /shared/httpd $ mkdir my-joomla

3. Download and extract Joomla ¶

devilbox@php-7.0.20 in /shared/httpd $ cd my-joomla
devilbox@php-7.0.20 in /shared/httpd/my-joomla $ wget -O joomla.tar.gz https://downloads.joomla.org/cms/joomla3/3-8-0/joomla_3-8-0-stable-full_package-tar-gz?format=gz
devilbox@php-7.0.20 in /shared/httpd $ mkdir joomla
devilbox@php-7.0.20 in /shared/httpd $ tar xvfz joomla.tar.gz -C joomla/

4. Symlink webroot ¶

devilbox@php-7.0.20 in /shared/httpd/my-joomla $ ln -s joomla/ htdocs

5. DNS record ¶

If you do not have Auto-DNS configured, you will need to add the following line to your host operating systems /etc/hosts file (or C:\Windows\System32\drivers\etc on Windows):

/etc/hosts¶

 127.0.0.1 my-joomla.loc

See also

For in-depth info about adding DNS records on Linux, Windows or MacOS see: DNS records or Auto-DNS.

6. Open your browser ¶

Open your browser at http://my-joomla.loc

Setup Laravel¶

This example will use laravel to install Laravel from within the PHP container.

See also

Table of Contents

Overview
Walk through

Overview ¶

The following configuration will be used:

Project name	VirtualHost directory	Database	TLD_SUFFIX	Project URL
my-laravel	/shared/httpd/my-laravel	n.a.	loc	http://my-laravel.loc

Walk through ¶

It will be ready in six simple steps:

Enter the PHP container
Create a new VirtualHost directory
Install Laravel
Symlink webroot directory
Setup DNS record
Visit http://my-laravel.loc in your browser

See also

1. Enter the PHP container ¶

host> ./shell.sh

See also

Official Phalcon Documentation

2. Create new vhost directory ¶

devilbox@php-7.0.20 in /shared/httpd $ mkdir my-laravel

3. Install Laravel ¶

devilbox@php-7.0.20 in /shared/httpd $ cd my-laravel
devilbox@php-7.0.20 in /shared/httpd/my-laravel $ laravel new laravel-project

4. Symlink webroot ¶

devilbox@php-7.0.20 in /shared/httpd/my-laravel $ ln -s laravel-project/public/ htdocs

5. DNS record ¶

If you do not have Auto-DNS configured, you will need to add the following line to your host operating systems /etc/hosts file (or C:\Windows\System32\drivers\etc on Windows):

/etc/hosts¶

 127.0.0.1 my-laravel.loc

See also

For in-depth info about adding DNS records on Linux, Windows or MacOS see: DNS records or Auto-DNS.

6. Open your browser ¶

Open your browser at http://my-laravel.loc

Setup Phalcon¶

This example will use phalcon to install Phalcon from within the PHP container.

See also

Table of Contents

Overview
Walk through

Overview ¶

The following configuration will be used:

Project name	VirtualHost directory	Database	TLD_SUFFIX	Project URL
my-phalcon	/shared/httpd/my-phalcon	n.a.	loc	http://my-phalcon.loc

Walk through ¶

It will be ready in six simple steps:

Enter the PHP container
Create a new VirtualHost directory
Install Phalcon
Symlink webroot directory
Setup DNS record
Visit http://my-phalcon.loc in your browser

See also

1. Enter the PHP container ¶

host> ./shell.sh

See also

Official Symfony Documentation

2. Create new vhost directory ¶

devilbox@php-7.0.20 in /shared/httpd $ mkdir my-phalcon

3. Install Phalcon ¶

devilbox@php-7.0.20 in /shared/httpd $ cd my-phalcon
devilbox@php-7.0.20 in /shared/httpd/my-phalcon $ phalcon project phalconphp

4. Symlink webroot ¶

devilbox@php-7.0.20 in /shared/httpd/my-pahlcon $ ln -s phalconphp/public/ htdocs

5. DNS record ¶

If you do not have Auto-DNS configured, you will need to add the following line to your host operating systems /etc/hosts file (or C:\Windows\System32\drivers\etc on Windows):

/etc/hosts¶

 127.0.0.1 my-phalcon.loc

See also

For in-depth info about adding DNS records on Linux, Windows or MacOS see: DNS records or Auto-DNS.

6. Open your browser ¶

Open your browser at http://my-phalcon.loc

Setup Symfony¶

This example will use symfony to install Symfony from within the PHP container.

See also

Table of Contents

Overview
Walk through

Overview ¶

The following configuration will be used:

Project name	VirtualHost directory	Database	TLD_SUFFIX	Project URL
my-symfony	/shared/httpd/my-symfony	n.a.	loc	http://my-symfony.loc

Walk through ¶

It will be ready in seven simple steps:

Enter the PHP container
Create a new VirtualHost directory
Install Symfony
Symlink webroot directory
Enable Symfony prod (app.php)
Setup DNS record
Visit http://my-symfony.loc in your browser

See also

1. Enter the PHP container ¶

host> ./shell.sh

See also

Official Wordpress Documentation

2. Create new vhost directory ¶

devilbox@php-7.0.20 in /shared/httpd $ mkdir my-symfony

3. Install Symfony ¶

devilbox@php-7.0.20 in /shared/httpd $ cd my-symfony
devilbox@php-7.0.20 in /shared/httpd/my-symfony $ symfony new symfony

4. Symlink webroot ¶

devilbox@php-7.0.20 in /shared/httpd/my-symfony $ ln -s symfony/web/ htdocs

5. Enable Symfony prod (`app.php`)¶

devilbox@php-7.0.20 in /shared/httpd/my-symfony $ cd symfony/web
devilbox@php-7.0.20 in /shared/httpd/my-symfony/symfony/web $ ln -s app.php index.php

6. DNS record ¶

If you do not have Auto-DNS configured, you will need to add the following line to your host operating systems /etc/hosts file (or C:\Windows\System32\drivers\etc on Windows):

/etc/hosts¶

 127.0.0.1 my-symfony.loc

See also

For in-depth info about adding DNS records on Linux, Windows or MacOS see: DNS records or Auto-DNS.

7. Open your browser ¶

Open your browser at http://my-symfony.loc

Setup Wordpress¶

This example will use git to install Wordpress from within the PHP container.

See also

Table of Contents

Overview
Walk through

Overview ¶

The following configuration will be used:

Project name	VirtualHost directory	Database	TLD_SUFFIX	Project URL
my-wp	/shared/httpd/my-wp	my_wp	loc	http://my-wp.loc

Walk through ¶

It will be ready in six simple steps:

Enter the PHP container
Create a new VirtualHost directory
Download Wordpress via git
Symlink webroot directory
Setup DNS record
Visit http://my-wp.loc in your browser

See also

1. Enter the PHP container ¶

host> ./shell.sh

See also

Official Yii Documentation

2. Create new vhost directory ¶

devilbox@php-7.0.20 in /shared/httpd $ mkdir my-wp

3. Download Wordpress via `git`¶

devilbox@php-7.0.20 in /shared/httpd $ cd my-wp
devilbox@php-7.0.20 in /shared/httpd/my-wp $ git clone https://github.com/WordPress/WordPress wordpress.git

4. Symlink webroot ¶

devilbox@php-7.0.20 in /shared/httpd/my-wp $ ln -s wordpress.git/ htdocs

5. DNS record ¶

If you do not have Auto-DNS configured, you will need to add the following line to your host operating systems /etc/hosts file (or C:\Windows\System32\drivers\etc on Windows):

/etc/hosts¶

 127.0.0.1 my-wp.loc

See also

For in-depth info about adding DNS records on Linux, Windows or MacOS see: DNS records or Auto-DNS.

6. Open your browser ¶

Open your browser at http://my-wp.loc

Setup Yii¶

This example will use composer to install Yii from within the PHP container.

See also

Table of Contents

Overview
Walk through

Overview ¶

The following configuration will be used:

Project name	VirtualHost directory	Database	TLD_SUFFIX	Project URL
my-yii	/shared/httpd/my-yii	n.a.	loc	http://my-yii.loc

Walk through ¶

It will be ready in six simple steps:

Enter the PHP container
Create a new VirtualHost directory
Install Yii2 via composer
Symlink webroot directory
Setup DNS record
Visit http://my-wp.loc in your browser

See also

1. Enter the PHP container ¶

host> ./shell.sh

See also

Official Zend Documentation

2. Create new vhost directory ¶

devilbox@php-7.0.20 in /shared/httpd $ mkdir my-yii

3. Install Yii2 via `composer`¶

devilbox@php-7.0.20 in /shared/httpd $ cd my-yii
devilbox@php-7.0.20 in /shared/httpd/my-yii $ composer create-project --prefer-dist --stability=dev yiisoft/yii2-app-basic yii2-dev

4. Symlink webroot ¶

devilbox@php-7.0.20 in /shared/httpd/my-yii $ ln -s yii2-dev/web/ htdocs

5. DNS record ¶

If you do not have Auto-DNS configured, you will need to add the following line to your host operating systems /etc/hosts file (or C:\Windows\System32\drivers\etc on Windows):

/etc/hosts¶

 127.0.0.1 my-yii.loc

See also

For in-depth info about adding DNS records on Linux, Windows or MacOS see: DNS records or Auto-DNS.

6. Open your browser ¶

Open your browser at http://my-yii.loc

Setup Zend¶

This example will use composer to install Zend from within the PHP container.

See also

Table of Contents

Overview
Walk through

Overview ¶

The following configuration will be used:

Project name	VirtualHost directory	Database	TLD_SUFFIX	Project URL
my-zend	/shared/httpd/my-zend	n.a.	loc	http://my-zend.loc

Walk through ¶

It will be ready in six simple steps:

Enter the PHP container
Create a new VirtualHost directory
Install Zend via composer
Symlink webroot directory
Setup DNS record
Visit http://my-wp.loc in your browser

See also

1. Enter the PHP container ¶

host> ./shell.sh

See also

Communicating with external hosts

2. Create new vhost directory ¶

devilbox@php-7.0.20 in /shared/httpd $ mkdir my-zend

3. Install Zend via `composer`¶

devilbox@php-7.0.20 in /shared/httpd $ cd my-zend
devilbox@php-7.0.20 in /shared/httpd/my-zend $ composer create-project --prefer-dist zendframework/skeleton-application zend

4. Symlink webroot ¶

devilbox@php-7.0.20 in /shared/httpd/my-zend $ ln -s zend/public/ htdocs

5. DNS record ¶

If you do not have Auto-DNS configured, you will need to add the following line to your host operating systems /etc/hosts file (or C:\Windows\System32\drivers\etc on Windows):

/etc/hosts¶

 127.0.0.1 my-zend.loc

See also

For in-depth info about adding DNS records on Linux, Windows or MacOS see: DNS records or Auto-DNS.

6. Open your browser ¶

Open your browser at http://my-zend.loc

DNS records¶

Project DNS records are required, because each project is using its own virtual host with its own unique server name.

The server name is constructed by a <project-directory> and the TLD_SUFFIX and requires the same DNS record to be present in order to access it.

See also

This section gives you an overview about how to create separate DNS records for each project. It has to be done for each project, however if you want to automate the process, refer to Auto-DNS.

Table of Contents

Examples
Creating DNS records
- Native Docker
  - Linux
  - MacOS
  - Windows
- Docker Toolbox
  - MacOS
  - Windows
Verify

Examples ¶

In order to better illustrate the process, we are going to use two projects as an example. See the following table for project directories and TLD_SUFFIX.

Project directory	TLD_SUFFIX	Project URL	Required DNS name
project-1	`loc`	http://project-1.loc	`project-1.loc`
www.project-1	`loc`	http://www.project-1.loc	`www.project-1.loc`

Note

When you have created the above two projects, you can check the vhost page on the Devilbox intranet. It will tell you exactly what DNS record to add.

Important

The IP address 127.0.0.1 is different for Docker Toolbox

Creating DNS records ¶

When creating DNS records for your host operating system, there are two distinctions to be made. If you use Native Docker (the default and recommended Docker), you can always use 127.0.0.1 as your IP address for the DNS record. If however your use Docker Toolbox, you first need to find out the IP address of the Docker Toolbox virtual machine.

See also

Docker Toolbox

Native Docker ¶

Linux ¶

Use your favorite editor and open /etc/hosts with root privileges. The following example uses vim to add the two example DNS records.

host> sudo vim /etc/hosts

127.0.0.1 project-1.loc
127.0.0.1 www.project-1.loc

MacOS ¶

Use your favorite editor and open /etc/hosts with root privileges. The following example uses vim to add the two example DNS records.

host> sudo vim /etc/hosts

127.0.0.1 project-1.loc
127.0.0.1 www.project-1.loc

Windows ¶

On Windows you need to open C:\Windows\System32\drivers\etc with administrative privileges and add the following two lines:

127.0.0.1 project-1.loc
127.0.0.1 www.project-1.loc

Docker Toolbox ¶

When using Docker Toolbox the Devilbox runs inside a virtual machine and therefore the webserver port (80) is not exposed to your host operating system. So your DNS record must point to the virtual machine instead of your host system.

Find out the IP address the virtual machine is running on
Add a DNS entry to your host operating system for this IP address.

For the sake of this example, let’s assume the virtual machine is running on 192.16.0.1

MacOS ¶

Use your favorite editor and open /etc/hosts with root privileges. The following example uses vim to add the two example DNS records.

host> sudo vim /etc/hosts

192.16.0.1 project-1.loc
192.16.0.1 www.project-1.loc

Windows ¶

On Windows you need to open C:\Windows\System32\drivers\etc with administrative privileges and add the following two lines:

192.16.0.1 project-1.loc
192.16.0.1 www.project-1.loc

Verify ¶

After settings the DNS records, you can use the ping command to verify if everything works.

host> ping -c1 project-1.loc

PING project-1.loc (127.0.0.1) 56(84) bytes of data.
64 bytes from localhost (127.0.0.1): icmp_seq=1 ttl=64 time=0.066 ms

host> ping -c1 www.project-1.loc

PING www.project-1.loc (127.0.0.1) 56(84) bytes of data.
64 bytes from localhost (127.0.0.1): icmp_seq=1 ttl=64 time=0.066 ms

Customized virtual host (vhost-gen)¶

Table of Contents

vhost-gen ¶

What is vhost-gen ¶

vhost-gen is a python script which is able to dynamically generate Apache 2.2, Apache 2.4 and Nginx virtual host or reverse proxy configuration files.

It is intended to be used by other means of automation such as change of directories or change of listening ports.

See also

If you intend to use vhost-gen for your own projects, have a look at its projcet page and its sister projects:

Where do I find templates ¶

The latest version of vhost-gen templates are shipped in the Devilbox git directory under templates/vhost-gen. You can however also download them directly from its own git directory.

How does it work ¶

By default new virtual hosts are automatically generated and enabled by vhost-gen and watcherp using the vanilla templates which are glued into the webserver Docker images. The used templates are exactly the same as what you will find in templates/vhost-gen.

This ensures to have equal and sane default virtual host for all of your projects. If you want to have a different virtual host configuration for a specific project of yours, you can copy a corresponding template into your project directory and adjust it to your needs.

How to apply templates to a specific project ¶

Customizing a virtual host via vhost-gen template is generally done in four steps:

Retrieve or set template directory value in .env.
Copy webserver template to project template directory
Adjust template
Make Devilbox pick up those changes

Let’s assume the following default values and one project named project-1:

Variable	Value
Devilbox path	`/home/user/devilbox`
Templates to copy from	`/home/user/devilbox/templates/vhost-gen`
Project name	`project-1`
HTTPD_TEMPLATE_DIR	`.devilbox` (default value)
HOST_PATH_HTTPD_DATADIR	`./data/www` (default value)

Those assumed settings will result in the following directory paths which must be created by you:

What	Path
Project directory path	`/home/user/devilbox/data/www/project-1/`
Project template path	`/home/user/devilbox/data/www/project-1/.devilbox/`

1. Retrieve or set template directory value ¶

By default the HTTPD_TEMPLATE_DIR value is .devilbox. This is defined in the .env file. Feel free to change it to whatever directory name you prefer, but keep in mind that it will change the Project template path which you need to create yourself.

For this example we will keep the default value for the sake of simplicity: .devilxbox.

Note

The HTTPD_TEMPLATE_DIR value is a global setting and will affect all projects.

2. Copy webserver template to project template directory ¶

First you need to ensure that the HTTPD_TEMPLATE_DIR exists wihin you project.

# Navigate to the Devilbox directory
host> cd /home/user/devilbox

# Create template directory in your project
host> mkdir ./data/www/project-1/.devilbox

Then you can copy the templates.

host> cp templates/vhost-gen/* ./data/www/project-1/.devilbox

Note

You actually only need to copy the template of your chosen webserver (either Apache 2.2, Apache 2.4 or Nginx), however it is good practice to copy all templates and also adjust all templates synchronously. This allows you to change web server versions and still keep your virtual host settings.

3. Adjust template ¶

At this stage you can start adjusting the template. Either do that for the webserver version you have enabled via HTTPD_SERVER: /home/user/devilbox/data/www/project-1/.devilbox/apache22.yml. /home/user/devilbox/data/www/project-1/.devilbox/apache24.yml, /home/user/devilbox/data/www/project-1/.devilbox/nginx.yml or do it for all of them synchronously.

Note

What exactly to change will be explained later.

4. Make Devilbox pick up those changes ¶

Whenever you change a project vhost template or the HTTPD_TEMPLATE_DIR value, you need to restart the Devilbox.

Note

It is also possible to do it without a restart which will be explained later.

Templates explained ¶

Before the templates are explained, have a look at the following table to find out what template needs to be in place for what webserver version.

Webserver	Template
Apache 2.2	`apache22.yml`
Apache 2.4	`apache22.yml`
Nginx stable	`nginx.yml`
Nginx mainline	`nginx.yml`

Note

Nginx stable and mainline share the same template as their syntax has no special differences, whereas Apache 2.2 and Apache 2.4 have slight differences in syntax and therefore require two different templates.

Ensure yaml files are valid ¶

Warning

Pay close attention that you do not use TAB (\t) characters for indenting the vhost-gen yaml files. Some editors might automatically indent using TABs, so ensure they are replaced with spaces. If TAB characters are present, those files become invalid and won’t work. https://github.com/cytopia/devilbox/issues/142

You can use the bundled yamllint binary inside the container to validate your config.

 # Navigate to the Devilbox directory
 host> cd /home/user/devilbox

 # Enter the PHP container
 host> ./shell.sh

 # Go to your project's template directory
 devilbox@php-7.0.19 in /shared/httpd $ cd project-1/.devilbox

 # Check the syntax of apache22.yml
 devilbox@php-7.0.19 in /shared/httpd/project-1/.devilbox $ yamllint apache22.yml

 108:81    error    line too long (90 > 80 characters)  (line-length)
 139:81    error    line too long (100 > 80 characters)  (line-length)
 140:81    error    line too long (84 > 80 characters)  (line-length)
 142:81    error    line too long (137 > 80 characters)  (line-length)

Long line errors can safely be ignored.

Template variables ¶

Every uppercase string which begins with __ and ends by __ (such as __PORT__) is a variable that will be replaced by a value. Variables can contain a string, a multi-line string or can also be replaced to an empty value.

Global variables ¶

There are global variables that are determined by the command line arguments of vhost-gen itself or are elsewhere replaced by the Devilbox webserver container such as:

__PORT__
__DEFAULT_VHOST__
__VHOST_NAME__
__ACCESS_LOG__
__ERROR_LOG__

vHost type variable ¶

There are also two variables that will be replaced according to the type of the vhost - either a normal vhost or a reverse proxy vhost.

__VHOST_DOCROOT__
__VHOST_PROXY__

The Devilbox always uses a normal vhost by default, so the __VHOST_DOCROOT__ variable will be replaced by what the vhost_type.docroot section provides. The vhost_type.rproxy will be ignored and __VHOST_PROXY__ will be replaced by an empty string.

Feature variables ¶

All other variables will be replaced by what is provided in the features: section. All subsections of features: have corresponding variables in the following form:

Feature directive	Variable name pattern
`lower_case:`	`__UPPER_CASE__`

As an example, the contents of the features.php_fpm: section will be replaced into the __PHP_FPM__ variable.

Template structure ¶

Each vhost-gen template has three main yaml directives:

vhost:
vhost_type:
features:

1. `vhost:`¶

The vhost: directive will contain the final resulting virtual host configuration that will be applied by the webserver. Each of its containing variables will be substituted and its content will be copied to a webserver configuration file.

By default the vhost: section has variables from global scope, from the vhost_type: section and from the features: section.

You can also fully hard-code your webserver configuration without any variables. This way you can specify a fully self-brewed webserver configuration. An example for Apache 2.2 could look like this:

vhost: |
  <VirtualHost *:80>
      ServerName   example.com

      CustomLog  "/var/log/apache/access.log" combined
      ErrorLog   "/var/log/apache/error.log"

      DocumentRoot "/shared/httpd/project-1/htdocs"
      <Directory "/shared/httpd/project-1/htdocs">
          DirectoryIndex index.php

          AllowOverride All
          Options All

          RewriteEngine on
          RewriteBase /

          Order allow,deny
          Allow from all
      </Directory>

      ProxyPassMatch ^/(.*\.php(/.*)?)$ fcgi://127.0.0.1:9000/shared/httpd/project-1/htdocs/$1
  </VirtualHost>

2. `vhost_type:`¶

The vhost_type: contains docroot and rproxy. The Devilbox only makes use of docroot which holds the definition of a normal vhost. Its content will be replaced into the __VHOST_DOCROOT__ variable.

The rproxy section will be ignored and the __VHOST_RPROXY__ variable will contain an empty value.

vHost Type section	Variable to be replaced into
`docroot:`	`__VHOST_DOCROOT__`
`rproxy:`	`__VHOST_RPROXY__` (empty)

3. `features:`¶

This section contains directives that will all be replaced into vhost: variables.

Feature section	Variable to be replaced into
`php_fpm:`	`__PHP_FPM__`
`alias:`	`__ALIASES__`
`deny:`	`__DENIES__`
`server_status:`	`__SERVER_STATUS__`
`xdomain_request:`	`__XDOMAIN_REQ__`

Apply Changes ¶

After having edited your vhost-gen template files, you still need to apply these changes. This can be achieved in two ways:

Rename your project directory back and forth
Restart the Devilbox

Rename project directory ¶

# Navigate to the data directory
host> /home/user/devilbox/data/www

# Rename your project to something else
host> mv project-1 project-1.tmp

# Rename your project to its original name
host> mv project-1.tmp project-1

If you want to understand what is going on right now, check the docker logs for the web server.

# Navigate to the devilbox directory
host> /home/user/devilbox

# Check docker logs
host> docker-compose logs httpd

httpd_1  | vhostgen: [2018-03-18 11:46:52] Adding: project-1.tmp.loc
httpd_1  | watcherd: [2018-03-18 11:46:52] [OK]  ADD: succeeded: /shared/httpd/project-1.tmp
httpd_1  | watcherd: [2018-03-18 11:46:52] [OK]  DEL: succeeded: /shared/httpd/project-1
httpd_1  | watcherd: [2018-03-18 11:46:52] [OK]  TRIGGER succeeded: /usr/local/apache2/bin/httpd -k restart

httpd_1  | vhostgen: [2018-03-18 11:46:52] Adding: project-1loc
httpd_1  | watcherd: [2018-03-18 11:46:52] [OK]  ADD: succeeded: /shared/httpd/project-1
httpd_1  | watcherd: [2018-03-18 11:46:52] [OK]  DEL: succeeded: /shared/httpd/project-1.tmp
httpd_1  | watcherd: [2018-03-18 11:46:52] [OK]  TRIGGER succeeded: /usr/local/apache2/bin/httpd -k restart

What happened?

The directory changes have been noticed and a new virtual host has been created. This time however your new vhost-gen template has been read and the changes have applied.

Note

Renaming a project directory will only affect a single project. In case your change the value of HTTPD_TEMPLATE_DIR it will affect all projects and you would have to rename all project directories. In this case it is much faster to just restart the Devilbox.

Restart the Devilbox ¶

Stop the Devilbox and start it up again.

HTTPS (SSL)¶

This page shows you how to use the Devilbox on https and how to import the Certificate Authority into your browser once, so that you always and automatically get valid SSL certificates for all new projects.

SSL certificates are generated automatically and there is nothing to do from your side.

Table of Contents

TL;DR
How does it work
- Certificate Authority
- SSL Certificates
Import the CA into your browser
- Chrome / Chromium
- Firefox
Further Reading

TL;DR ¶

Import the Certificate Authority into your browser and you are all set.

How does it work ¶

Certificate Authority ¶

When the Devilbox starts up for the first time, it will generate a Certificate Authority and will store its public and private key in ./ca/ within the Devilbox git directory.

The keys are only generated if they don’t exist and kept permanently if you don’t delete them manually, i.e. they are not overwritten.

host> cd path/to/devilbox
host> ls -l ca/
-rw-r--r--  1 cytopia cytopia 1558 May  2 11:12 devilbox-ca.crt
-rw-------  1 cytopia cytopia 1675 May  2 11:12 devilbox-ca.key
-rw-r--r--  1 cytopia cytopia   17 May  4 08:35 devilbox-ca.srl

SSL Certificates ¶

Whenever you create a new project directory, multiple things happen in the background:

A new virtual host is created
DNS is provided via Auto-DNS
A new SSL certificate is generated for that vhost
The SSL certificate is signed by the Devilbox Certificate Authority

By having a SSL certificates signed by the provided CA, you will only have to import the CA into your browser ones and all current projects and future projects will automatically have valid and trusted SSL certificates without any further work.

Important

Importing the CA into the browser is also recommended and required for the Devilbox intranet page to work properly.

Import the CA into your browser ¶

Chrome / Chromium ¶

Open Chrome settings, scroll down to the very bottom and click on Advanced to expand the advanced settings.

_images/https-ssl-01-chrome-settings.png

Find the setting Manage certificates and open it.

_images/https-ssl-02-chrome-advanced-settings.png

Navigate to the tab setting AUTHORITIES and click on IMPORT.

_images/https-ssl-03-chrome-authorities.png

Select devilbox-ca.crt from within the Devilbox ./ca directory:

As the last step you are asked what permissions you want to grant the newly importat CA. To make sure it works everywhere, check all options and proceed with OK.

_images/https-ssl-05-chrome-set-trust.png

Now you are all set and all generated SSL certificates will be valid from now on.

Firefox ¶

Open Firefox settings and click on Privacy & Security.

At the very bottom click on the button View Certificates.

_images/https-ssl-02-firefox-security-settings.png

In the Authories tab, click on Import.

_images/https-ssl-03-firefox-authorities.png

Select devilbox-ca.crt from within the Devilbox ./ca directory:

As the last step you are asked what permissions you want to grant the newly importat CA. To make sure it works everywhere, check all options and proceed with OK.

_images/https-ssl-05-firefox-set-trust.png

Now you are all set and all generated SSL certificates will be valid from now on.

Web server¶

This page lists a general overview about the bundled web server - its features, where it comes from, how it is built and what configuration is possible.

Table of Contents

Features
Information
Configuration

Features ¶

Auto-virtual hosts ¶

File permission problem ¶

Custom global configuration ¶

Custom vhost configuration ¶

Information ¶

Dockerfile ¶

Github ¶

Dockerhub ¶

Build process ¶

Configuration ¶

.env file ¶

apache.conf / nginx.conf ¶

vhost-gen ¶

PHP¶

Environment variables

MySQL¶

MongoDB¶

Redis¶

Memcached¶

BIND¶

Devilbox Intranet¶

Auto-DNS¶

If you don’t want to add DNS records manually for every project, you can also use the bundled DNS server and use it’s DNS catch-all feature to have all DNS records automatically available.

Important

By default, the DNS server is set to listen on 1053 to avoid port collisions during startup. You need to change it to 53 in .env via HOST_PORT_BIND.

Table of Contents

Native Docker
- Prerequisites
- Linux
- MacOS
- Windows
Docker Toolbox
- MacOS
- Windows

Native Docker ¶

The webserver as well as the DNS server must be available on 127.0.0.1 or on all interfaces on 0.0.0.0. Additionally the DNS server port must be set to 53 (it is not by default).

Ensure LOCAL_LISTEN_ADDR is set accordingly
Ensure HOST_PORT_BIND is set accordingly
No other DNS resolver should listen on 127.0.0.1:53

Prerequisites ¶

First ensure that LOCAL_LISTEN_ADDR is either empty or listening on 127.0.0.1.

.env¶

host> cd path/to/devilbox
host> vi .env
LOCAL_LISTEN_ADDR=

Then you need to ensure that HOST_PORT_BIND is set to 53.

.env¶

host> cd path/to/devilbox
host> vi .env
HOST_PORT_BIND=53

Before starting up the Devilbox, ensure that port 53 is not already used on 127.0.0.1.

host> netstat -an | grep -E 'LISTEN\s*$'
tcp        0      0 127.0.0.1:53            0.0.0.0:*               LISTEN
tcp        0      0 127.0.0.1:43477         0.0.0.0:*               LISTEN
tcp        0      0 127.0.0.1:50267         0.0.0.0:*               LISTEN

If you see port 53 already being used as in the above example, ensure to stop any DNS resolver, otherwise it does not work.

The output should look like this (It is only important that there is no :53.

host> netstat -an | grep -E 'LISTEN\s*$'
tcp        0      0 127.0.0.1:43477         0.0.0.0:*               LISTEN
tcp        0      0 127.0.0.1:50267         0.0.0.0:*               LISTEN

Linux ¶

If the prerequisites are met, you can edit /etc/dhcp/dhclient.conf with root or sudo privileges and add an instruction, which tells your local DHCP client that whenever any of your DNS servers are changed, you always want to have an additional entry, which is the one from the Devilbox.

Add the following line to to the very beginning to /etc/dhcp/dhclient.conf:

/etc/dhcp/dhclient.conf¶

prepend domain-name-servers 127.0.0.1;

When you do that for the first time, you need to restart the network-manager service.

# Via service command
$ sudo service network-manager restart

# Or the systemd way
$ sudo systemctl restart network-manager

This will make sure that whenever your /etc/resolv.conf is deployed, you will have 127.0.0.1 as the first entry and also make use of any other DNS server which are deployed via the LAN’s DHCP server.

If the Devilbox DNS server is not running, it does not affect the name resolution, because you will still have other entries in /etc/resolv.conf.

MacOS ¶

Modifying /etc/resolv.conf does not work on MacOS, you need to make changes in your System Preferences:

Open System Preferences
Go to Network
Select your connected interface
Click on DNS tab
Add new DNS server by clicking the + sign
Add 127.0.0.1

Windows ¶

On Windows, you need to change your active network adapter. See the following screenshots for how to do it.

In the last screenshot, you will have to add 127.0.0.1 as your Preferred DNS server.

Docker Toolbox ¶

See also

Docker Toolbox

MacOS ¶

LOCAL_LISTEN_ADDR must be empty in order to listen on all interfaces
HOST_PORT_BIND must be set to 53
Port 80 from the Docker Toolbox virtual machine must be port-forwarded to 127.0.0.1:80 on your host os
Port 53 from the Docker Toolbox virtual machine must be port-forwarded to 127.0.0.1:53 on your host os

Todo

This section needs further proof and information.

Windows ¶

LOCAL_LISTEN_ADDR must be empty in order to listen on all interfaces
HOST_PORT_BIND must be set to 53
Port 80 from the Docker Toolbox virtual machine must be port-forwarded to 127.0.0.1:80 on your host os
Port 53 from the Docker Toolbox virtual machine must be port-forwarded to 127.0.0.1:53 on your host os

Todo

This section needs further proof and information.

.env file¶

All docker-compose configuration is done inside the .env file which simply defines key-value variables parsed to docker-compose.yml.

Note

what is the .env file?

Note

Use your browsers search function to quickly find the desired variable name.

Important

Any change of .env requires a restart of the Devilbox.

Table of Contents

Core settings
Intranet settings
Docker image versions
Docker host mounts
Docker host ports
Container settings

Core settings ¶

DEBUG_COMPOSE_ENTRYPOINT ¶

This variable controls the docker-compose log verbosity during service startup. When set to 1 verbose output as well as executed commands are shown. When set to 0 only warnings and errors are shown.

Name	Allowed values	Default value
`DEBUG_COMPOSE_ENTRYPOINT`	`0` or `1`	`1`

DOCKER_LOGS ¶

This variable controls the output of logs. Logs can either go to file and will be available under ./log/ inside the Devilbox git directory or they can be forwarded to Docker logs and will then be send to stdout and stderr.

Name	Allowed values	Default value
`DOCKER_LOGS`	`1` or `0`	`0`

When DOCKER_LOGS is set to 1, output will go to Docker logs, otherwise if it is set to 0 the log output will go to files under ./log/.

The ./log/ directory itself will contain subdirectories in the form <service>-<version> which will then hold all available log files.

Note

Log directories do not exist until you start the Devilbox and will only be created for the service versions you have enabled in .env.

The log directory structure would look something like this:

host> cd path/to/devilbox
host> tree log

log/
├── nginx-stable/
│   ├── nginx-stable/
│   ├── defaultlocalhost-access.log
│   ├── defaultlocalhost-error.log
│   ├── <project-name>-access.log    # Each project has its own access log
│   ├── <project-name>-error.log     # Each project has its own error log
├── mariadb-10.1/
│   ├── error.log
│   ├── query.log
│   ├── slow.log
├── php-fpm-7.1/
│   ├── php-fpm.access
│   ├── php-fpm.error

When you want to read logs sent to Docker logs, you can do so via the following command:

host> cd path/to/devilbox
host> docker-compose logs

When you want to continuously watch the log output (such as tail -f), you need to append -f to the command.

host> cd path/to/devilbox
host> docker-compose logs -f

When you only want to have logs displayed for a single service, you can also append the service name (works with or without -f as well):

host> cd path/to/devilbox
host> docker-compose logs php -f

Important

Currently this is only implemented for PHP-FPM and HTTPD Docker container. MySQL will always output its logs to file and all other official Docker container always output to Docker logs.

DEVILBOX_PATH ¶

This specifies a relative or absolute path to the Devilbox git directory and will be used as a prefix for all Docker mount paths.

Relative path: relative to the devilbox git directory (Must start with .)
Absolute path: Full path (Must start with /)

The only reason you would ever want change this variable is when you are on MacOS and relocate your project files onto an NFS volume due to performance issues.

Warning

Remove stopped container: Whenever you change this value you have to stop the Devilbox and also remove the stopped container via docker-compose rm.

Name	Allowed values	Default value
`DEVILBOX_PATH`	valid path	`.`

LOCAL_LISTEN_ADDR ¶

This variable specifies you host computers listening IP address for exposed container ports. If you leave this variable empty, all exposed ports will be bound to all network interfaces on your host operating system, which is also the default behaviour. If you only want the exposed container ports to be bound to a specific IP address (such as 127.0.0.1), you can add this IP address here, but note, in this case you must add a trailing colon (:).

Name	Allowed values	Default value
`LOCAL_LISTEN_ADDR`	IP address	empty

Examples:

Value	Meaning
`127.0.0.1:`	only expose ports on your host os on `127.0.0.1`. Note the trailing `:`
`192.168.0.1:`	only expose ports on your host os on `192.168.0.1`. Note the trailing `:`
`0.0.0.0:`	listen on all host computer interfaces / IP addresses
	listen on all host computer interfaces / IP addresses

Note

When using Docker Toolbox, you must leave this variable empty, in order to have the exposed ports available on the external interface of the virtual machine.

TLD_SUFFIX ¶

This variable controls all of your projects domain suffix.

Name	Allowed values	Default value
`TLD_SUFFIX`	alpha-num string	`loc`

Your project domains are built together out of the project directory name and the TLD_SUFFIX. The formula is like this: http://<project-dir>.<TLD_SUFFIX>.

You can even use official tld’s and have your nameserver point to an internal LAN id, to make this project visible to everyone in your corporate LAN.

How does it look?

Project dir	`TLD_SUFFIX`	Project URL
my-test	`loc`	`http://my-test.loc`
example	`loc`	`http://example.loc`
www.test	`loc`	`http://www.test.loc`
my-test	`local`	`http://my-test.local`
example	`local`	`http://example.local`
www.test	`local`	`http://www.test.local`
my-test	`net`	`http://my-test.net`
example	`com`	`http://example.com`
www.test	`org`	`http://www.test.org`

Warning

Do not use dev as a domain suffix (I know, it’s tempting). It has been registered by Google and they advertise the HSTS header which makes your browser redirect every http request to https.

See also: This blog post

Warning

Do not use localhost as a domain suffix. There is an RFC draft to make sure all localhost requests, including their sub domains should be redirected to the systems loopback interface. Docker has already released a commit preventing the use of localhost on MacOS.

See also: RFC Draft and Docker Release notes

EXTRA_HOSTS ¶

This variable allows you to add additional DNS entries from hosts outside the Devilbox network, such as hosts running on your host operating system, the LAN or from the internet.

Name	Allowed values	Default value
`EXTRA_HOSTS`	comma separated host mapping	empty

Adding hosts can be done in two ways:

Add DNS entry for an IP address
Add DNS entry for a hostname/CNAME which will be mapped to whatever IP address it will resolve

The general structure to add extra hosts looks like this

# Single host
EXTRA_HOSTS='hostname=1.1.1.1'
EXTRA_HOSTS='hostname=CNAME'

# Multiple hosts
EXTRA_HOSTS='hostname1=1.1.1.1,hostname2=2.2.2.2'
EXTRA_HOSTS='hostname1=CNAME1,hostname2=CNAME2'

The left side represents the name by which the host will be available by
The right side represents the IP address by which the new name will resolve to
If the right side is a CNAME itself, it will be first resolved to an IP address and then the left side will resolve to that IP address.

A few examples for adding extra hosts:

# 1. One entry:
# The following extra host 'loc' is added and will always point to 192.168.0.7.
# When reverse resolving '192.168.0.7' it will answer with 'tld'.
EXTRA_HOSTS='loc=192.168.0.7'

# 2. One entry:
# The following extra host 'my.host.loc' is added and will always point to 192.168.0.9.
# When reverse resolving '192.168.0.9' it will answer with 'my.host'.
EXTRA_HOSTS='my.host.loc=192.168.0.9'

# 3. Two entries:
# The following extra host 'tld' is added and will always point to 192.168.0.1.
# When reverse resolving '192.168.0.1' it will answer with 'tld'.
# A second extra host 'example.org' is added and always redirects to 192.168.0.2
# When reverse resolving '192.168.0.2' it will answer with 'example.org'.
EXTRA_HOSTS='tld=192.168.0.1,example.org=192.168.0.2'

# 4. Using CNAME's for resolving:
# The following extra host 'my.host' is added and will always point to whatever
# IP example.org resolves to.
# When reverse resolving '192.168.0.1' it will answer with 'my.host'.
EXTRA_HOSTS='my.host=example.org'

See also

This resembles the feature of Docker Compose: extra_hosts to add external links.

See also

NEW_UID ¶

This setting controls one of the core concepts of the Devilbox. It overcomes the problem of syncronizing file and directory permissions between the Docker container and your host operating system.

You should set this value to the user id of your host operating systems user you actually work with. How do you find out your user id?

host> id -u
1000

In most cases (on Linux and MacOS), this will be 1000 if you are the first and only user on your system, however it could also be a different value.

Name	Allowed values	Default value
`NEW_UID`	valid uid	`1000`

The Devilbox own containers will then pick up this value during startup and change their internal user id to the one specified. Services like PHP-FPM, Apache and Nginx will then do read and write operation of files with this uid, so all files mounted will have permissions as your local user and you do not have to fix permissions afterwards.

See also

Syncronize container permissions: Read up more on the general problem of trying to have syncronized permissions between the host system and a running Docker container.

NEW_GID ¶

This is the equivalent to user id for groups and addresses the same concept. See NEW_UID.

How do you find out your group id?

host> id -g
1000

In most cases (on Linux and MacOS), this will be 1000 if you are the first and only user on your system, however it could also be a different value.

Name	Allowed values	Default value
`NEW_GID`	valid gid	`1000`

See also

Syncronize container permissions: Read up more on the general problem of trying to have syncronized permissions between the host system and a running Docker container.

TIMEZONE ¶

This variable controls the system as well as service timezone for the Devilbox’s own containers. This is especially useful to keep PHP and database timezones in sync.

Name	Allowed values	Default value
`TIMEZONE`	valid timezone	`Europe/Berlin`

Have a look at Wikipedia to get a list of valid timezones: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

Note

It is always a good practice not to assume a specific timezone anyway and store all values in UTC (such as time types in MySQL).

Intranet settings ¶

DNS_CHECK_TIMEOUT ¶

The Devilbox intranet validates if every project has a corresponding DNS record (either an official DNS record, one that came from its own Auto-DNS or an /etc/hosts entry). By doing so it queries the DNS record based on <project-dir>.<TLD_SUFFIX>. In case it does not exist, the query itself might take a while and the intranet page will be unresponsive during that time. In order to avoid long waiting times, you can set the DNS query time-out in seconds after which the query should stop and report as unsuccessful. The default is 1 second, wich should be fairly sane for all use-cases.

Name	Allowed values	Default value
`DNS_CHECK_TIMEOUT`	integers	`1`

DEVILBOX_UI_SSL_CN ¶

When accessing the Devilbox intranet via https it will use an automatically created SSL certificate. Each SSL certificate requires a valid Common Name, which must match the virtual host name.

This setting let’s you specify by what name you are accessing the Devilbox intranet. The default is localhost, but if you have created your own alias, you must change this value accordingly. Also note that multiple values are possible and must be separated with a comma. When you add an asterisk (*.) to the beginning, it means it will create a wildcard certificate for that hostname.

Name	Allowed values	Default value
`DEVILBOX_UI_SSL_CN`	comma separated list of CN’s	`localhost,.localhost,devilbox,.devilbox`

Examples:

DEVILBOX_UI_SSL_CN=localhost
DEVILBOX_UI_SSL_CN=localhost,*.localhost
DEVILBOX_UI_SSL_CN=localhost,*.localhost,devilbox,*.devilbox
DEVILBOX_UI_SSL_CN=intranet.example.com

See also

HTTPS (SSL)

DEVILBOX_UI_PROTECT ¶

By setting this variable to 1, the Devilbox intranet will be password protected. This might be useful, if you share your running Devilbox instance accross a LAN, but do not want everybody to have access to the intranet itself, just to the projects you actually provide.

Name	Allowed values	Default value
`DEVILBOX_UI_PROTECT`	`0` or `1`	`0`

Note

Also pay attention to the next env var, which will control the password for the login: DEVILBOX_UI_PASSWORD.

DEVILBOX_UI_PASSWORD ¶

When the devilbox intranet is password-protected via DEVILBOX_UI_PROTECT, this is the actual password by which it will be protected.

Name	Allowed values	Default value
`DEVILBOX_UI_PASSWORD`	any string	`password`

DEVILBOX_UI_ENABLE ¶

In case you want to completely disable the Devilbox intranet, such as when running it on production, you need to set this variable to 0.

By disabling the intranet, the webserver will simply remove the default virtual host and redirect all IP-based requests to the first available virtual host, which will be you first project when ordering their names alphabetically.

Name	Allowed values	Default value
`DEVILBOX_UI_ENABLE`	`0` or `1`	`1`

Docker image versions ¶

The following settings reflect one of the main goals of the Devilbox: being able to run any combination of all container versions.

Note

Any change for those settings requires a restart of the devilbox.

PHP_SERVER ¶

This variable choses your desired PHP-FPM version to be started.

Name	Allowed values	Default value
`PHP_SERVER`	`php-fpm-5.4` `php-fpm-5.5` `php-fpm-5.6` `php-fpm-7.0` `php-fpm-7.1` `php-fpm-7.2`	`php-fpm-7.1`

All values are already available in the .env file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences:

.env¶

host> grep PHP_SERVER .env

#PHP_SERVER=php-fpm-5.4
#PHP_SERVER=php-fpm-5.5
#PHP_SERVER=php-fpm-5.6
#PHP_SERVER=php-fpm-7.0
PHP_SERVER=php-fpm-7.1
#PHP_SERVER=php-fpm-7.2
#PHP_SERVER=php-fpm-7.3
#PHP_SERVER=hhvm-latest

HTTPD_SERVER ¶

This variable choses your desired web server version to be started.

Name	Allowed values	Default value
`HTTPD_SERVER`	`apache-2.2` `apache-2.4` `nginx-stable` `nginx-mainline`	`nginx-stable`

All values are already available in the .env file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences:

.env¶

host> grep HTTPD_SERVER .env

#HTTPD_SERVER=apache-2.2
#HTTPD_SERVER=apache-2.4
HTTPD_SERVER=nginx-stable
#HTTPD_SERVER=nginx-mainline

MYSQL_SERVER ¶

This variable choses your desired MySQL server version to be started.

Name	Allowed values	Default value
`MYSQL_SERVER`	`mysql-5.5` `mysql-5.6` `mariadb-10.2` `percona-5.7` and many more	`mariadb-10.1`

All values are already available in the .env file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences:

.env¶

host> grep MYSQL_SERVER .env

#MYSQL_SERVER=mysql-5.5
#MYSQL_SERVER=mysql-5.6
#MYSQL_SERVER=mysql-5.7
#MYSQL_SERVER=mysql-8.0
#MYSQL_SERVER=mariadb-5.5
#MYSQL_SERVER=mariadb-10.0
MYSQL_SERVER=mariadb-10.1
#MYSQL_SERVER=mariadb-10.2
#MYSQL_SERVER=mariadb-10.3
#MYSQL_SERVER=percona-5.5
#MYSQL_SERVER=percona-5.6
#MYSQL_SERVER=percona-5.7

PGSQL_SERVER ¶

This variable choses your desired PostgreSQL server version to be started.

Name	Allowed values	Default value
`PGSQL_SERVER`	`9.1` `9.2` `9.3` `9.4` and many more	`9.6`

All values are already available in the .env file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences:

.env¶

host> grep PGSQL_SERVER .env

#PGSQL_SERVER=9.1
#PGSQL_SERVER=9.2
#PGSQL_SERVER=9.3
#PGSQL_SERVER=9.4
#PGSQL_SERVER=9.5
PGSQL_SERVER=9.6
#PGSQL_SERVER=10.0

Note

This is the official PostgreSQL server which might already have other tags available, check their official website for even more versions. https://hub.docker.com/_/postgres/

REDIS_SERVER ¶

This variable choses your desired Redis server version to be started.

Name	Allowed values	Default value
`REDIS_SERVER`	`2.8` `3.0` `3.2` `4.0` and many more	`4.0`

All values are already available in the .env file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences:

.env¶

host> grep REDIS_SERVER .env

#REDIS_SERVER=2.8
#REDIS_SERVER=3.0
#REDIS_SERVER=3.2
REDIS_SERVER=4.0

Note

This is the official Redis server which might already have other tags available, check their official website for even more versions. https://hub.docker.com/_/redis/

MEMCD_SERVER ¶

This variable choses your desired Memcached server version to be started.

Name	Allowed values	Default value
`MEMCD_SERVER`	`1.4.21` `1.4.22` `1.4.23` `1.4.24` and many more	`1.5.2`

All values are already available in the .env file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences:

.env¶

host> grep MEMCD_SERVER .env

#MEMCD_SERVER=1.4.21
#MEMCD_SERVER=1.4.22
#MEMCD_SERVER=1.4.23
#MEMCD_SERVER=1.4.24
#MEMCD_SERVER=1.4.25
#MEMCD_SERVER=1.4.26
#MEMCD_SERVER=1.4.27
#MEMCD_SERVER=1.4.28
#MEMCD_SERVER=1.4.29
#MEMCD_SERVER=1.4.30
#MEMCD_SERVER=1.4.31
#MEMCD_SERVER=1.4.32
#MEMCD_SERVER=1.4.33
#MEMCD_SERVER=1.4.34
#MEMCD_SERVER=1.4.35
#MEMCD_SERVER=1.4.36
#MEMCD_SERVER=1.4.37
#MEMCD_SERVER=1.4.38
#MEMCD_SERVER=1.4.39
#MEMCD_SERVER=1.5.0
#MEMCD_SERVER=1.5.1
MEMCD_SERVER=1.5.2
#MEMCD_SERVER=latest

Note

This is the official Memcached server which might already have other tags available, check their official website for even more versions. https://hub.docker.com/_/memcached/

MONGO_SERVER ¶

This variable choses your desired MongoDB server version to be started.

Name	Allowed values	Default value
`MONGO_SERVER`	`2.8` `3.0` `3.2` `3.4` and many more	`3.4`

All values are already available in the .env file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences:

.env¶

host> grep MONGO_SERVER .env

#MONGO_SERVER=2.8
#MONGO_SERVER=3.0
#MONGO_SERVER=3.2
MONGO_SERVER=3.4
#MONGO_SERVER=3.5

Note

This is the official MongoDB server which might already have other tags available, check their official website for even more versions. https://hub.docker.com/_/mongo/

Docker host mounts ¶

The Docker host mounts are directory paths on your host operating system that will be mounted into the running Docker container. This makes data persistent accross restarts and let them be available on both sides: Your host operating system as well as inside the container.

This also gives you the choice to edit data on your host operating system, such as with your favourite IDE/editor and also inside the container, by using the bundled tools, such as downloading libraries with composer and others.

Being able to do that on both sides, removes the need to install any development tools (except your IDE/editor) on your host and have everything fully encapsulated into the containers itself.

HOST_PATH_HTTPD_DATADIR ¶

This is an absolute or relative path (relative to Devilbox git directory) to your data directory.

See also

Data directory

By default, all of your websites/projects will be stored in that directory. If however you want to separate your data from the Devilbox git directory, do change the path to a place where you want to store all of your projects on your host computer.

Relative path: relative to the devilbox git directory (Must start with .)
Absolute path: Full path (Must start with /)

Name	Allowed values	Default value
`HOST_PATH_HTTPD_DATADIR`	valid path	`./data/www`

Example ¶

If you want to move all your projects to /home/myuser/workspace/web/ for example, just set it like this:

.env¶

 HOST_PATH_HTTPD_DATADIR=/home/myuser/workspace/web

Mapping ¶

No matter what path you assign, inside the PHP and the web server container your data dir will always be /shared/httpd/.

Warning

Do not create any symlinks inside your project directories that go outside the data dir. Anything which is outside this directory is not mounted into the container.

Warning

Remove stopped container: Whenever you change this value you have to stop the Devilbox and also remove the stopped container via docker-compose rm.

HOST_PATH_MYSQL_DATADIR ¶

This is an absolute or relative path (relative to Devilbox git directory) to your MySQL data directory.

Relative path: relative to the devilbox git directory (Must start with .)
Absolute path: Full path (Must start with /)

Name	Allowed values	Default value
`HOST_PATH_MYSQL_DATADIR`	valid path	`./data/mysql`

Each MySQL, MariaDB or PerconaDB version will have its own subdirectory, so when first running MySQL 5.5 and then starting MySQL 5.6, you will have a different database with different data.

Having each version separated from each other makes sure that you don’t accidently upgrade from a lower to a higher version which might not be reversable. (MySQL auto-upgrade certain older data files to newer, but this process does not necessarily work the other way round and could result in failues).

The directory structure will look something like this:

host> ls -l ./data/mysql/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mariadb-10.0/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mariadb-10.1/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mariadb-10.2/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mariadb-10.3/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mysql-5.5/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mysql-5.6/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mysql-5.7/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 mysql-8.0/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 percona-5.5/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 percona-5.6/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 percona-5.7/

Warning

Remove stopped container: Whenever you change this value you have to stop the Devilbox and also remove the stopped container via docker-compose rm.

HOST_PATH_PGSQL_DATADIR ¶

This is an absolute or relative path (relative to Devilbox git directory) to your PostgreSQL data directory.

Relative path: relative to the devilbox git directory (Must start with .)
Absolute path: Full path (Must start with /)

Name	Allowed values	Default value
`HOST_PATH_PGSQL_DATADIR`	valid path	`./data/pgsql`

Each PostgreSQL version will have its own subdirectory, so when first running PostgreSQL 9.1 and then starting PostgreSQL 10.0, you will have a different database with different data.

Having each version separated from each other makes sure that you don’t accidently upgrade from a lower to a higher version which might not be reversable.

The directory structure will look something like this:

host> ls -l ./data/pgsql/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 9.1/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 9.2/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 9.3/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 9.4/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 9.5/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 9.6/

Warning

Remove stopped container: Whenever you change this value you have to stop the Devilbox and also remove the stopped container via docker-compose rm.

HOST_PATH_MONGO_DATADIR ¶

This is an absolute or relative path (relative to Devilbox git directory) to your MongoDB data directory.

Relative path: relative to the devilbox git directory (Must start with .)
Absolute path: Full path (Must start with /)

Name	Allowed values	Default value
`HOST_PATH_MONGO_DATADIR`	valid path	`./data/mongo`

Each MongoDB version will have its own subdirectory, so when first running MongoDB 2.8 and then starting MongoDB 3.5, you will have a different database with different data.

Having each version separated from each other makes sure that you don’t accidently upgrade from a lower to a higher version which might not be reversable.

The directory structure will look something like this:

host> ls -l ./data/mongo/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 2.8/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 3.0/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 3.2/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 3.4/
drwxrwxr-x 6 48 48 4096 Jun 21 08:47 3.5/

Warning

Remove stopped container: Whenever you change this value you have to stop the Devilbox and also remove the stopped container via docker-compose rm.

Docker host ports ¶

All describned host ports below are ports that the Docker container expose on your host operating system. By default each port will be exposed to all interfaces or IP addresses of the host operating system. This can be controlled with LOCAL_LISTEN_ADDR.

How to list used ports on Linux and MacOS

Open a terminal and type the following:

host> netstat -an | grep 'LISTEN\s'
tcp        0      0 127.0.0.1:53585    0.0.0.0:*     LISTEN
tcp        0      0 127.0.0.1:37715    0.0.0.0:*     LISTEN
tcp        0      0 127.0.0.1:58555    0.0.0.0:*     LISTEN
tcp        0      0 127.0.0.1:48573    0.0.0.0:*     LISTEN
tcp        0      0 127.0.0.1:34591    0.0.0.0:*     LISTEN
tcp        0      0 127.0.0.1:8000     0.0.0.0:*     LISTEN

How to list used ports on Windows

Open the command prompt and type the following:

C:\WINDOWS\system32> netstat -an
Proto  Local Address       Foreign Address      State
TCP    0.0.0.0:80          0.0.0.0:0            LISTENING
TCP    0.0.0.0:145         0.0.0.0:0            LISTENING
TCP    0.0.0.0:445         0.0.0.0:0            LISTENING
TCP    0.0.0.0:1875        0.0.0.0:0            LISTENING

Warning

Docker Toolbox: When using Docker Toobox ensure that ports are exposed to all interfaces. See LOCAL_LISTEN_ADDR

Warning

Before setting the ports, ensure that they are not already in use on your host operating system by other services.

HOST_PORT_HTTPD ¶

The port to expose for the web server (Apache or Nginx). This is usually 80. Set it to something else if 80 is already in use on your host operating system.

Name	Allowed values	Default value
`HOST_PORT_HTTPD`	`1` - `65535`	`80`

HOST_PORT_HTTPD_SSL ¶

The port to expose for the web server (Apache or Nginx) for HTTPS (SSL) requests. This is usually 443. Set it to something else if 443 is already in use on your host operating system.

HOST_PORT_MYSQL ¶

The port to expose for the MySQL server (MySQL, MariaDB or PerconaDB). This is usually 3306. Set it to something else if 3306 is already in use on your host operating system.

Name	Allowed values	Default value
`HOST_PORT_MYSQL`	`1` - `65535`	`3306`

HOST_PORT_PGSQL ¶

The port to expose for the PostgreSQL server. This is usually 5432. Set it to something else if 5432 is already in use on your host operating system.

Name	Allowed values	Default value
`HOST_PORT_PGSQL`	`1` - `65535`	`5432`

HOST_PORT_REDIS ¶

The port to expose for the Redis server. This is usually 6379. Set it to something else if 6379 is already in use on your host operating system.

Name	Allowed values	Default value
`HOST_PORT_REDIS`	`1` - `65535`	`5432`

HOST_PORT_MEMCD ¶

The port to expose for the Memcached server. This is usually 11211. Set it to something else if 11211 is already in use on your host operating system.

Name	Allowed values	Default value
`HOST_PORT_MEMCD`	`1` - `65535`	`11211`

HOST_PORT_MONGO ¶

The port to expose for the MongoDB server. This is usually 27017. Set it to something else if 27017 is already in use on your host operating system.

Name	Allowed values	Default value
`HOST_PORT_MONGO`	`1` - `65535`	`27017`

HOST_PORT_BIND ¶

The port to expose for the BIND DNS server. This is usually 53. Set it to something else if 53 is already in use on your host operating system.

Name	Allowed values	Default value
`HOST_PORT_BIND`	`1` - `65535`	`1053`

Warning

As you might have noticed, BIND is not set to its default port 53 by default, but rather to 1053. This is because some operating system already have a local DNS resolver running on port 53 which would result in a failure when this BIND server is starting.

You only need to set BIND to port 53 when you want to use the Auto-DNS feautre of the Devilbox. When doing so, read this article with care: Auto-DNS.

Container settings ¶

PHP ¶

Custom variables ¶

The PHP container itself does not offer any variables, however you can add any key-value pair variable into the .env file which will automatically be available to the started PHP container and thus in any of your PHP projects.

If your application requires a variable to determine if it is run under development or production, for example: APPLICATION_ENV, you can just add this to the .env file:

.env¶

host> grep APPLICATION_ENV .env

APPLICATION_ENV=development

Within your php application/file you can then access this variable via the getenv function:

index.php¶

<?php
// Example use of getenv()
echo getenv('APPLICATION_ENV');
?>

This will then output development.

Note

Add as many custom environment variables as you require.

See also

Custom environment variables

Web server ¶

HTTPD_DOCROOT_DIR ¶

This variable specifies the name of a directory within each of your project directories from which the web server will serve the files.

Together with the HOST_PATH_HTTPD_DATADIR and your project directory, the HTTPD_DOCROOT_DIR will built up the final location of a virtual hosts document root.

Name	Allowed values	Default value
`HTTPD_DOCROOT_DIR`	valid dir name	`htdocs`

Example 1

devilbox git directory location: /home/user-1/repo/devilbox
HOST_PATH_HTTPD_DATADIR: ./data/www (relative)
Project directory: my-first-project
HTTPD_DOCROOT_DIR: htdocs

The location from where the web server will serve files for my-first-project is then: /home/user-1/repo/devilbox/data/www/my-first-project/htdocs

Example 2

devilbox git directory location: /home/user-1/repo/devilbox
HOST_PATH_HTTPD_DATADIR: /home/user-1/www (absolute)
Project directory: my-first-project
HTTPD_DOCROOT_DIR: htdocs

The location from where the web server will serve files for my-first-project is then: /home/user-1/www/my-first-project/htdocs

Directory structure: default

Let’s have a look how the directory is actually built up:

 # Project directory
 host> ls -l data/www/my-first-project/
 total 4
 drwxr-xr-x 2 cytopia cytopia 4096 Mar 12 23:05 htdocs/

 # htdocs directory inside your project directory
 host> ls -l data/www/my-first-project/htdocs
 total 4
 -rw-r--r-- 1 cytopia cytopia 87 Mar 12 23:05 index.php

By calling your proect url, the index.php file will be served.

Directory structure: nested symlink

Most of the time you would clone or otherwise download a PHP framework, which in most cases has its own www directory somewhere nested. How can this be linked to the htdocs directory?

Let’s have a look how the directory is actually built up:

 # Project directory
 host> ls -l data/www/my-first-project/
 total 4
 drwxr-xr-x 2 cytopia cytopia 4096 Mar 12 23:05 cakephp/
 lrwxrwxrwx 1 cytopia cytopia   15 Mar 17 09:36 htdocs -> cakephp/webroot/

 # htdocs directory inside your project directory
 host> ls -l data/www/my-first-project/htdocs
 total 4
 -rw-r--r-- 1 cytopia cytopia 87 Mar 12 23:05 index.php

As you can see, the web server is still able to server the files from the htdocs location, this time however, htdocs itself is a symlink pointing to a much deeper and nested location inside an actual framework directory.

HTTPD_TEMPLATE_DIR ¶

This variable specifies the directory name (which is just in your project directory, next to the HTTPD_DOCROOT_DIR directory) in which you can hold custom web server configuration files.

Every virtual host (which represents a project) can be fully customized to its own needs, independently of other virtual hosts.

This directory does not exist by default and you need to create it. Additionally you will also have to populate it with one of three yaml-based template files.

Name	Allowed values	Default value
`HTTPD_TEMPLATE_DIR`	valid dir name	`.devilbox`

Let’s have a look at an imaginary project directory called my-first-project:

# Project directory
host> ls -l data/www/my-first-project/
total 4
drwxr-xr-x 2 cytopia cytopia 4096 Mar 12 23:05 htdocs/

Inside this your project directory you will need to create another directory which is called .devilbox by default. If you change the HTTPD_TEMPLATE_DIR variable to something else, you will have to create a directory by whatever name you chose for that variable.

 # Project directory
 host> cd data/www/my-first-project/
 host> mkdir .devilbox
 host> ls -l
 total 4
 drwxr-xr-x 2 cytopia cytopia 4096 Mar 12 23:05 .devilbox/
 drwxr-xr-x 2 cytopia cytopia 4096 Mar 12 23:05 htdocs/

Now you need to copy the vhost-gen templates into the .devilbox directory. The templates are available in the Devilbox git directory under templates/vhost-gen/.

By copying those files into your project template directory, nothing will change, these are the default templates that will create the virtual host exactly the same way as if they were not present.

 # Navigate into the devilbox directory
 host> cd path/to/devilbox

 # Copy templates to your project directory
 host> cp templates/vhost-gen/* data/www/my-first-project/.devilbox/

Let’s have a look how the directory is actually built up:

 # Project directory
 host> ls -l data/www/my-first-project/
 total 4
 drwxr-xr-x 2 cytopia cytopia 4096 Mar 12 23:05 .devilbox/
 drwxr-xr-x 2 cytopia cytopia 4096 Mar 12 23:05 htdocs/

 # template directory inside your project directory
 host> ls -l data/www/my-first-project/htdocs/.devilbox
 total 4
 -rw-r--r-- 1 cytopia cytopia 87 Mar 12 23:05 apache22.yml
 -rw-r--r-- 1 cytopia cytopia 87 Mar 12 23:05 apache24.yml
 -rw-r--r-- 1 cytopia cytopia 87 Mar 12 23:05 nginx.yml

The three files apache22.yml, apache24.yml and nginx.yml let you customize your web servers virtual host to anything from adding rewrite rules, overwriting directory index to even changing the server name or adding locations to other assets.

See also

The whole process is based on a project called vhost-gen. A virtual host generator for Apache 2.2, Apache 2.4 and any Nginx version.

See also

Customize your virtual host: When you want to find out more how to actually customize each virtual host to its own need, read up more on Customized virtual host (vhost-gen).
Tutorials: Also have a look at this tutorial which is a walk-through showing you how to modify a virtual host and make it serve all files for multiple sub domains (server names): Adding Sub domains

MySQL ¶

MYSQL_ROOT_PASSWORD ¶

If you start a MySQL container for the first time, it will setup MySQL itself with this specified password. If you do change the root password to something else, make sure to also set it accordingly in .env, otherwise the devilbox will not be able to connect to MySQL and will not be able to display information inside the bundled intranet.

Name	Allowed values	Default value
`MYSQL_ROOT_PASSWORD`	any string	empty (no password)

Warning

Keep this variable in sync with the actual MySQL root password.

MYSQL_GENERAL_LOG ¶

This variable controls the logging behaviour of the MySQL server (MySQL, MariaDB and PerconaDB). As the Devilbox is intended to be used for development, this feature is turned on by default.

Name	Allowed values	Default value
`MYSQL_GENERAL_LOG`	`0` or `1`	`0`

MySQL documentation:

“The general query log is a general record of what mysqld is doing. The server writes information to this log when clients connect or disconnect, and it logs each SQL statement received from clients. The general query log can be very useful when you suspect an error in a client and want to know exactly what the client sent to mysqld.”

– https://dev.mysql.com/doc/refman/5.7/en/query-log.html

PostgreSQL ¶

PGSQL_ROOT_USER ¶

If you start a PostgreSQL container for the first time, it will setup PostgreSQL itself with a specified username and password. If you do change the root username or password to something else, make sure to also set it accordingly in .``env,`` otherwise the devilbox will not be able to connect to PostgreSQL and will not be able to display information inside the bundled intranet.

Name	Allowed values	Default value
`PGSQL_ROOT_USER`	alphabetical string	`postgres`

Warning

Keep this variable in sync with the actual PostgreSQL username.

PGSQL_ROOT_PASSWORD ¶

If you start a PostgreSQL container for the first time, it will setup PostgreSQL itself with a specified username and password. If you do change the root username or password to something else, make sure to also set it accordingly in .``env,`` otherwise the devilbox will not be able to connect to PostgreSQL and will not be able to display information inside the bundled intranet.

Name	Allowed values	Default value
`PGSQL_ROOT_PASSWORD`	any string	empty (no password)

Warning

Keep this variable in sync with the actual PostgreSQL password.

Bind ¶

BIND_DNS_RESOLVER ¶

This variable holds a comma separated list of IP addresses of DNS servers. By default using Google’s DNS server as they are pretty fast.

Name	Allowed values	Default value
`BIND_DNS_RESOLVER`	comma separated list of IP addresses	`8.8.8.8,8.8.4.4`

The devilbox is using its own DNS server internally (your host computer can also use it for Auto-DNS) in order to resolve custom project domains defined by TLD_SUFFIX. To also be able to reach the internet from within the Container there must be some kind of upstream DNS server to ask for queries.

Some examples:

BIND_DNS_RESOLVER='8.8.8.8'
BIND_DNS_RESOLVER='8.8.8.8,192.168.0.10'

Note

If you don’t trust the Google DNS server, then set it to something else. If you already have a DNS server inside your LAN and also want your custom DNS (if any) to be available inside the containers, set the value to its IP address.

BIND_DNSSEC_VALIDATE ¶

This variable controls the DNSSEC validation of the DNS server. By default it is turned off.

Name	Allowed values	Default value
`BIND_DNSSEC_VALIDATE`	`no`, `auto`, `yes`	`no`

yes - DNSSEC validation is enabled, but a trust anchor must be manually configured. No validation will actually take place.
no - DNSSEC validation is disabled, and recursive server will behave in the “old fashioned” way of performing insecure DNS lookups, until you have manually configured at least one trusted key.
auto - DNSSEC validation is enabled, and a default trust anchor (included as part of BIND) for the DNS root zone is used.

BIND_LOG_DNS ¶

This variable controls if DNS queries should be shown in Docker log output or not. By default no DNS queries are shown.

Name	Allowed values	Default value
`BIND_LOG_DNS`	`1` or `0`	`0`

If enabled all DNS queries are shown. This is useful for debugging.

BIND_TTL_TIME ¶

This variable controls the DNS TTL in seconds. If empty or removed it will fallback to a sane default.

Name	Allowed values	Default value
`BIND_TTL_TIME`	integer	empty

See also

BIND_REFRESH_TIME ¶

This variable controls the DNS Refresh time in seconds. If empty or removed it will fallback to a sane default.

Name	Allowed values	Default value
`BIND_REFRESH_TIME`	integer	empty

See also

BIND_RETRY_TIME ¶

This variable controls the DNS Retry time in seconds. If empty or removed it will fallback to a sane default.

Name	Allowed values	Default value
`BIND_RETRY_TIME`	integer	empty

See also

BIND_EXPIRY_TIME ¶

This variable controls the DNS Expiry time in seconds. If empty or removed it will fallback to a sane default.

Name	Allowed values	Default value
`BIND_EXPIRY_TIME`	integer	empty

See also

BIND_MAX_CACHE_TIME ¶

This variable controls the DNS Max Cache time in seconds. If empty or removed it will fallback to a sane default.

Name	Allowed values	Default value
`BIND_MAX_CACHE_TIME`	integer	empty

See also

docker-compose.yml¶

This file is the core of the Devilbox and glues together all Docker images.

It is very tempting to just change this file in order to add new services to the already existing once. However your git directory will become dirty and you will always have to stash your changes before pulling new features from remote. To overcome this Docker Compose offers a default override file (docker-compose.override.yml) that let’s you specify custom changes as well as completely new services without having to touch the default docker-compose.yml.

See also

To find out more read docker-compose.override.yml

docker-compose.override.yml¶

The docker-compose.override.yml is the configuration file where you can override existing settings from docker-compose.yml or even add completely new services.

By default, this file does not exist and you must create it. You can either copy the existing docker-compose.override.yml-example or create a new one.

Table of Contents

Create docker-compose.override.yml
- Copy example file
- Create new file from scratch
Further reading

See also

Official Docker documentation: Share Compose configurations between files and projects

Create docker-compose.override.yml ¶

Copy example file ¶

host> cd path/to/devilbox
host> cp docker-compose.override.yml-example docker-compose.override.yml

Create new file from scratch ¶

Create an empty file within the Devilbox git directory named docker-compose.override.yml
Retrieve the currently used version from the existing docker-compose.yml file
Copy this version line to your newly created docker-compose.override.yml at the very top

# Create an empty file
host> cd path/to/devilbox
host> touch docker-compose.override.yml

# Retrieve the current version
host> grep ^version docker-compose.yml
version: '2.1'

# Add this version line to docker-compose.override.yml
host> echo "version: '2.1'" > docker-compose.override.yml

Let’s see again how this file should look like now:

docker-compose.override.yml¶

version: '2.1'

Note

The documentation might be outdated and the version number might already be higher. Rely on the output of the grep command.

apache.conf¶

Apache 2.2 and Apache 2.4 both come with their default vendor configuration. This might not be the ideal setup for some people, so you have the chance to change any of those settings, by supplying custom configurations.

See also

If you are rather using Nginx, have a look at: nginx.conf

Important

You could actually also create virtual hosts here, but it is recommended to use the Devilbox Auto-vhost generation feature. If you want to custimize your current virtual hosts have a look at Customized virtual host (vhost-gen).

Table of Contents

General
Examples
- Adjust KeepAlive settings for Apache 2.2
- Limit HTTP headers and GET size for Apache 2.4

General ¶

You can set custom apache.conf configuration options for each Apache version separately. See the directory structure for Apache configuration directories inside ./cfg/ directory:

host> ls -l path/to/devilbox/cfg/ | grep 'apache'

drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 apache-2.2/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 apache-2.4/

Customization is achieved by placing a file into cfg/apache-X.X/ (where X.X stands for your Apache version). The file must end by .conf in order to be sourced by the web server.

Each of the Apache configuration directories already contain an example file: devilbox-custom.conf-example, that can simply be renamed to devilbox-custom.conf. This file holds some example values that can be adjusted or commented out.

In order for the changes to be applied, you will have to restart the Devilbox.

Examples ¶

Adjust KeepAlive settings for Apache 2.2 ¶

The following examples shows you how to change the KeepAlive, the MaxKeepAliveRequests as well as the KeepAliveTimeout values of Apache 2.2.

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Navigate to Apache 2.2 config directory
host> cd cfg/apache-2.2

# Create new conf file
host> touch keep_alive.conf

Now add the following content to the file:

keep_alive.conf¶

KeepAlive On
KeepAliveTimeout 10
MaxKeepAliveRequests 100

In order to apply the changes you need to restart the Devilbox.

Note

The above is just an example demonstration, you probably need other values for your setup. So make sure to understand how to configure Apache, if you are going to change any of those settings.

Limit HTTP headers and GET size for Apache 2.4 ¶

The following examples shows you how to limit the amount of headers the client can send to the server as well as changing the maximum URL GET size by adjusting LimitRequestFields, LimitRequestFieldSize and LimitRequestLine for Apache 2.4.

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Navigate to Apache 2.4 config directory
host> cd cfg/apache-2.4

# Create new conf file
host> touch limits.conf

Now add the following content to the file:

limits.conf¶

# Limit amount of HTTP headers a client can send to the server
LimitRequestFields 20
LimitRequestFieldSize 4094

# URL GET size
LimitRequestLine 2048

In order to apply the changes you need to restart the Devilbox.

Note

The above is just an example demonstration, you probably need other values for your setup. So make sure to understand how to configure Apache, if you are going to change any of those settings.

nginx.conf¶

Nginx stable and Nginx mainline both come with their default vendor configuration. This might not be the ideal setup for some people, so you have the chance to change any of those settings, by supplying custom configurations.

See also

If you are rather using Apache, have a look at: apache.conf

Important

You could actually also create virtual hosts here, but it is recommended to use the Devilbox Auto-vhost generation feature. If you want to custimize your current virtual hosts have a look at Customized virtual host (vhost-gen).

Table of Contents

General
Examples
- Adjust KeepAlive settings for Nginx stable
- Adjust timeout settings for Nginx mainline

General ¶

You can set custom nginx.conf configuration options for each Nginx version separately. See the directory structure for Nginx configuration directories inside ./cfg/ directory:

host> ls -l path/to/devilbox/cfg/ | grep 'nginx'

drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 nginx-mainline/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 nginx-stable/

Customization is achieved by placing a file into cfg/nginx-X/ (where X stands for your Nginx flavoour). The file must end by .conf in order to be sourced by the web server.

Each of the Nginx configuration directories already contain an example file: devilbox-custom.conf-example, that can simply be renamed to devilbox-custom.conf. This file holds some example values that can be adjusted or commented out.

In order for the changes to be applied, you will have to restart the Devilbox.

Examples ¶

Adjust KeepAlive settings for Nginx stable ¶

The following examples shows you how to change the keepalive, the keepalive_requests as well as the keepalive_timeout values of Nginx stable.

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Navigate to Nginx stable config directory
host> cd cfg/nginx-stable

# Create new conf file
host> touch keep_alive.conf

Now add the following content to the file:

keep_alive.conf¶

keepalive 10;
keepalive_timeout 10s;
keepalive_requests 100;

In order to apply the changes you need to restart the Devilbox.

Note

The above is just an example demonstration, you probably need other values for your setup. So make sure to understand how to configure Nginx, if you are going to change any of those settings.

Adjust timeout settings for Nginx mainline ¶

The following examples shows you how to adjust various timeout settings for Nginx mainline by adjusting client_body_timeout, client_header_timeout and send_timeout directives.

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Navigate to Nginx mainline config directory
host> cd cfg/nginx-mainline

# Create new conf file
host> touch timeouts.conf

Now add the following content to the file:

timeouts.conf¶

client_body_timeout 60s;
client_header_timeout 60s;
send_timeout 60s;

In order to apply the changes you need to restart the Devilbox.

Note

The above is just an example demonstration, you probably need other values for your setup. So make sure to understand how to configure Nginx, if you are going to change any of those settings.

php.ini¶

php.ini changes are global to all projects, but will only affect the currently selected PHP version.

Table of Contents

General
Examples
- Change memory_limit for PHP 7.1
- Change timeout values for PHP 5.6

General ¶

You can set custom php.ini configuration options for each PHP version separately. See the directory structure for PHP configuration directories inside ./cfg/ directory:

host> ls -l path/to/devilbox/cfg/ | grep 'php-ini'

drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-ini-5.4/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-ini-5.5/
drwxr-xr-x  2 cytopia cytopia 4096 Apr  3 22:04 php-ini-5.6/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-ini-7.0/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-ini-7.1/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-ini-7.2/

Customization is achieved by placing a file into cfg/php-ini-X.X/ (where X.X stands for your PHP version). The file must end by .ini in order to be sourced by the PHP-FPM server.

Each of the PHP ini configuration directories already contain an example file: devilbox-custom.ini-example, that can simply be renamed to devilbox-custom.ini. This file holds some example values that can be adjusted or commented out.

In order for the changes to be applied, you will have to restart the Devilbox.

Examples ¶

Change memory_limit for PHP 7.1 ¶

The following examples shows you how to change the memory_limit of PHP 7.1 to 4096 MB.

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Navigate to PHP 7.1 config directory
host> cd cfg/php-ini-7.1

# Create new ini file
host> touch memory_limit.ini

Now add the following content to the file:

memory_limit.ini¶

[PHP]
memory_limit = 4096M

In order to apply the changes you need to restart the Devilbox. You can validate that the changes have taken place by visiting the Devilbox intranet phpinfo page.

Change timeout values for PHP 5.6 ¶

The following examples shows you how to change the max_execution_time and max_input_time of PHP 5.6.

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Navigate to PHP 5.6 config directory
host> cd cfg/php-ini-5.6

# Create new ini file
host> touch timeouts.ini

Now add the following content to the file:

timeouts.ini¶

[PHP]
max_execution_time = 180
max_input_time     = 180

In order to apply the changes you need to restart the Devilbox. You can validate that the changes have taken place by visiting the Devilbox intranet phpinfo page.

php-fpm.conf¶

php-fpm.conf changes are global to all projects, but will only affect the currently selected PHP version.

Table of Contents

General
Examples

General ¶

You can set custom php-fpm.conf configuration options for each PHP version separately. These changes affect the PHP-FPM process itself, global as well as pool specific configuration can be set.

Note

The default PHP-FPM pool is called www in case you want to make changes to it.

See the directory structure for PHP-FPM configuration directories inside ./cfg/ directory:

host> ls -l path/to/devilbox/cfg/ | grep 'php-fpm'

drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-fpm-5.4/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-fpm-5.5/
drwxr-xr-x  2 cytopia cytopia 4096 Apr  3 22:04 php-fpm-5.6/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-fpm-7.0/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-fpm-7.1/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-fpm-7.2/

Customization is achieved by placing a file into cfg/php-fpm-X.X/ (where X.X stands for your PHP version). The file must end by .conf in order to be sourced by the PHP-FPM server.

Each of the PHP-FPM conf configuration directories already contain an example file: devilbox-custom.conf-example, that can simply be renamed to devilbox-custom.conf. This file holds some example values that can be adjusted or commented out.

In order for the changes to be applied, you will have to restart the Devilbox.

See also

To find out about all available PHP-FPM directives, global or pool specific have a look at its documentation: https://secure.php.net/manual/en/install.fpm.configuration.php

Examples ¶

Change rlimit core for master process for PHP 7.1 ¶

The following examples shows you how to change the rlimit_core of PHP-FPM 7.1 master process to 100.

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Navigate to PHP 7.1 config directory
host> cd cfg/php-fpm-7.1

# Create new conf file
host> touch rlimit.conf

Now add the following content to the file:

rlimit.conf¶

[global]
rlimit_core = 100

Important

Note the [global] section.

In order to apply the changes you need to restart the Devilbox.

Change child process on pool `www` for PHP 5.6 ¶

The following examples shows you how to change the pm, pm.max_children, pm.start_servers, pm.min_spare_servers and pm.max_spare_servers of PHP-FPM 5.6 on pool www.

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Navigate to PHP 5.6 config directory
host> cd cfg/php-fpm-5.6

# Create new conf file
host> touch www_server.conf

Now add the following content to the file:

www_server.conf¶

[www]
; Pool config
pm = dynamic
pm.max_children = 10
pm.start_servers = 3
pm.min_spare_servers = 2
pm.max_spare_servers = 5

Important

Note the [www] section.

In order to apply the changes you need to restart the Devilbox.

Set non-overwritable php.ini values for PHP 7.0 ¶

You can also set php.ini values that cannot be overwritten by php.ini or the ini_set() function of PHP. This might be useful to make sure a specific value is enforced and will not be changed by some PHP frameworks on-the-fly.

This is achieved by php_admin_flag and php_admin_value that are parsed directly to PHP-FPM.

The following example will disable built-in PHP functions globally and non-overwriteable for PHP 7.0.

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Navigate to PHP 7.0 config directory
host> cd cfg/php-fpm-7.0

# Create new conf file
host> touch admin.conf

Now add the following content to the file:

admin.conf¶

[www]
php_admin_value[disable_functions] = link,symlink,popen,exec,system,shell_exec

Important

Note the [www] section.

Important

This kind of setting only has affects PHP files served through PHP-FPM, when you run php on the command line, this setting will be ignored.

Important

Be aware that none of your projects can use the above disabled functions anymore. They will simply not exist for PHP 7.0 after that configuration took affect.

In order to apply the changes you need to restart the Devilbox.

my.cnf¶

my.ini changes are global to all projects, but will only affect the currently selected MySQL version.

Important

When using Docker Toolbox on Windows, *.cnf files must have read-only file permissions, otherwise they are not sourced by the MySQL server.

Make sure to chmod 0444 *.cnf after adding your values.

Table of Contents

General
Examples
- Change key_buffer_size for MySQL 5.5
- Change timeout and packet size for PerconaDB 5.7

General ¶

You can set custom MySQL options via your own defined my.cnf files for each version separately. See the directory structure for MySQL configuration directories inside ./cfg/ directory:

host> ls -l path/to/devilbox/cfg/ | grep -E 'mysql|mariadb|percona'

drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 mariadb-10.0/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 mariadb-10.1/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 mariadb-10.2/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 mariadb-10.3/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 mysql-5.5/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 mysql-5.6/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 mysql-5.7/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 mysql-8.0/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 percona-5.5/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 percona-5.6/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 percona-5.7/

Customization is achieved by placing a file into cfg/mysql-X.X/, cfg/mariadb-X.X/ or cfg/percona-X-X (where X.X stands for your MySQL version). The file must end by .cnf in order to be sourced by the MySQL server.

Each of the MySQL cnf configuration directories already contain an example file: devilbox-custom.cnf-example, that can simply be renamed to devilbox-custom.cnf. This file holds some example values that can be adjusted or commented out.

In order for the changes to be applied, you will have to restart the Devilbox.

Examples ¶

Change key_buffer_size for MySQL 5.5 ¶

The following examples shows you how to change the key_buffer_size of MySQL 5.5 to 16 MB.

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Navigate to MySQL 5.5 config directory
host> cd cfg/mysql-5.5

# Create new cnf file
host> touch key_buffer_size.cnf

Now add the following content to the file:

memory_limit.cnf¶

[mysqld]
key_buffer_size=16M

In order to apply the changes you need to restart the Devilbox. You can validate that the changes have taken place by visiting the Devilbox intranet MySQL info page.

Change timeout and packet size for PerconaDB 5.7 ¶

The following examples shows you how to change the wait_timeout and max_allowed_packet of PerconaDB 5.7

# Navigate to the Devilbox directory
host> cd path/to/devilbox

# Navigate to PerconaDB 5.7 config directory
host> cd cfg/percona-5.7

# Create new ini file
host> touch timeouts.cnf

Now add the following content to the file:

timeouts.cnf¶

[mysqld]
max_allowed_packet=256M
wait_timeout = 86400

In order to apply the changes you need to restart the Devilbox. You can validate that the changes have taken place by visiting the Devilbox intranet MySQL info page.

bashrc.sh¶

Each PHP container is using bash as its default shell. If you do not like the way it is currently configured, you can add your own configuration files to overwrite settings.

See also

Table of Contents

Directory mapping
Examples
- Custom aliases
- Custom vim configuration

Directory mapping ¶

Inside the Devilbox git directory you will find a directory called bash/. Every file inside this directory ending by *.sh will be source by your bash shell, allowing for a customized bash configuration. All files not ending by *.sh will be ignored and can be used to create config files for other programs.

The bash/ directory will be mounted into the PHP container to /etc/bashrc-devilbox.d/.

Host OS path	Docker path
`./bash/`	`/etc/bashrc-devilbox.d/`

Examples ¶

Custom aliases ¶

Let’s say you want to add some custom shell aliases. All you have to do is create any file ending by .sh and place it into the ./bash/ directory:

# Navigate to the Devilbox git directory
host> cd path/to/devilbox

# Create a new file
host> touch ./bash/aliases.sh

# Add some content to the file
host> vi ./bash/aliases.sh

./bash/aliases.sh¶

 alias l='ls -a'
 alias ll='ls -al'
 alias www='cd /shared/httpd'

Custom vim configuration ¶

The .vimrc is usually place directly in the users home directory and the Devilbox does not offer any mounts directly to that directory, however you can use a trick with shell aliases to use vim with a different config file by default.

First of all, place your favorite .vimrc into the ./bash/ directory

# Navigate to the Devilbox git directory
host> cd path/to/devilbox

# Copy your vim config to the ./bash directory
host> cp ~/.vimrc bash/.vimrc

Right now, this is not going to do anything and as .vimrc is not ending by .sh it is also ignored by the shell itself. What is now left to do, is make vim itself always use this config file.

As you can see from the above stated directory mapping, the .vimrc file will end up under: /etc/bashrc-devilbox.d/.vimrc inside the PHP container, so just create a shell alias for vim that will always use this file:

# Navigate to the Devilbox git directory
host> cd path/to/devilbox

# Create a new file
host> touch ./bash/vim.sh

# Add your vim alias
host> vi ./bash/vim.sh

./bash/vim.sh¶

alias vim='vim -u /etc/bashrc-devilbox.d/.vimrc

Whenever you start vim inside any PHP container, it will automatically use the provided vim configuration file.

This trick will work for all tools that require configuration files.

Docker and Docker Compose¶

This section gives you some detail about installing Docker and Docker Compose on your operating system.

Install Docker
Install Docker Compose
Checklist

Install Docker ¶

See also

Docker Toolbox: Note, this section refers to native Docker, which is the recommended version. If however, you need to install Docker Toolbox (such as on Windows 7 or older Macs), have a look at this page.

Warning

The minimum required Docker version is 1.12.0. Make sure not to install older versions.

Docker on Linux ¶

Refer to the official Docker for Linux documentation for how to install Docker on your specific Linux distribution.

Docker on Windows ¶

Refer to the official Docker for Windows documentation for how to install Docker on Windows.

Docker on MacOS ¶

Refer to the official Docker for Mac documentation for how to install Docker on MacOS.

`docker` user group ¶

Docker itself requires super user privileges which is granted to a system wide group called docker. After having installed Docker on your system, ensure that your local user is assigned to the docker group. Check this via groups or id command.

host> id

uid=1000(cytopia) gid=1000(cytopia) groups=1000(cytopia),999(docker)

Install Docker Compose ¶

Warning

The minimum required Docker Compose version is 1.9.0. Make sure not to install older versions.

The Docker documentation provides various ways to install Docker Compose for all supported operating systems and is quite extensive and straight forward. Follow their steps here: Install Docker Compose.

Checklist ¶

Docker is installed at the minimum required version
Your user is part of the docker group
Docker Compose is installed at the minimum required version

Installation ¶

Warning

The minimum required Docker Toolbox version is 1.12.0. Make sure not to install older versions.

Docker Toolbox on Windows ¶

Refer to the official Docker Toolbox on Windows documentation for how to install Docker Toolbox on Windows.

Docker Toolbox on MacOS ¶

Refer to the official Docker Toolbox on MacOS documentation for how to install Docker Toolbox on MacOS.

Docker Compose ¶

When installing Docker Compose, make sure you do that inside the virtual machine.

See also

Install Docker Compose: Have a look at this page to help you install Docker Compose for your operating system.

Additional steps ¶

Docker Toolbox is a legacy solution to bring Docker to systems which don’t natively support Docker itself. This is achieved by starting a virtualized Linux (e.g.: on VirtualBox) and have Docker run inside.

You don’t have to take care about setting up the virtual machine, this is done automatically with the provided setup file (Windows and MacOS).

This however has several disadvantages as the forwarded Docker ports are only visible inside the virtualized Linux and not on the host computer. Therefore the web server port cannot be reached on your host machine and you are not able to view any projects.

Listening address ¶

First thing you need to make sure is that the LOCAL_LISTEN_ADDR variable from your .env file is empty. When it is empty all services bind to all IP addresses inside the virtual machine and thus being able to be seen from outside (your host operating system).

You can verifiy that the variable is actually empty by checking your .env file:

host> grep ^LOCAL_LISTEN_ADDR .env

LOCAL_LISTEN_ADDR=

Port forwarding ¶

Additionally I would suggest that you port-forward the virtual machines port 80 (which itself points to the docker container inside) to your host computers 127.0.0.1 address. This way you can reach the devilbox via http://127.0.0.1 or http://localhost.

If you do not port-forward it to your host machines localhost, you will have to adjust all project DNS entries that are described in this documentation to go to 127.0.0.1 to the IP address of your virtual machine.

Auto-DNS ¶

I am currently not aware that Auto-DNS will work with Docker Toolbox. If you are willing to spent some time there, let me know. There is currently an open ticket which is addressing this: https://github.com/cytopia/devilbox/issues/101

Checklist ¶

Docker Toolbox is installed at minimum required version
Docker Compose is installed inside the virtual machine at minimum required version
LOCAL_LISTEN_ADDR is empty in the .env file

Available container¶

Note

Start the Devilbox: Find out how to start some or all container.

The following table gives you an overview about all container that can be started. When doing a selective start, use the Name value to specify the container to start up.

Container	Name	Hostname	IP Address
DNS	bind	bind	172.16.238.100
PHP	php	php	172.16.238.10
Apache, Nginx	httpd	httpd	172.16.238.11
MySQL, MariaDB, PerconaDB	mysql	mysql	172.16.238.12
PostgreSQL	pgsql	pgsql	172.16.238.13
Redis	redis	redis	172.16.238.14
Memcached	memcd	memcd	172.16.238.15
MongoDB	mongo	mongo	172.16.238.16

Available tools¶

Each PHP container version brings the same tools, so you can safely switch versions without having to worry to have less or more tools available.

See also