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

User settings ¶

Some versions of Docker require your local user to be in the docker group (or docker-users on Windows).

Shared drives ¶

Some versions of Docker require you to correctly setup shared drives. Ensure the desired locations are being made available to Docker and the correct credentials are applied.

Network and firewall ¶

On Windows, ensure your firewall allows access to shared drives.

SE Linux ¶

Make sure to read any shortcomings when SE Linux is enabled.

General ¶

It could also help to do a full system restart after the installation has been finished.

Optional previous knowledge ¶

In order to easily work with the Devilbox you should already be familiar with the following:

Navigate on the command line
Docker Compose commands ( up , stop , kill , rm , logs and pull )
Docker Compose .env file
Know how to use git

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Install the Devilbox¶

Important

Ensure you have read and followed the Prerequisites

Table of Contents

Download the Devilbox
Create .env file
Set uid and gid
- Find your user id
- Find your group id
OS specific setup
- Linux: SELinux
- OSX: Performance
Checklist

Download the Devilbox ¶

The Devilbox does not need to be installed. The only thing that is required is its git directory. To download that, open a terminal and copy/paste the following command.

host> git clone https://github.com/cytopia/devilbox

See also

Create `.env` file ¶

Inside the cloned Devilbox git directory, you will find a file called env-example. This file is the main configuration with sane defaults for Docker Compose. In order to use it, it must be copied to a file named .env. (Pay attention to the leading dot).

host> cp env-example .env

The .env file does nothing else than providing environment variables for Docker Compose and in this case it is used as the main configuration file for the Devilbox by providing all kinds of settings (such as which version to start up).

See also

Set uid and gid ¶

To get you started, there are only two variables that need to be adjusted:

NEW_UID
NEW_GID

The values for those two variables refer to your local (on your host operating system) user id and group id. To find out what the values are required in your case, issue the following commands on a terminal:

Find your user id ¶

host> id -u

Find your group id ¶

host> id -g

In most cases both values will be 1000, but for the sake of this example, let’s assume a value of 1001 for the user id and 1002 for the group id.

Open the .env file with your favorite text editor and adjust those values:

.env¶

host> vi .env

NEW_UID=1001
NEW_GID=1002

See also

OS specific setup ¶

Linux: SELinux ¶

If you have SELinux enabled, you will also have to adjust the MOUNT_OPTIONS to allow shared mounts among multiple container:

.env¶

host> vi .env

MOUNT_OPTIONS=,z

See also

OSX: Performance ¶

Out of the box, Docker for Mac has some performance issues when it comes to mount directories with a lot of files inside. To mitigate this issue, you can adjust the caching settings for mounted directories.

To do so, you will want to adjust the MOUNT_OPTIONS to allow caching on mounts.

.env¶

host> vi .env

MOUNT_OPTIONS=,cached

Ensure to read the links below to understand why this problem exists and how the fix works. The Docker documentation will also give you alternative caching options to consider.

See also

Checklist ¶

Devilbox is cloned
.env file is created
User and group id have been set in .env file

That’s it, you have finished the first section and have a working Devilbox ready to be started.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Start the Devilbox¶

Congratulations, when you have reached this page everything has been set up and you can now get your hands dirty.

Note

Starting and stopping containers is done via docker-compose. If you have never worked with it before, have a look at their documentation for overview , up , stop , kill , rm , logs and pull commands.

Table of Contents

The Devilbox startup explained
Start all container
- Foreground
- Background
Start some container
- Foreground
- Background
Stop and Restart
- Stop all container
- Restart all container
Open Devilbox intranet
Checklist

The Devilbox startup explained ¶

To gain a brief understanding about what is happening under the hood during startup, read ahead or skip directly to: Start all container.

Startup operations with the same configuration are idempotent, thus consecutive startups will not introduce any new changes. The following shows the brief startup steps:

Docker Compose will automatically pull all necessary Docker images if they do not exist locally.
Once the HTTPD container start, it will automatically create a Certificate Authority to be used for https connections and will place it in the ca/ directory.
The HTTPD container will then look for already available projects and create virtual hosts configurations, apply vhost-gen templates as well as CA-signed HTTPS certificates.
Once the Bind container start, it will create a wildcard DNS zone for the given TLD_SUFFIX
In case MySQL or PgSQL container start, they will populate itself with their required default databases.

Note

Docker images are only pulled if they do not exist. They are not updated automatically. If you want to update to new Docker images read on: Update the Devilbox.

Start all container ¶

If you want all provided docker container to be available (as defined in docker-compose.yml), start them all by not explicitly specifying any image name.

Foreground ¶

For the first startup, foreground start is recommended to see any errors that might occur:

host> docker-compose up

If you want to gracefully stop all container, hit Ctrl + c
If you want to kill all container, hit Ctrl + c twice
Ensure to run docker-compose rm -f afterwards

Background ¶

For consecutive startups you can send them into background (-d):

host> docker-compose up -d

If you want to gracefully stop all container, enter docker-compose stop
If you want to kill all container, enter docker-compose kill
Ensure to run docker-compose rm -f afterwards

Start some container ¶

If you don’t require all container to be up and running and let’s say just PHP, HTTPD and MYSQL, you must explicitly specify the image names to start:

Foreground ¶

host> docker-compose up httpd php mysql

If you want to gracefully stop all started container, hit Ctrl + c
If you want to kill all started container, hit Ctrl + c twice
Ensure to run docker-compose rm -f afterwards

Background ¶

host> docker-compose up -d httpd php mysql

If you want to gracefully stop all container, enter docker-compose stop
If you want to kill all container, enter docker-compose kil
Ensure to run docker-compose rm -f afterwards

See also

Available container: Have a look at this page to get an overview about all available container and by what name they have to be specified.

Stop and Restart ¶

Important

When stopping or restarting the Devilbox, ensure to also remove stopped container before the next startup to prevent orphaned runtime settings and always start fresh.

This will prevent many common Docker issues.

See also

Troubleshooting: What to always do first

Stop all container ¶

# Stop all container
host> docker-compose stop
# Remove stopped container (important!)
host> docker-compose rm -f

Restart all container ¶

# Stop all container
host> docker-compose stop
# Remove stopped container (important!)
host> docker-compose rm -f
# Start all container
host> docker-compose up

Open Devilbox intranet ¶

Once docker-compose up has finished and all or the selected container are up and running, you can visit the Devilbox intranet with your favorite Web browser at http://localhost or http://127.0.0.1 (https://localhost or https://127.0.0.1 respectively).

The Intranet start page will also show you all running and failed containers:

Devilbox intranet: index dash view for all started container

_images/devilbox-intranet-dash-selective.png

Devilbox intranet: index dash view for some started container

Important

Find Docker Toolbox IP address: When you are using Docker Toolbox the Devilbox web server port will not be available on your host computer. You first have to find out on which IP address the Docker Toolbox machine is serving and use this one instead.

Checklist ¶

Docker container are started successfully with docker-compose up
docker-compose rm -f is issued before restarting the Devilbox
Intranet is reachable via http://localhost, http://127.0.0.1 or Docker Toolbox IP address
Intranet is reachable via https://localhost, https://127.0.0.1 (HTTPS)

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Devilbox intranet¶

The Devilbox 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.

Devilbox intranet: homepage

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.

Devilbox intranet: available virtual hosts

Emails ¶

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

Devilbox intranet: email catch-all overview

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:

_images/devilbox-intranet-mysql-databases.png

Devilbox intranet: MySQL database overview

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.

Devilbox intranet: php info

The following example shows you the info page for MySQL:

_images/devilbox-intranet-mysql-info.png

Devilbox intranet: MySQL info overview

Third-party tools ¶

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.

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.

phpPgAdmin ¶

phpPgAdmin is a web-based administration tool for PostgreSQL. It is perfect for PostgreSQL DBAs, newbies, and hosting services.

phpRedMin ¶

phpRedMin is a simple web interface to manage and monitor your Redis.

PHPMemcachedAdmin ¶

PHPMemcachedAdmin is a simple web interface to manage and monitor your Memcached.

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

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Directory overview¶

Important

The directory overview only provides you some theoretical, but useful insights about how it all works together. You should at least read it once to be able to debug any problems you might encounter.

If you have read it already, jump directly to Create your first project

Table of Contents

Data directory
Project directory
Docroot directory
Domain suffix
Making sense of it
Checklist

Data directory ¶

By default all your projects must be created in the ./data/www/ directory which is inside in your Devilbox git directory. This can be changed as well, but is outside the scope of this getting started tutorial.

You can verifiy that the path is actually ./data/www/ by checking your .env file:

host> grep HTTPD_DATADIR .env

HOST_PATH_HTTPD_DATADIR=./data/www

Project directory ¶

The project directory is a directory directly within the data directory.

This represents one project.

By creating this directory, the web server will create a new virtual host for you. This happens fully automated and there is nothing else required to do except just to create a directory.

The name of this directory will also be used to build up the final project url together with the domain suffix: http://<project directory>.<domain suffix>

Create as many project directories as you require.

Docroot directory ¶

The docroot directory is a directory within each project directory from which the webserver will serve the files.

By default this directory must be named htdocs. This can be changed as well, but is outside the scope of this getting started tutorial.

You can verifiy that the docroot directory is actually htdocs by checking your .env file:

host> grep DOCROOT_DIR .env

HTTPD_DOCROOT_DIR=htdocs

Domain suffix ¶

The default domain suffix (TLD_SUFFIX variable in .env file) is loc. That means that all your projects will be available under the following address: http://<project-directory>.loc. This can be changed as well, but is outside the scope of this getting started tutorial.

You can verifiy that the suffix is actually loc by checking your .env file:

host> grep ^TLD_SUFFIX .env

TLD_SUFFIX=loc

Making sense of it ¶

Ok, let’s sum it up and make sense of the previously provided information. To better illustrate the behaviour we are going to use project-1 as our project directory name.

Item	Example	Description
data dir	`./data/www`	Where all of your projects reside.
project dir	`./data/www/project-1`	A single project. It’s name will be used to create the url.
docroot dir	`./data/www/project-1/htdocs`	Where the webserver looks for files within your project.
domain suffix	`loc`	Suffix to build up your project url.
project url	`http://project-1.loc`	Final resulting project url.

data dir

This directory is mounted into the httpd and php container, so that both know where all projects can be found. This is also the place where you create project directories for each of your projects.

project dir

Is your project and used to generate the virtual host together with the domain suffix.

docroot dir

A directory inside your project dir from where the webserver will actually serve your files.

domain suffix

Used as part of the project url.

Checklist ¶

You know what the data directory is
You know what the project directory is
You know what the docroot directory is
You know what the domain suffix is
You know how domains are constructed

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Create your first project¶

Important

Ensure you have read Directory overview to understand what is going on under the hood.

Note

This section not only applies for one project, it applied for as many projects as you need. There is no limit in the number of projects.

Table of Contents

Step 1: visit Intranet vhost page
Step 2: create a project directory
Step 3: create a docroot directory
Step 4: create a DNS entry
Step 5: visit your project
Step 6: create a hello world file
Checklist
Further examples

Step 1: visit Intranet vhost page ¶

Before starting, have a look at the vhost page at http://localhost/vhosts.php or http://127.0.0.1/vhosts.php

See also

It should look like the screenshot below and will actually already provide the information needed to create a new project.

_images/devilbox-intranet-vhosts-empty.png

Devilbox intranet: no projects created

Step 2: create a project directory ¶

In your Devilbox git directory, navigate to ./data/www and create a new directory.

Note

Choose the directory name wisely, as it will be part of the domain for that project. For this example we will use project-1 as our project name.

# navigate to your Devilbox git directory
host> cd path/to devilbox

# navigate to the data directory
host> cd data/www

# create a new project directory named: project-1
host> mkdir project-1

Visit the vhost page again and see what has changed: http://localhost/vhosts.php

_images/devilbox-intranet-vhosts-missing-htdocs.png

Devilbox intranet: misssing htdocs directory

So what has happened?

By having created a project directory, the web server container has created a new virtual host. However it has noticed, that the actual document root directory does not yet exist and therefore it cannot serve any files yet.

Step 3: create a docroot directory ¶

Note

As desribed in Docroot directory the docroot directory name must be htdocs for now.

Navigate to your newly created project directory and create a directory named htdocs inside it.

# navigate to your Devilbox git directory
host> cd path/to devilbox

# navigate to your above created project directory
host> cd data/www/project-1

# create the docroot directory
host> mkdir htdocs

Vist the vhost page again and see what has changed: http://localhost/vhosts.php

_images/devilbox-intranet-vhosts-missing-dns.png

Devilbox intranet: misssing dns record

So what has happened?

By having created the docroot directory, the web server is now able to serve your files. However it has noticed, that you have no way yet, to actually visit your project url, as no DNS record for it exists yet.

The intranet already gives you the exact string that you can simply copy into your /etc/hosts (or C:\Windows\System32\drivers\etc for Windows) file on your host operating system to solve this issue.

Step 4: create a DNS entry ¶

Note

This step can also be automated via the bundled DNS server to automatically provide catch-all DNS entries to your host computer, but is outside the scope of this getting started tutorial.

When using native Docker, the Devilbox intranet will provide you the exact string you need to paste into your /etc/hosts (or C:\Windows\System32\drivers\etc for Windows).

# Open your /etc/hosts file with sudo or root privileges
# and add the following DNS entry
host> sudo vi /etc/hosts

127.0.0.1 project-1.loc

See also

Vist the vhost page again and see what has changed: http://localhost/vhosts.php

_images/devilbox-intranet-vhosts-working.png

Devilbox intranet: vhost setup successfully

So what has happened?

By having created the DNS record, the Devilbox intranet is aware that everything is setup now and gives you a link to your new project.

Step 5: visit your project ¶

On the intranet, click on your project link. This will open your project in a new Browser tab or visit http://project-1.loc

_images/devilbox-project-missing-index.png

Devilbox project: misssing index.php or index.html

So what has happened?

Everything is setup now, however the webserver is trying to find a index.php file in your document root which does not yet exist.

So all is left for you to do is to add your HTML or PHP files.

Step 6: create a hello world file ¶

Navigate to your docroot directory within your project and create a index.php file with some output.

# navigate to your Devilbox git directory
host> cd path/to devilbox

# navigate to your projects docroot directory
host> cd data/www/project-1/htdocs

# Create a hello world index.php file
host> echo "<?php echo 'hello world';" > index.php

Alternatively create an index.php file in data/www/project-1/htdocs with the following contents:

<?php echo 'hello world';

Visit your project url again and see what has changed: http://project-1.loc

_images/devilbox-project-hello-world.png

Devilbox project: hello world on index.php

Checklist ¶

Project directory is created
Docroot directory is created
DNS entry is added to the host operating system
PHP files are added to your docroot directory

See also

Further examples ¶

If you already want to know how to setup specific frameworks on the Devilbox, jump directly to their articles:

See also

Well tested frameworks on the Devilbox

See also

Generic information for all unlisted frameworks

Setup other Frameworks

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Enter the PHP container¶

Another core feature of the Devilbox, is to be totally independent of what you have or have not installed on your host operating system.

The Devilbox already ships with many common developer tools which are installed inside each PHP container, so why not make use of it.

The only thing you might need to install on your host operating system is your favourite IDE or editor to actually start coding.

See also

If you want to find out what tools are available inside the PHP container, visit the following section: Available tools.

Table of Contents

How to enter
- Linux and MacOS
- Windows
How to become root
Tools
- What is available
- How to update them
Advanced
Checklist

How to enter ¶

Note

You can only enter the PHP container if it is running.

Linux and MacOS ¶

On Linux and MacOS you can simply execute the provided shell script: shell.sh. By doing so it will enter you into the PHP container and bring you to /shared/httpd.

# Execute on the host operating system
host> ./shell.sh

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

Windows ¶

On Windows you have a different script to enter the PHP container: shell.bat. Just run it and it will enter you into the PHP container and bring you to /shared/httpd.

# Execute on the host operating system
C:/Users/user1/devilbox> shell.bat

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

How to become root ¶

When you enter the container with the provided scripts, you are doing so as the user devilbox. If you do need to perform any actions as root (such as installing new software), you can use the password-less sudo.

# Inside the PHP Linux container as user devilbox
devilbox@php-7.0.19 in /shared/httpd $ sudo su -

# Now you are root and can do anything you want
root@php-7.0.19 in /shared/httpd $

Note

As this action is inside a Docker container, there is no difference between Linux, MacOS or Windows. Every host operating system is using the same Docker container - equal accross all platforms.

Tools ¶

What is available ¶

There are lots of tools available, for a full overview see Available tools. If you think you are missing a tool, install it yourself as root, or open up an issue on github to get it backed into the Docker image permanently.

See also

Available tools

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

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

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

Implications
- Configuration changes
- Data changes
Examples
Gotchas
Checklist

Implications ¶

Configuration changes ¶

Be aware that every version has its own configuration files in the cfg/ directory. If you switch to a different version, you might end up with a different custom configuration. This however only applies, if you have already customized the configuration for your current service.

See also

Data changes ¶

You also have to be aware that all database services (e.g.: MySQL, PostgreSQL, MongoDB, etc) use a per version data directory. If you change the database version you might find that you have an empty database when starting another version.

This is simply a pre-caution to prevent newer versions from upgrading the database files and accidentally making them incompatible for older versions.

If you want to take your data along, do a backup before switching the version and then re-import after the switch:

See also

Examples ¶

Change PHP version ¶

Stop the Devilbox ¶

Shut down the Devilbox in case it is still running:

# Navigate to the Devilbox directory
host> cd path/to/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.2
#PHP_SERVER=5.3
#PHP_SERVER=5.4
#PHP_SERVER=5.5
#PHP_SERVER=5.6
#PHP_SERVER=7.0
PHP_SERVER=7.1
#PHP_SERVER=7.2
#PHP_SERVER=7.3
#PHP_SERVER=7.4
#PHP_SERVER=8.0
#PHP_SERVER=8.1
#PHP_SERVER=8.2

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.2
#PHP_SERVER=5.3
#PHP_SERVER=5.4
PHP_SERVER=5.5
#PHP_SERVER=5.6
#PHP_SERVER=7.0
#PHP_SERVER=7.1
#PHP_SERVER=7.2
#PHP_SERVER=7.3
#PHP_SERVER=7.4
#PHP_SERVER=8.0
#PHP_SERVER=8.1
#PHP_SERVER=8.2

Start the Devilbox ¶

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

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

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

See also

Change web server version ¶

Stop the Devilbox ¶

Shut down the Devilbox in case it is still running:

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

# Stop all container
host> docker-compose stop

Edit the `.env` file ¶

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

.env¶

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

As you can see, all available values are already there, but commented. Only one is uncommented. In this example it is nginx-stable, which is the web server 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 Apache 2.2, you would change the .env file like this:

.env¶

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

Start the Devilbox ¶

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

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

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

See also

Change whatever version ¶

When you have read how to change the PHP or web server 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

Gotchas ¶

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

Consider this .env file:

.env¶

#PHP_SERVER=5.2
#PHP_SERVER=5.3
#PHP_SERVER=5.4
PHP_SERVER=5.5
#PHP_SERVER=5.6
PHP_SERVER=7.0
#PHP_SERVER=7.1
#PHP_SERVER=7.2
#PHP_SERVER=7.3
#PHP_SERVER=7.4
#PHP_SERVER=8.0
#PHP_SERVER=8.1
#PHP_SERVER=8.2

Both, PHP 5.5 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.

Checklist ¶

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

See also

Add custom DNS server on Linux

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

IMPORTANT¶

The following is a collection of important do’s and don’ts you should be aware of when starting to use the Devilbox and Docker in general.

Table of Contents

Starting
- Do not run via sudo or root
- Starting, Stopping and Restarting
Backups

Starting ¶

Do not run via `sudo` or `root`¶

Do not start the Devilbox with sudo or as root user. If it complains about permissions when starting it with your normal system user, it is probably due to the fact, that your user is not in the docker group.

See also

Ensure you have read and done the following:

Add user to docker group: Docker installation
Synronize file permissions: Set uid and gid

Warning

If you start the Devilbox with sudo or as root user, it will most likely mess with your file permissions.

Starting, Stopping and Restarting ¶

Whenever you want to stop the Devilbox, change configuration and start up again, do not forget to remove stopped container.

# Stop the Devilbox
host> docker-compose stop

# Remove stopped container
host> docker-compose rm

# Start the Devilbox
host> docker-compose up

See also

Stop and Restart (why do docker-compose rm?)

Backups ¶

Ensure to do regular database backups! Better safe then sorry!

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup Auto DNS¶

If you don’t want to add host 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
Docker Toolbox
- Prerequisites
- Actual setup

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.

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

Docker on Linux ¶

Your DNS server IP address is 127.0.0.1.

See also

Docker for Mac ¶

Your DNS server IP address is 127.0.0.1.

See also

Add custom DNS server on MacOS

Important

The .local TLD will not resolve on MacOs, due to Apple’s use of Multicast DNS for this TLD. If you want to use .local, you will need to specify each domain in /etc/hosts manually.

Docker for Windows ¶

Your DNS server IP address is 127.0.0.1.

See also

Add custom DNS server on Windows

Docker Toolbox ¶

See also

Docker Toolbox and the Devilbox

This part applies equally for Docker Toolbox on MacOS and on Windows:

Prerequisites ¶

LOCAL_LISTEN_ADDR must be empty in order to listen on all interfaces
HOST_PORT_BIND must be set to 53

You need to create three port-forwards to make the DNS and web server available on your host os:

Port 80 from the Docker Toolbox virtual machine must be port-forwarded to 127.0.0.1:80 on your host os
Port 443 from the Docker Toolbox virtual machine must be port-forwarded to 127.0.0.1:443 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

Assuming the Docker Toolbox IP is 192.168.99.100 your forwards must be as follows:

From IP	From port	To IP	To port
192.168.99.100	53	127.0.0.1	53
192.168.99.100	80	127.0.0.1	80
192.168.99.100	443	127.0.0.1	443

See also

Actual setup ¶

Important

After settings this up, follow the above guides for Docker for Mac or Docker for Windows to finish the setup.

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup valid HTTPS¶

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.

Valid HTTPS will automatically be available for all projects

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

Import the CA into your browser ¶

Important

Importing the CA into the browser is also recommended and required for the Devilbox intranet page to work properly. You may also import the CA into your Operating System’s Keystore. Information on that is available at GFI Root Certificate guide .

Chrome / Chromium ¶

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

Click on Advanced

Find the setting Manage certificates and open it.

Click on Manage certificates

Navigate to the tab setting AUTHORITIES and click on IMPORT.

Click on IMPORT in the AUTHORITIES tab

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

Note: your file manager might look different

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.

Tell Chrome to trust this CA

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

Valid HTTPS will automatically be available for all projects

Note: if you are on Chrome on Mac Big Sur and above, you won’t find the above settings, you will have to go the “Keychain Access” application, click on System in the left hand corner and then drag in the devilbox-ca.crt, it will ask for your password to complete the operation. once that is done, the cert will be listed but will not be trusted by default. Now right click on the imported cert, click on Info, an info dialog will open up and you can expand the ‘Trust’ accordian and set it to Trust All. 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.

Click on Privacy & Security in the left menu bar

At the very bottom click on the button View Certificates.

_images/firefox-privacy-and-security.png

Click on View Certificates

In the Authories tab, click on Import.

Click on Import in the Authorities tab

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

Note: your file manager might look different

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.

Tell Firefox to trust this CA

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

Valid HTTPS will automatically be available for all projects

Configure PHP Xdebug¶

This section explains in depth how to enable and use PHP Xdebug with the Devilbox.

Table of Contents

Introduction
Configure Xdebug

Introduction ¶

In order to have a working Xdebug, you need to ensure two things:

PHP Xdebug must be configured and enabled in PHP itself
Your IDE/editor must be configured and requires a way talk to PHP

Configuring PHP Xdebug will slightly differ when configuring it for a dockerized environment. This is due to the fact that Docker versions on different host os have varying implementations of how they connect back to the host.

Most IDE or editors will also require different configurations for how they talk to PHP Xdebug. This is at least most likely the case for xdebug.idekey.

See also

Xdebug options explained

Configure Xdebug ¶

Docker on Linux ¶

Docker on Linux allows Xdebug to automatically connect back to the host system without the need of an explicit IP address.

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Docker on Linux: Xdebug for Atom¶

Docker on Linux allows Xdebug to automatically connect back to the host system without the need of an explicit IP address.

Table of Contents

Prerequisites
Assumption
Configuration

Prerequisites ¶

Ensure you know how to customize php.ini values for the Devilbox and have a rough understanding about common Xdebug options.

See also

Assumption ¶

For the sake of this example, we will assume the following settings and file system paths:

Directory	Path
Devilbox git directory	`/home/cytopia/repo/devilbox`
HOST_PATH_HTTPD_DATADIR	`./data/www`
Resulting local project path	`/home/cytopia/repo/devilbox/data/www`
Selected PHP version	`5.6`

The Resulting local project path is the path where all projects are stored locally on your host operating system. No matter what this path is, the equivalent remote path (inside the Docker container) is always /shared/httpd.

Important

Remember this, when it comes to path mapping in your IDE/editor configuration.

Configuration ¶

Install php-debug for Atom ¶

Ensure you have php-debug installed for Atom.

See also

php-debug

Configure Atom ¶

You will need to configure the path mapping in config.cson (Atom configuration file) or via UI:

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

Recall the path settings from the Assumption section and adjust if your configuration differs!

Configure php.ini ¶

Note

The following example show how to configure PHP Xdebug for PHP 5.6:

Create an xdebug.ini file (must end by .ini):

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

# Navigate to PHP 5.6 ini configuration directory
host> cd cfg/php-ini-5.6/

# Create and open debug.ini file
host> vi xdebug.ini

Copy/paste all of the following lines into the above created xdebug.ini file:

xdebug.ini¶

; Defaults
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_port=9000

; The Linux way
xdebug.remote_connect_back=1

; idekey value is specific to Atom
xdebug.idekey=xdebug.atom

; Optional: Set to true to always auto-start xdebug
xdebug.remote_autostart=false

Xdebug 3.0 changes:

xdebug.ini¶

; Defaults
xdebug.mode=debug
xdegub.client_port=9000

; The Linux Way
xdebug.discover_client_host=1

; idekey value is specific to Atom
xdebug.session=xdebug.atom

; Optional: Set to true to always auto-start xdebug
xdebug.start_with_request=Yes

Note

Host os and editor specific settings are highlighted in yellow and are worth googling to get a better understanding of the tools you use and to be more efficient at troubleshooting.

Restart the Devilbox ¶

Restarting the Devilbox is important in order for it to read the new PHP settings. Note that the following example only starts up PHP, HTTPD and Bind.

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

# Stop, remove stopped container and start
host> docker-compose stop
host> docker-compose rm
host> docker-compose up php httpd bind

See also

Stop and Restart (Why do docker-compose rm?)

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Docker on Linux: Xdebug for PhpStorm¶

Docker on Linux allows Xdebug to automatically connect back to the host system without the need of an explicit IP address.

Table of Contents

Prerequisites
Assumption
Configuration

Prerequisites ¶

Ensure you know how to customize php.ini values for the Devilbox and have a rough understanding about common Xdebug options.

See also

Assumption ¶

For the sake of this example, we will assume the following settings and file system paths:

Directory	Path
Devilbox git directory	`/home/cytopia/repo/devilbox`
HOST_PATH_HTTPD_DATADIR	`./data/www`
Resulting local project path	`/home/cytopia/repo/devilbox/data/www`
Selected PHP version	`5.6`

The Resulting local project path is the path where all projects are stored locally on your host operating system. No matter what this path is, the equivalent remote path (inside the Docker container) is always /shared/httpd.

Important

Remember this, when it comes to path mapping in your IDE/editor configuration.

Configuration ¶

Configure PhpStorm ¶

1. Ensure Xdebug port is set to 9000

PHPStorm settings: Xdebug

2. Set path mapping

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:

PHPStorm settings: path mapping

Important

Recall the path settings from the Assumption section and adjust if your configuration differs!

3. Ensure DBGp proxy settings are configured

PHPStorm settings: DBGp Proxy

Configure php.ini ¶

Note

The following example show how to configure PHP Xdebug for PHP 5.6:

Create an xdebug.ini file (must end by .ini):

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

# Navigate to PHP 5.6 ini configuration directory
host> cd cfg/php-ini-5.6/

# Create and open debug.ini file
host> vi xdebug.ini

Copy/paste all of the following lines into the above created xdebug.ini file:

xdebug.ini¶

; Defaults
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_port=9000

; The Linux way
xdebug.remote_connect_back=1

; idekey value is specific to PhpStorm
xdebug.idekey=PHPSTORM

; Optional: Set to true to always auto-start xdebug
xdebug.remote_autostart=false

Note

Host os and editor specific settings are highlighted in yellow and are worth googling to get a better understanding of the tools you use and to be more efficient at troubleshooting.

Restart the Devilbox ¶

Restarting the Devilbox is important in order for it to read the new PHP settings. Note that the following example only starts up PHP, HTTPD and Bind.

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

# Stop, remove stopped container and start
host> docker-compose stop
host> docker-compose rm
host> docker-compose up php httpd bind

See also

Stop and Restart (Why do docker-compose rm?)

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Docker on Linux: Xdebug for Sublime Text 3¶

Docker on Linux allows Xdebug to automatically connect back to the host system without the need of an explicit IP address.

Table of Contents

Prerequisites
Assumption
Configuration

Prerequisites ¶

Ensure you know how to customize php.ini values for the Devilbox and have a rough understanding about common Xdebug options.

See also

Assumption ¶

For the sake of this example, we will assume the following settings and file system paths:

Directory	Path
Devilbox git directory	`/home/cytopia/repo/devilbox`
HOST_PATH_HTTPD_DATADIR	`./data/www`
Resulting local project path	`/home/cytopia/repo/devilbox/data/www`
Selected PHP version	`5.6`

The Resulting local project path is the path where all projects are stored locally on your host operating system. No matter what this path is, the equivalent remote path (inside the Docker container) is always /shared/httpd.

Important

Remember this, when it comes to path mapping in your IDE/editor configuration.

Configuration ¶

Install Xdebug Client for Sublime ¶

Use Sublime’s Package Control to search for and install Xdebug Client.

See also

Xdebug client

Configure Sublime ¶

Navigate to Tools -> Xdebug -> Settings - User in the menu

This will open the configuration file in Sublime

Xdebug-sublime-settings¶

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

Important

Recall the path settings from the Assumption section and adjust if your configuration differs!

Configure php.ini ¶

Note

The following example show how to configure PHP Xdebug for PHP 5.6:

Create an xdebug.ini file (must end by .ini):

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

# Navigate to PHP 5.6 ini configuration directory
host> cd cfg/php-ini-5.6/

# Create and open debug.ini file
host> vi xdebug.ini

Copy/paste all of the following lines into the above created xdebug.ini file:

xdebug.ini¶

; Defaults
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_port=9000

; The Linux way
xdebug.remote_connect_back=1

; idekey value is specific to Sublime
xdebug.idekey=sublime.xdebug

; Optional: Set to true to always auto-start xdebug
xdebug.remote_autostart=false

Note

Host os and editor specific settings are highlighted in yellow and are worth googling to get a better understanding of the tools you use and to be more efficient at troubleshooting.

Restart the Devilbox ¶

Restarting the Devilbox is important in order for it to read the new PHP settings. Note that the following example only starts up PHP, HTTPD and Bind.

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

# Stop, remove stopped container and start
host> docker-compose stop
host> docker-compose rm
host> docker-compose up php httpd bind

See also

Stop and Restart (Why do docker-compose rm?)

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Docker on Linux: Xdebug for Visual Studio Code¶

Docker on Linux allows Xdebug to automatically connect back to the host system without the need of an explicit IP address.

Table of Contents

Prerequisites
Assumption
Configuration

Prerequisites ¶

Ensure you know how to customize php.ini values for the Devilbox and have a rough understanding about common Xdebug options.

See also

Assumption ¶

For the sake of this example, we will assume the following settings and file system paths:

Directory	Path
Devilbox git directory	`/home/cytopia/repo/devilbox`
HOST_PATH_HTTPD_DATADIR	`./data/www`
Resulting local project path	`/home/cytopia/repo/devilbox/data/www`
Selected PHP version	`5.6`

The Resulting local project path is the path where all projects are stored locally on your host operating system. No matter what this path is, the equivalent remote path (inside the Docker container) is always /shared/httpd.

Important

Remember this, when it comes to path mapping in your IDE/editor configuration.

Configuration ¶

Install vscode-php-debug for VSCode ¶

Ensure you have vscode-php-debug installed for Visual Studio Code.

See also

vscode-php-debug

Configure VSCode ¶

You will need to configure the path mapping in launch.json (VSCode configuration file):

launch.json¶

{
   "version": "0.2.0",
   "configurations": [
      {
         "name": "Xdebug for Project mytest",
         "type": "php",
         "request": "launch",
         "port": 9000,
         "pathMappings": {
            "/shared/httpd/mytest/htdocs": "${workspaceFolder}/htdocs"
         },
         "log": true,
         "xdebugSettings": {
            "max_children": 128,
            "max_data": 512,
            "max_depth": 3
         }
      },
      {
         "name": "Launch currently open script",
         "type": "php",
         "request": "launch",
         "program": "${file}",
         "cwd": "${fileDirname}",
         "port": 9000
      }
   ]
}

Important

Recall the path settings from the Assumption section and adjust if your configuration differs!

Important

The above example configures Xdebug for a single project mytest. Add more projects as you need.

See also

Configure php.ini ¶

Note

The following example show how to configure PHP Xdebug for PHP 7.4:

Create an xdebug.ini file (must end by .ini):

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

# Navigate to PHP 7.4 ini configuration directory
host> cd cfg/php-ini-7.4/

# Create and open debug.ini file
host> vi xdebug.ini

Copy/paste all of the following lines into the above created xdebug.ini file:

xdebug.ini¶

; Defaults
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.client_port=9000
xdebug.client_host=docker.for.lin.host.internal
xdebug.remote_handler=dbgp
xdebug.start_with_request=yes

; Controls the protection mechanism for infinite recursion protection
xdebug.max_nesting_level=250

; idekey value is specific to Visual Studio Code
xdebug.idekey=VSCODE

Note

Host os and editor specific settings are highlighted in yellow and are worth googling to get a better understanding of the tools you use and to be more efficient at troubleshooting.

Restart the Devilbox ¶

Restarting the Devilbox is important in order for it to read the new PHP settings. Note that the following example only starts up PHP, HTTPD and Bind.

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

# Stop, remove stopped container and start
host> docker-compose stop
host> docker-compose rm
host> docker-compose up php httpd bind

See also

Stop and Restart (Why do docker-compose rm?)

See also

Docker on MacOS ¶

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Docker on MacOS: Xdebug for Atom¶

Note

Docker on MacOS requires you to create a host address alias on your loopback device.

Table of Contents

Prerequisites
Assumption
Configuration

Prerequisites ¶

Ensure you know how to customize php.ini values for the Devilbox and have a rough understanding about common Xdebug options.

See also

Important

Ensure you have created an Host address alias on MacOS and 10.254.254.254 is aliased to your localhost.

Assumption ¶

For the sake of this example, we will assume the following settings and file system paths:

Directory	Path
Devilbox git directory	`/home/cytopia/repo/devilbox`
HOST_PATH_HTTPD_DATADIR	`./data/www`
Resulting local project path	`/home/cytopia/repo/devilbox/data/www`
Selected PHP version	`5.6`
Host address alias	`10.254.254.254` (see prerequisites)

The Resulting local project path is the path where all projects are stored locally on your host operating system. No matter what this path is, the equivalent remote path (inside the Docker container) is always /shared/httpd.

Important

Remember this, when it comes to path mapping in your IDE/editor configuration.

Configuration ¶

Install php-debug for Atom ¶

Ensure you have php-debug installed for Atom.

See also

php-debug

Configure Atom ¶

You will need to configure the path mapping in config.cson (Atom configuration file) or via UI:

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

Recall the path settings from the Assumption section and adjust if your configuration differs!

Configure php.ini ¶

Note

The following example show how to configure PHP Xdebug for PHP 5.6:

Create an xdebug.ini file (must end by .ini):

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

# Navigate to PHP 5.6 ini configuration directory
host> cd cfg/php-ini-5.6/

# Create and open debug.ini file
host> vi xdebug.ini

Copy/paste all of the following lines into the above created xdebug.ini file:

xdebug.ini¶

; Defaults
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_port=9000

; The MacOS way
xdebug.remote_connect_back=0
xdebug.remote_host=10.254.254.254

; idekey value is specific to Atom
xdebug.idekey=xdebug.atom

; Optional: Set to true to always auto-start xdebug
xdebug.remote_autostart=false

Important

Ensure you have created a Host address alias on MacOS pointing to 10.254.254.254 as stated in the prerequisites section above!

Note

Host os and editor specific settings are highlighted in yellow and are worth googling to get a better understanding of the tools you use and to be more efficient at troubleshooting.

Restart the Devilbox ¶

Restarting the Devilbox is important in order for it to read the new PHP settings. Note that the following example only starts up PHP, HTTPD and Bind.

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

# Stop, remove stopped container and start
host> docker-compose stop
host> docker-compose rm
host> docker-compose up php httpd bind

See also

Stop and Restart (Why do docker-compose rm?)

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Docker on MacOS: Xdebug for PhpStorm¶

Note

Docker on MacOS requires you to create a host address alias on your loopback device.

Table of Contents

Prerequisites
Assumption
Configuration

Prerequisites ¶

Ensure you know how to customize php.ini values for the Devilbox and have a rough understanding about common Xdebug options.

See also

Important

Ensure you have created an Host address alias on MacOS and 10.254.254.254 is aliased to your localhost.

Assumption ¶

For the sake of this example, we will assume the following settings and file system paths:

Directory	Path
Devilbox git directory	`/home/cytopia/repo/devilbox`
HOST_PATH_HTTPD_DATADIR	`./data/www`
Resulting local project path	`/home/cytopia/repo/devilbox/data/www`
Selected PHP version	`5.6`
Host address alias	`10.254.254.254` (see prerequisites)

The Resulting local project path is the path where all projects are stored locally on your host operating system. No matter what this path is, the equivalent remote path (inside the Docker container) is always /shared/httpd.

Important

Remember this, when it comes to path mapping in your IDE/editor configuration.

Configuration ¶

Configure PhpStorm ¶

1. Ensure Xdebug port is set to 9000

PHPStorm settings: Xdebug

2. Set path mapping

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:

PHPStorm settings: path mapping

Important

Recall the path settings from the Assumption section and adjust if your configuration differs!

3. Ensure DBGp proxy settings are configured

PHPStorm settings: DBGp Proxy

Configure php.ini ¶

Note

The following example show how to configure PHP Xdebug for PHP 5.6:

Create an xdebug.ini file (must end by .ini):

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

# Navigate to PHP 5.6 ini configuration directory
host> cd cfg/php-ini-5.6/

# Create and open debug.ini file
host> vi xdebug.ini

Copy/paste all of the following lines into the above created xdebug.ini file:

xdebug.ini¶

; Defaults
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_port=9000

; The MacOS way
xdebug.remote_connect_back=0
xdebug.remote_host=10.254.254.254

; idekey value is specific to PhpStorm
xdebug.idekey=PHPSTORM

; Optional: Set to true to always auto-start xdebug
xdebug.remote_autostart=false

Important

Ensure you have created a Host address alias on MacOS pointing to 10.254.254.254 as stated in the prerequisites section above!

Note

Host os and editor specific settings are highlighted in yellow and are worth googling to get a better understanding of the tools you use and to be more efficient at troubleshooting.

Restart the Devilbox ¶

Restarting the Devilbox is important in order for it to read the new PHP settings. Note that the following example only starts up PHP, HTTPD and Bind.

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

# Stop, remove stopped container and start
host> docker-compose stop
host> docker-compose rm
host> docker-compose up php httpd bind

See also

Stop and Restart (Why do docker-compose rm?)

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Docker on MacOS: Xdebug for Sublime Text 3¶

Note

Docker on MacOS requires you to create a host address alias on your loopback device.

Table of Contents

Prerequisites
Assumption
Configuration

Prerequisites ¶

Ensure you know how to customize php.ini values for the Devilbox and have a rough understanding about common Xdebug options.

See also

Important

Ensure you have created an Host address alias on MacOS and 10.254.254.254 is aliased to your localhost.

Assumption ¶

For the sake of this example, we will assume the following settings and file system paths:

Directory	Path
Devilbox git directory	`/home/cytopia/repo/devilbox`
HOST_PATH_HTTPD_DATADIR	`./data/www`
Resulting local project path	`/home/cytopia/repo/devilbox/data/www`
Selected PHP version	`5.6`
Host address alias	`10.254.254.254` (see prerequisites)

The Resulting local project path is the path where all projects are stored locally on your host operating system. No matter what this path is, the equivalent remote path (inside the Docker container) is always /shared/httpd.

Important

Remember this, when it comes to path mapping in your IDE/editor configuration.

Configuration ¶

Install Xdebug Client for Sublime ¶

Use Sublime’s Package Control to search for and install Xdebug Client.

See also

Xdebug client

Configure Sublime ¶

Navigate to Tools -> Xdebug -> Settings - User in the menu

This will open the configuration file in Sublime

Xdebug-sublime-settings¶

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

Important

Recall the path settings from the Assumption section and adjust if your configuration differs!

Configure php.ini ¶

Note

The following example show how to configure PHP Xdebug for PHP 5.6:

Create an xdebug.ini file (must end by .ini):

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

# Navigate to PHP 5.6 ini configuration directory
host> cd cfg/php-ini-5.6/

# Create and open debug.ini file
host> vi xdebug.ini

Copy/paste all of the following lines into the above created xdebug.ini file:

xdebug.ini¶

; Defaults
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_port=9000

; The MacOS way
xdebug.remote_connect_back=0
xdebug.remote_host=10.254.254.254

; idekey value is specific to Sublime
xdebug.idekey=sublime.xdebug

; Optional: Set to true to always auto-start xdebug
xdebug.remote_autostart=false

Note

Host os and editor specific settings are highlighted in yellow and are worth googling to get a better understanding of the tools you use and to be more efficient at troubleshooting.

Restart the Devilbox ¶

Restarting the Devilbox is important in order for it to read the new PHP settings. Note that the following example only starts up PHP, HTTPD and Bind.

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

# Stop, remove stopped container and start
host> docker-compose stop
host> docker-compose rm
host> docker-compose up php httpd bind

See also

Stop and Restart (Why do docker-compose rm?)

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Docker on MacOS: Xdebug for Visual Studio Code¶

Note

Docker on MacOS requires you to create a host address alias on your loopback device.

Table of Contents

Prerequisites
Assumption
Configuration

Prerequisites ¶

Ensure you know how to customize php.ini values for the Devilbox and have a rough understanding about common Xdebug options.

See also

Important

Ensure you have created an Host address alias on MacOS and 10.254.254.254 is aliased to your localhost.

Assumption ¶

For the sake of this example, we will assume the following settings and file system paths:

Directory	Path
Devilbox git directory	`/home/cytopia/repo/devilbox`
HOST_PATH_HTTPD_DATADIR	`./data/www`
Resulting local project path	`/home/cytopia/repo/devilbox/data/www`
Selected PHP version	`5.6`
Host address alias	`10.254.254.254` (see prerequisites)

The Resulting local project path is the path where all projects are stored locally on your host operating system. No matter what this path is, the equivalent remote path (inside the Docker container) is always /shared/httpd.

Important

Remember this, when it comes to path mapping in your IDE/editor configuration.

Configuration ¶

Install vscode-php-debug for VSCode ¶

Ensure you have vscode-php-debug installed for Visual Studio Code.

See also

vscode-php-debug

Configure VSCode ¶

You will need to configure the path mapping in launch.json (VSCode configuration file):

launch.json¶

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Xdebug for Project mytest",
            "type": "php",
            "request": "launch",
            "port": 9000,
            "pathMappings": {
                "/shared/httpd/mytest/htdocs": "${workspaceFolder}/htdocs"
            }
        }, {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9000
        }
    ]
}

Important

Recall the path settings from the Assumption section and adjust if your configuration differs!

Important

The above example configures Xdebug for a single project mytest. Add more projects as you need.

See also

Configure php.ini ¶

Note

The following example show how to configure PHP Xdebug for PHP 5.6:

Create an xdebug.ini file (must end by .ini):

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

# Navigate to PHP 5.6 ini configuration directory
host> cd cfg/php-ini-5.6/

# Create and open debug.ini file
host> vi xdebug.ini

Copy/paste all of the following lines into the above created xdebug.ini file:

xdebug.ini¶

; Defaults
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_port=9000

; The MacOS way
xdebug.remote_connect_back=0
xdebug.remote_host=10.254.254.254

; idekey value is specific to Visual Studio Code
xdebug.idekey=VSCODE

; Optional: Set to true to always auto-start xdebug
xdebug.remote_autostart=false

Important

Ensure you have created a Host address alias on MacOS pointing to 10.254.254.254 as stated in the prerequisites section above!

Note

Host os and editor specific settings are highlighted in yellow and are worth googling to get a better understanding of the tools you use and to be more efficient at troubleshooting.

Restart the Devilbox ¶

Restarting the Devilbox is important in order for it to read the new PHP settings. Note that the following example only starts up PHP, HTTPD and Bind.

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

# Stop, remove stopped container and start
host> docker-compose stop
host> docker-compose rm
host> docker-compose up php httpd bind

See also

Stop and Restart (Why do docker-compose rm?)

See also

Docker on Windows ¶

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Docker on Windows: Xdebug for Atom¶

Docker for Windows requires a well known IP address in order to connect to the host operating system.

Table of Contents

Prerequisites
- General
- Gather Host IP address
Assumption
Configuration

Prerequisites ¶

General ¶

Ensure you know how to customize php.ini values for the Devilbox and have a rough understanding about common Xdebug options.

See also

Gather Host IP address ¶

On Windows you will have to manually retrieve the IP address to which Xdebug should connect to via xdebug.remote_host.

When you have done no custom configuration in your Virtual Switch manager, Docker for Windows will use the Default Switch automatically.

Windows: Virtual Switch Manager example screenshot

Open command line
Enter ipconfig
Look for the IP4 address in Default Switch (e.g.: 192.168.0.12)

Windows: ipconfig example output

Important

192.168.0.12 is meant as an example and will eventually differ on your system. Ensure you substitute it with the correct IP address.

See also

Assumption ¶

For the sake of this example, we will assume the following settings and file system paths:

Directory	Path
Devilbox git directory	`/home/cytopia/repo/devilbox`
HOST_PATH_HTTPD_DATADIR	`./data/www`
Resulting local project path	`/home/cytopia/repo/devilbox/data/www`
Selected PHP version	`5.6`
DockerNAT IP address	`192.168.0.12`
Virtual Switch IP address	`192.168.0.12`

The Resulting local project path is the path where all projects are stored locally on your host operating system. No matter what this path is, the equivalent remote path (inside the Docker container) is always /shared/httpd.

Important

Remember this, when it comes to path mapping in your IDE/editor configuration.

Configuration ¶

Install php-debug for Atom ¶

Ensure you have php-debug installed for Atom.

See also

php-debug

Configure Atom ¶

You will need to configure the path mapping in config.cson (Atom configuration file) or via UI:

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

Recall the path settings from the Assumption section and adjust if your configuration differs!

Important

On Windows you have to use \\ as directory separators for the local path mapping. E.g.: C:\\Users\\projects.

Configure php.ini ¶

Note

The following example show how to configure PHP Xdebug for PHP 5.6:

Create an xdebug.ini file (must end by .ini):

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

# Navigate to PHP 5.6 ini configuration directory
host> cd cfg/php-ini-5.6/

# Create and open debug.ini file
host> vi xdebug.ini

Copy/paste all of the following lines into the above created xdebug.ini file:

xdebug.ini¶

; Defaults
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_port=9000

; The Windows way
xdebug.remote_connect_back=0
xdebug.remote_host=192.168.0.12

; idekey value is specific to Atom
xdebug.idekey=xdebug.atom

; Optional: Set to true to always auto-start xdebug
xdebug.remote_autostart=false

Important

Ensure you have retrieved the correct DockerNAT IP address as stated in the prerequisites section above!

Note

Host os and editor specific settings are highlighted in yellow and are worth googling to get a better understanding of the tools you use and to be more efficient at troubleshooting.

Restart the Devilbox ¶

Restarting the Devilbox is important in order for it to read the new PHP settings. Note that the following example only starts up PHP, HTTPD and Bind.

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

# Stop, remove stopped container and start
host> docker-compose stop
host> docker-compose rm
host> docker-compose up php httpd bind

See also

Stop and Restart (Why do docker-compose rm?)

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Docker on Windows: Xdebug for PhpStorm¶

Docker for Windows requires a well known IP address in order to connect to the host operating system.

Table of Contents

Prerequisites
- General
- Gather Host IP address
Assumption
Configuration

Prerequisites ¶

General ¶

Ensure you know how to customize php.ini values for the Devilbox and have a rough understanding about common Xdebug options.

See also

Gather Host IP address ¶

On Windows you will have to manually retrieve the IP address to which Xdebug should connect to via xdebug.remote_host.

When you have done no custom configuration in your Virtual Switch manager, Docker for Windows will use the Default Switch automatically.

Windows: Virtual Switch Manager example screenshot

Open command line
Enter ipconfig
Look for the IP4 address in Default Switch (e.g.: 192.168.0.12)

Windows: ipconfig example output

Important

192.168.0.12 is meant as an example and will eventually differ on your system. Ensure you substitute it with the correct IP address.

See also

Assumption ¶

For the sake of this example, we will assume the following settings and file system paths:

Directory	Path
Devilbox git directory	`/home/cytopia/repo/devilbox`
HOST_PATH_HTTPD_DATADIR	`./data/www`
Resulting local project path	`/home/cytopia/repo/devilbox/data/www`
Selected PHP version	`5.6`
DockerNAT IP address	`192.168.0.12`
Virtual Switch IP address	`192.168.0.12`

The Resulting local project path is the path where all projects are stored locally on your host operating system. No matter what this path is, the equivalent remote path (inside the Docker container) is always /shared/httpd.

Important

Remember this, when it comes to path mapping in your IDE/editor configuration.

Configuration ¶

Configure PhpStorm ¶

1. Ensure Xdebug port is set to 9000

PHPStorm settings: Xdebug

2. Set path mapping

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:

PHPStorm settings: path mapping

Important

Recall the path settings from the Assumption section and adjust if your configuration differs!

3. Ensure DBGp proxy settings are configured

PHPStorm settings: DBGp Proxy

Configure php.ini ¶

Note

The following example show how to configure PHP Xdebug for PHP 5.6:

Create an xdebug.ini file (must end by .ini):

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

# Navigate to PHP 5.6 ini configuration directory
host> cd cfg/php-ini-5.6/

# Create and open debug.ini file
host> vi xdebug.ini

Copy/paste all of the following lines into the above created xdebug.ini file:

xdebug.ini¶

; Defaults
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_port=9000

; The Windows way
xdebug.remote_connect_back=0
xdebug.remote_host=192.168.0.12

; idekey value is specific to PhpStorm
xdebug.idekey=PHPSTORM

; Optional: Set to true to always auto-start xdebug
xdebug.remote_autostart=false

Important

Ensure you have retrieved the correct DockerNAT IP address as stated in the prerequisites section above!

Note

Host os and editor specific settings are highlighted in yellow and are worth googling to get a better understanding of the tools you use and to be more efficient at troubleshooting.

Restart the Devilbox ¶

Restarting the Devilbox is important in order for it to read the new PHP settings. Note that the following example only starts up PHP, HTTPD and Bind.

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

# Stop, remove stopped container and start
host> docker-compose stop
host> docker-compose rm
host> docker-compose up php httpd bind

See also

Stop and Restart (Why do docker-compose rm?)

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Docker on Windows: Xdebug for Sublime Text 3¶

Docker for Windows requires a well known IP address in order to connect to the host operating system.

Table of Contents

Prerequisites
- General
- Gather Host IP address
Assumption
Configuration

Prerequisites ¶

General ¶

Ensure you know how to customize php.ini values for the Devilbox and have a rough understanding about common Xdebug options.

See also

Gather Host IP address ¶

On Windows you will have to manually retrieve the IP address to which Xdebug should connect to via xdebug.remote_host.

When you have done no custom configuration in your Virtual Switch manager, Docker for Windows will use the Default Switch automatically.

Windows: Virtual Switch Manager example screenshot

Open command line
Enter ipconfig
Look for the IP4 address in Default Switch (e.g.: 192.168.0.12)

Windows: ipconfig example output

Important

192.168.0.12 is meant as an example and will eventually differ on your system. Ensure you substitute it with the correct IP address.

See also

Assumption ¶

For the sake of this example, we will assume the following settings and file system paths:

Directory	Path
Devilbox git directory	`/home/cytopia/repo/devilbox`
HOST_PATH_HTTPD_DATADIR	`./data/www`
Resulting local project path	`/home/cytopia/repo/devilbox/data/www`
Selected PHP version	`5.6`
DockerNAT IP address	`192.168.0.12`
Virtual Switch IP address	`192.168.0.12`

The Resulting local project path is the path where all projects are stored locally on your host operating system. No matter what this path is, the equivalent remote path (inside the Docker container) is always /shared/httpd.

Important

Remember this, when it comes to path mapping in your IDE/editor configuration.

Configuration ¶

Install Xdebug Client for Sublime ¶

Use Sublime’s Package Control to search for and install Xdebug Client.

See also

Xdebug client

Configure Sublime ¶

Navigate to Tools -> Xdebug -> Settings - User in the menu

This will open the configuration file in Sublime

Xdebug-sublime-settings¶

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

Important

Recall the path settings from the Assumption section and adjust if your configuration differs!

Configure php.ini ¶

Note

The following example show how to configure PHP Xdebug for PHP 5.6:

Create an xdebug.ini file (must end by .ini):

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

# Navigate to PHP 5.6 ini configuration directory
host> cd cfg/php-ini-5.6/

# Create and open debug.ini file
host> vi xdebug.ini

Copy/paste all of the following lines into the above created xdebug.ini file:

xdebug.ini¶

; Defaults
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_port=9000

; The Windows way
xdebug.remote_connect_back=0
xdebug.remote_host=192.168.0.12

; idekey value is specific to Sublime
xdebug.idekey=sublime.xdebug

; Optional: Set to true to always auto-start xdebug
xdebug.remote_autostart=false

Important

Ensure you have retrieved the correct DockerNAT IP address as stated in the prerequisites section above!

Note

Host os and editor specific settings are highlighted in yellow and are worth googling to get a better understanding of the tools you use and to be more efficient at troubleshooting.

Restart the Devilbox ¶

Restarting the Devilbox is important in order for it to read the new PHP settings. Note that the following example only starts up PHP, HTTPD and Bind.

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

# Stop, remove stopped container and start
host> docker-compose stop
host> docker-compose rm
host> docker-compose up php httpd bind

See also

Stop and Restart (Why do docker-compose rm?)

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Docker on Windows: Xdebug for Visual Studio Code¶

Docker for Windows requires a well known IP address in order to connect to the host operating system.

Table of Contents

Prerequisites
- General
- Gather Host IP address
Assumption
Configuration

Prerequisites ¶

General ¶

Ensure you know how to customize php.ini values for the Devilbox and have a rough understanding about common Xdebug options.

See also

Gather Host IP address ¶

On Windows you will have to manually retrieve the IP address to which Xdebug should connect to via xdebug.remote_host.

When you have done no custom configuration in your Virtual Switch manager, Docker for Windows will use the Default Switch automatically.

Windows: Virtual Switch Manager example screenshot

Open command line
Enter ipconfig
Look for the IP4 address in Default Switch (e.g.: 192.168.0.12)

Windows: ipconfig example output

Important

192.168.0.12 is meant as an example and will eventually differ on your system. Ensure you substitute it with the correct IP address.

See also

Enable and configure MailHog

Assumption ¶

For the sake of this example, we will assume the following settings and file system paths:

Directory	Path
Devilbox git directory	`/home/cytopia/repo/devilbox`
HOST_PATH_HTTPD_DATADIR	`./data/www`
Resulting local project path	`/home/cytopia/repo/devilbox/data/www`
Selected PHP version	`5.6`
DockerNAT IP address	`192.168.0.12`
Virtual Switch IP address	`192.168.0.12`

The Resulting local project path is the path where all projects are stored locally on your host operating system. No matter what this path is, the equivalent remote path (inside the Docker container) is always /shared/httpd.

Important

Remember this, when it comes to path mapping in your IDE/editor configuration.

Configuration ¶

Install vscode-php-debug for VSCode ¶

Ensure you have vscode-php-debug installed for Visual Studio Code.

See also

vscode-php-debug

Configure VSCode ¶

You will need to configure the path mapping in launch.json (VSCode configuration file):

launch.json¶

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Xdebug for Project mytest",
            "type": "php",
            "request": "launch",
            "port": 9000,
            "pathMappings": {
                "/shared/httpd/mytest/htdocs": "${workspaceRoot}/htdocs"
            }
        }, {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9000
        }
    ]
}

Important

Recall the path settings from the Assumption section and adjust if your configuration differs!

Important

The above example configures Xdebug for a single project mytest. Add more projects as you need.

See also

Configure php.ini ¶

Note

The following example show how to configure PHP Xdebug for PHP 5.6:

Create an xdebug.ini file (must end by .ini):

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

# Navigate to PHP 5.6 ini configuration directory
host> cd cfg/php-ini-5.6/

# Create and open debug.ini file
host> vi xdebug.ini

Copy/paste all of the following lines into the above created xdebug.ini file:

xdebug.ini¶

; Defaults
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_port=9000

; The Windows way
xdebug.remote_connect_back=0
xdebug.remote_host=192.168.0.12

; idekey value is specific to Visual Studio Code
xdebug.idekey=VSCODE

; Optional: Set to true to always auto-start xdebug
xdebug.remote_autostart=false

Important

Ensure you have retrieved the correct DockerNAT IP address as stated in the prerequisites section above!

Note

Host os and editor specific settings are highlighted in yellow and are worth googling to get a better understanding of the tools you use and to be more efficient at troubleshooting.

Restart the Devilbox ¶

Restarting the Devilbox is important in order for it to read the new PHP settings. Note that the following example only starts up PHP, HTTPD and Bind.

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

# Stop, remove stopped container and start
host> docker-compose stop
host> docker-compose rm
host> docker-compose up php httpd bind

See also

Stop and Restart (Why do docker-compose rm?)

See also

Docker Toolbox ¶

Docker Toolbox configuration is equal, no matter if it is started on MacOS or Windows, as both use a Linux system inside VirtualBox.

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Docker Toolbox: Xdebug for Atom¶

Docker Toolbox regardless of running on MacOS or Windows requires an additional port-forward from your host operating system to the Docker Toolbox machine.

Table of Contents

Prerequisites
- General
- Docker Toolbox port-forward
Assumption
Configuration

Prerequisites ¶

General ¶

Ensure you know how to customize php.ini values for the Devilbox and have a rough understanding about common Xdebug options.

See also

Docker Toolbox port-forward ¶

Forward host port 9000 to Docker Toolbox machine:

Your IDE/editor will open up port 9000 on your host operating system. PHP Xdebug requires this port to connect to in order to send Xdebug events. As Docker Toolbox itself runs in a virtual machine, you need to forward traffic from the same port in that virtual machine back to your host operating system.

See also

SSH port-forward on Docker Toolbox from host

SSH port-forward on host to Docker Toolbox

Assumption ¶

For the sake of this example, we will assume the following settings and file system paths:

Directory	Path
Devilbox git directory	`/home/cytopia/repo/devilbox`
HOST_PATH_HTTPD_DATADIR	`./data/www`
Resulting local project path	`/home/cytopia/repo/devilbox/data/www`
Selected PHP version	`5.6`

The Resulting local project path is the path where all projects are stored locally on your host operating system. No matter what this path is, the equivalent remote path (inside the Docker container) is always /shared/httpd.

Important

Remember this, when it comes to path mapping in your IDE/editor configuration.

Configuration ¶

Install php-debug for Atom ¶

Ensure you have php-debug installed for Atom.

See also

php-debug

Configure Atom ¶

You will need to configure the path mapping in config.cson (Atom configuration file) or via UI:

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

Recall the path settings from the Assumption section and adjust if your configuration differs!

Configure php.ini ¶

Note

The following example show how to configure PHP Xdebug for PHP 5.6:

Create an xdebug.ini file (must end by .ini):

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

# Navigate to PHP 5.6 ini configuration directory
host> cd cfg/php-ini-5.6/

# Create and open debug.ini file
host> vi xdebug.ini

Copy/paste all of the following lines into the above created xdebug.ini file:

xdebug.ini¶

; Defaults
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_port=9000

; The Docker Toolbox way
xdebug.remote_connect_back=0
xdebug.remote_host=docker.for.lin.host.internal

; idekey value is specific to Atom
xdebug.idekey=xdebug.atom

; Optional: Set to true to always auto-start xdebug
xdebug.remote_autostart=false

Important

Ensure the port-forward is in place as mentioned in the Prerequisites section.

Note

Host os and editor specific settings are highlighted in yellow and are worth googling to get a better understanding of the tools you use and to be more efficient at troubleshooting.

Restart the Devilbox ¶

Restarting the Devilbox is important in order for it to read the new PHP settings. Note that the following example only starts up PHP, HTTPD and Bind.

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

# Stop, remove stopped container and start
host> docker-compose stop
host> docker-compose rm
host> docker-compose up php httpd bind

See also

Stop and Restart (Why do docker-compose rm?)

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Docker Toolbox: Xdebug for PhpStorm¶

Docker Toolbox regardless of running on MacOS or Windows requires an additional port-forward from your host operating system to the Docker Toolbox machine.

Table of Contents

Prerequisites
- General
- Docker Toolbox port-forward
Assumption
Configuration

Prerequisites ¶

General ¶

Ensure you know how to customize php.ini values for the Devilbox and have a rough understanding about common Xdebug options.

See also

Docker Toolbox port-forward ¶

Forward host port 9000 to Docker Toolbox machine:

Your IDE/editor will open up port 9000 on your host operating system. PHP Xdebug requires this port to connect to in order to send Xdebug events. As Docker Toolbox itself runs in a virtual machine, you need to forward traffic from the same port in that virtual machine back to your host operating system.

See also

SSH port-forward on Docker Toolbox from host

SSH port-forward on host to Docker Toolbox

Assumption ¶

For the sake of this example, we will assume the following settings and file system paths:

Directory	Path
Devilbox git directory	`/home/cytopia/repo/devilbox`
HOST_PATH_HTTPD_DATADIR	`./data/www`
Resulting local project path	`/home/cytopia/repo/devilbox/data/www`
Selected PHP version	`5.6`

The Resulting local project path is the path where all projects are stored locally on your host operating system. No matter what this path is, the equivalent remote path (inside the Docker container) is always /shared/httpd.

Important

Remember this, when it comes to path mapping in your IDE/editor configuration.

Configuration ¶

Configure PhpStorm ¶

1. Ensure Xdebug port is set to 9000

PHPStorm settings: Xdebug

2. Set path mapping

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:

PHPStorm settings: path mapping

Important

Recall the path settings from the Assumption section and adjust if your configuration differs!

3. Ensure DBGp proxy settings are configured

PHPStorm settings: DBGp Proxy

Configure php.ini ¶

Note

The following example show how to configure PHP Xdebug for PHP 5.6:

Create an xdebug.ini file (must end by .ini):

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

# Navigate to PHP 5.6 ini configuration directory
host> cd cfg/php-ini-5.6/

# Create and open debug.ini file
host> vi xdebug.ini

Copy/paste all of the following lines into the above created xdebug.ini file:

xdebug.ini¶

; Defaults
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_port=9000

; The Docker Toolbox way
xdebug.remote_connect_back=0
xdebug.remote_host=docker.for.lin.host.internal

; idekey value is specific to PhpStorm
xdebug.idekey=PHPSTORM

; Optional: Set to true to always auto-start xdebug
xdebug.remote_autostart=false

Important

Ensure the port-forward is in place as mentioned in the Prerequisites section.

Note

Host os and editor specific settings are highlighted in yellow and are worth googling to get a better understanding of the tools you use and to be more efficient at troubleshooting.

Restart the Devilbox ¶

Restarting the Devilbox is important in order for it to read the new PHP settings. Note that the following example only starts up PHP, HTTPD and Bind.

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

# Stop, remove stopped container and start
host> docker-compose stop
host> docker-compose rm
host> docker-compose up php httpd bind

See also

Stop and Restart (Why do docker-compose rm?)

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Docker Toolbox: Xdebug for Sublime Text 3¶

Docker Toolbox regardless of running on MacOS or Windows requires an additional port-forward from your host operating system to the Docker Toolbox machine.

Table of Contents

Prerequisites
- General
- Docker Toolbox port-forward
Assumption
Configuration

Prerequisites ¶

General ¶

Ensure you know how to customize php.ini values for the Devilbox and have a rough understanding about common Xdebug options.

See also

Docker Toolbox port-forward ¶

Forward host port 9000 to Docker Toolbox machine:

Your IDE/editor will open up port 9000 on your host operating system. PHP Xdebug requires this port to connect to in order to send Xdebug events. As Docker Toolbox itself runs in a virtual machine, you need to forward traffic from the same port in that virtual machine back to your host operating system.

See also

SSH port-forward on Docker Toolbox from host

SSH port-forward on host to Docker Toolbox

Assumption ¶

For the sake of this example, we will assume the following settings and file system paths:

Directory	Path
Devilbox git directory	`/home/cytopia/repo/devilbox`
HOST_PATH_HTTPD_DATADIR	`./data/www`
Resulting local project path	`/home/cytopia/repo/devilbox/data/www`
Selected PHP version	`5.6`

The Resulting local project path is the path where all projects are stored locally on your host operating system. No matter what this path is, the equivalent remote path (inside the Docker container) is always /shared/httpd.

Important

Remember this, when it comes to path mapping in your IDE/editor configuration.

Configuration ¶

Install Xdebug Client for Sublime ¶

Use Sublime’s Package Control to search for and install Xdebug Client.

See also

Xdebug client

Configure Sublime ¶

Navigate to Tools -> Xdebug -> Settings - User in the menu

This will open the configuration file in Sublime

Xdebug-sublime-settings¶

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

Important

Recall the path settings from the Assumption section and adjust if your configuration differs!

Configure php.ini ¶

Note

The following example show how to configure PHP Xdebug for PHP 5.6:

Create an xdebug.ini file (must end by .ini):

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

# Navigate to PHP 5.6 ini configuration directory
host> cd cfg/php-ini-5.6/

# Create and open debug.ini file
host> vi xdebug.ini

Copy/paste all of the following lines into the above created xdebug.ini file:

xdebug.ini¶

; Defaults
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_port=9000

; The Docker Toolbox way
xdebug.remote_connect_back=0
xdebug.remote_host=docker.for.lin.host.internal

; idekey value is specific to Sublime
xdebug.idekey=sublime.xdebug

; Optional: Set to true to always auto-start xdebug
xdebug.remote_autostart=false

Important

Ensure the port-forward is in place as mentioned in the Prerequisites section.

Note

Host os and editor specific settings are highlighted in yellow and are worth googling to get a better understanding of the tools you use and to be more efficient at troubleshooting.

Restart the Devilbox ¶

Restarting the Devilbox is important in order for it to read the new PHP settings. Note that the following example only starts up PHP, HTTPD and Bind.

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

# Stop, remove stopped container and start
host> docker-compose stop
host> docker-compose rm
host> docker-compose up php httpd bind

See also

Stop and Restart (Why do docker-compose rm?)

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Docker Toolbox: Xdebug for Visual Studio Code¶

Docker Toolbox regardless of running on MacOS or Windows requires an additional port-forward from your host operating system to the Docker Toolbox machine.

Table of Contents

Prerequisites
- General
- Docker Toolbox port-forward
Assumption
Configuration

Prerequisites ¶

General ¶

Ensure you know how to customize php.ini values for the Devilbox and have a rough understanding about common Xdebug options.

See also

Docker Toolbox port-forward ¶

Forward host port 9000 to Docker Toolbox machine:

Your IDE/editor will open up port 9000 on your host operating system. PHP Xdebug requires this port to connect to in order to send Xdebug events. As Docker Toolbox itself runs in a virtual machine, you need to forward traffic from the same port in that virtual machine back to your host operating system.

See also

SSH port-forward on Docker Toolbox from host

SSH port-forward on host to Docker Toolbox

Assumption ¶

For the sake of this example, we will assume the following settings and file system paths:

Directory	Path
Devilbox git directory	`/home/cytopia/repo/devilbox`
HOST_PATH_HTTPD_DATADIR	`./data/www`
Resulting local project path	`/home/cytopia/repo/devilbox/data/www`
Selected PHP version	`5.6`

The Resulting local project path is the path where all projects are stored locally on your host operating system. No matter what this path is, the equivalent remote path (inside the Docker container) is always /shared/httpd.

Important

Remember this, when it comes to path mapping in your IDE/editor configuration.

Configuration ¶

Install vscode-php-debug for VSCode ¶

Ensure you have vscode-php-debug installed for Visual Studio Code.

See also

vscode-php-debug

Configure VSCode ¶

You will need to configure the path mapping in launch.json (VSCode configuration file):

launch.json¶

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Xdebug for Project mytest",
            "type": "php",
            "request": "launch",
            "port": 9000,
            "pathMappings": {
                "/shared/httpd/mytest/htdocs": "${workspaceFolder}/htdocs"
            }
        }, {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9000
        }
    ]
}

Important

Recall the path settings from the Assumption section and adjust if your configuration differs!

Important

The above example configures Xdebug for a single project mytest. Add more projects as you need.

See also

Configure php.ini ¶

Note

The following example show how to configure PHP Xdebug for PHP 5.6:

Create an xdebug.ini file (must end by .ini):

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

# Navigate to PHP 5.6 ini configuration directory
host> cd cfg/php-ini-5.6/

# Create and open debug.ini file
host> vi xdebug.ini

Copy/paste all of the following lines into the above created xdebug.ini file:

xdebug.ini¶

; Defaults
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_port=9000

; The Docker Toolbox way
xdebug.remote_connect_back=0
xdebug.remote_host=docker.for.lin.host.internal

; idekey value is specific to Visual Studio Code
xdebug.idekey=VSCODE

; Optional: Set to true to always auto-start xdebug
xdebug.remote_autostart=false

Important

Ensure the port-forward is in place as mentioned in the Prerequisites section.

Note

Host os and editor specific settings are highlighted in yellow and are worth googling to get a better understanding of the tools you use and to be more efficient at troubleshooting.

Restart the Devilbox ¶

Restarting the Devilbox is important in order for it to read the new PHP settings. Note that the following example only starts up PHP, HTTPD and Bind.

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

# Stop, remove stopped container and start
host> docker-compose stop
host> docker-compose rm
host> docker-compose up php httpd bind

See also

Stop and Restart (Why do docker-compose rm?)

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Enable/disable PHP modules¶

Table of Contents

Enabled PHP modules
Disable PHP modules
Roadmap

See also

https://github.com/devilbox/docker-php-fpm/blob/master/doc/php-modules.md: Follow the link to see all available PHP modules for each different PHP-FPM server version.

Enabled PHP modules ¶

At the moment all PHP modules are enabled by default except ioncube, So this one is the only one you can currently enable. To do so follow the steps provided below:

Stop the Devilbox
Enable modules in .env under PHP_MODULES_ENABLE
.env¶
```
# Enable Ioncube
PHP_MODULES_ENABLE=ioncube
```
Start the Devilbox

See also

PHP_MODULES_ENABLE

Disable PHP modules ¶

If you feel there are currently too many modules loaded and you want to unload some of them by default, you can do so via a comma separated list in .env.

Stop the Devilbox

Disable modules in .env under PHP_MODULES_DISABLE

.env¶

# Disable Xdebug, Imagick and Swoole
PHP_MODULES_DISABLE=xdebug,imagick,swoole

Start the Devilbox

See also

PHP_MODULES_DISABLE

Roadmap ¶

Todo

In order to create a performent, secure and sane default PHP-FPM server, only really required modules should be enabled by default. The rest is up to the user to enable others as needed.

The current discussion about default modules can be found at the following Github issue. Please participate and give your ideas: https://github.com/cytopia/devilbox/issues/299

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Read log files¶

The logging behaviour is determined by the value of DOCKER_LOGS inside your .env file. By default logs are mounted to the host operating system for convenient access.

Table of Contents

Mounted logs
Docker logs
Checklist

Mounted logs ¶

By default log files for PHP, the webserver and the MySQL server are mounted to the host system into your Devilbox git directory under ./log/. All logs are separated by service version in the following format: ./log/<service>-<version>/

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
├── php-fpm-7.1/
│   ├── php-fpm.access
│   ├── php-fpm.error

Use your favorite tools to view log files such as tail, less, more, cat or others.

Important

Currently logs are only mounted for PHP, HTTPD and MYSQL container. All other services will log to Docker logs.

Docker logs ¶

You can also change the behaviour where logs are streamed by setting DOCKER_LOGS to 1 inside your .env file. When doing logs are sent to Docker logs.

When using this approach, you need to use the docker-compose logs command to view your log files from within the Devilbox git directory.

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

This currently does not work for the MySQL container, which will always log to file.

Checklist ¶

You know how to switch between file and Docker logs
You know where log files are mounted
You know how to access Docker logs

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Email catch-all¶

Devilbox Intranet¶

All your projects can send emails to whatever recipient. You do not have to worry that they will actually being sent. Each PHP container runs a local postfix mailserver that intercepts all outgoing mails and puts them into a local mailbox by the user devilbox.

In order to view sent emails open up the devilbox intranet http://localhost/mail.php. There you can also test email sending and verify that they really stay locally.

Devilbox intranet: email catch-all overview

In the above image from the intranet you can see that all emails sent to whatever recipient have been caught by the Devilbox and are available to be read.

MailHog¶

Instead of using the very basic Devilbox intranet UI for emails, you can also enable MailHog and use this to view sent email.s

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Add 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');
?>

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Work inside the PHP 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

Available tools

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 and hostnames. In other words, when you are inside the PHP container, you can reach the services via the below defined IP addresses or hostnames:

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

Note

It is recommended to use hostnames as they can be remembered much easiert.

An example to access the MySQL database from within the PHP container:

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

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

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

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

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 Setup Auto DNS.

See also

You can achieve the same on your host operating system by explicitly enabling auto-dns. See also: Setup 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 by what hostnames you can reach a specific service
You know that project urls are available inside the container and on your host

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Source 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

PHP CodeSniffer

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

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Best practice¶

If you have already operate the Devilbox, this guide is a must have. It will cover common best-practice topics as well as some tips and tricks you will want to apply.

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.

Affected env variables to consider changing:

Projects ¶

See also

Move projects to a different directory Follow this guide to keep your projects separated from the Devilbox git directory.

Backups ¶

See also

Move backups to a different directory Follow this guide to keep your backups separated from the Devilbox git directory.

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/address of each of those services to how they are defined within the Devilbox network:

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

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 mysql -p
mysql>

To access the MySQL database from your host operating system you would need the address to what it exposes to on your host (usually 127.0.0.1):

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

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

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

See also

Enable/disable PHP modules

Timezone ¶

The TIMEZONE value will affect PHP and web serverequally. 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, 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.

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Customize PHP globally¶

PHP settings can be applied globally to all projects, but are bound to a specific PHP version. This means every PHP version can have its own profile of customized settings.

Note

By default, all PHP container use roughly the same settings. This might only differ if some options or modules do not exist in a specific container.

Table of Contents

Configure PHP settings globally
- Settings via php.ini
- Settings via php-fpm.conf
Configure non-overwritable settings globally
Configure loaded PHP modules
Configure PHP-FPM service

Configure PHP settings globally ¶

PHP settings can either be applied in its php.ini configuration file or through the PHP-FPM configuration itself via php_value and php_flag.

Settings in php.ini are also picked up by the PHP command line tool, whereas php_value and php_flag settings are only valid for requests over the webserver.

This means you can set different values, when executing command line tasks and when the application is run through the browser.

Settings via php.ini ¶

To configure PHP globally via php.ini follow the provided link:

See also

php.ini

Settings via php-fpm.conf ¶

To configure PHP globally via PHP-FPM follow the provided link:

See also

php-fpm.conf

Configure non-overwritable settings globally ¶

Settings defined via php.ini, php_value and php_flag are applied globally, however they can still be overwritten by any project via the PHP function ini_set().

If you want to create PHP settings and force them, so no application can accidentally or on purpose overwrite them, you need to use php_admin_value and php_admin_flag.

Important

Keep in mind that those settings are not picked up by the command line execution of PHP, but only through the browser.

To configure PHP globally and non-overwritable via PHP-FPM follow the provided link:

See also

php-fpm.conf

Configure loaded PHP modules ¶

The .env file offers the option to specify what PHP modules to enable or disable specifically.

See also

Configure PHP-FPM service ¶

You can also configure the PHP-FPM service itself. Settings can be applied for the core service as well as for the pool. This is useful if you need to adjust performance settings such as number of running child processes, file- and memory limits, timeouts and many more.

Be sure to read up on the PHP-FPM documentation to understand what you are doing.

See also

php-fpm.conf

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Customize web server globally¶

Web server settings can be applied globally, which will affect the web server behaviour itself, but not the vhost configuration. Configuration can be done for each version separetely, which means each web server can have its own profile of customized settings.

See also

In order to customize the vhosts, have a look at the following links:

vhost-gen: Virtual host templates
vhost-gen: Customize all virtual hosts globally
vhost-gen: Customize specific virtual host
vhost-gen: Example: add sub domains

Table of Contents

Configure Apache
Configure Nginx
Devilbox specific settings

Configure Apache ¶

All settings that usually go into the main httpd.conf or apache2.conf configuration file can be overwritten or customized separately for Apache 2.2 and Apache 2.4.

See also

apache.conf

Configure Nginx ¶

All settings that usually go into the main nginx.conf configuration file can be overwritten or customized separately for Nginx stable and Nginx mainline.

See also

nginx.conf

Devilbox specific settings ¶

There are certain other settings that are directly managed by the Devilbox’s .env file in order to make other containers aware of those settings.

Important

Try to avoid to overwrite the .env settings via web server configuration files.

Use the following .env variables to customize this behaviour globally.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Connect to host OS¶

This section explains how to connect from inside a Devilbox container to the host operating system.

Table of Contents

Prerequisites
Docker on Linux
Docker for Mac
Docker for Windows
- Docker 18.03.0-ce+ and Docker compose 1.20.1+
- Docker 17.06.0-ce+ and Docker compose 1.14.0+
Docker Toolbox

Prerequisites ¶

When you want to connect from inside a Docker container to a port on your host operating system, ensure the host service is listening on all interfaces for simplicity.

The following sections will give you the IP address and/or the CNAME where the host os can be reached from within a container.

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

Important

Ensure services on the host listen on that IP address or on all interfaces.

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

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

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:

Important

Ensure your firewall is not blocking Docker to host connections.

Docker 18.03.0-ce+ and Docker compose 1.20.1+¶

CNAME: docker.for.win.host.internal
CNAME: host.docker.internal

Docker 17.06.0-ce+ and Docker compose 1.14.0+¶

CNAME: docker.for.win.host.localhost

Docker Toolbox ¶

Note

This section applies for both, Docker Toolbox on MacOS and Docker Toolbox on Windows.

Docker Toolbox behaves the same way as Docker on Linux, with one major difference. The Devilbox IP address or the custom provided CNAMEs actually refer to the Docker Toolbox machine.

In order to connect from inside the Docker container (which is inside the Docker Toolbox machine) to your host os, you need to create:

either a local port-forward on the Docker Toolbox machine (ssh -L)
or a remote port-forward on your host os (ssh -R)

For both examples we assume the following:

MySQL database exists on your host os and listens on 127.0.0.1 on port 3306
Docker Toolbox IP address is 192.168.99.100
Host IP address where SSH is listening on 172.16.0.1
Host SSH username is user
Devilbox Docker container wants to access MySQL on host os

Local port forward on Docker Toolbox ¶

Important

For that to work, your host operating system requires an SSH server to be up and running.

Initiator	From host	From port	To host	To port
Docker Toolbox	`127.0.0.1`	`3306`	`192.168.99.100`	`3306`

# From Docker Toolbox forward port 3306 (on host 172.16.0.1) to myself (192.168.99.100)
toolbox> ssh -L 3306:127.0.0.1:3306 user@172.16.0.1

See also

Remote port-forward on host os ¶

Important

For that to work, your host operating system requires an SSH client (ssh binary).

Initiator	From host	From port	To host	To port
Host os	`127.0.0.1`	`3306`	`192.168.99.100`	`3306`

# From host os forward port 3306 (from loopback 127.0.0.1) to Docker Toolbox (192.168.99.100)
host> ssh -R 3306:127.0.0.1:3306 docker@192.168.99.100

See also

Post steps ¶

With either of the above you have achieved the exact behaviour as Docker on Linux for one single service/port (MySQL port 3306).

You must now follow the steps for Docker on Linux to actually connect to that service from within the Devilbox Docker container.

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Connect to other Docker container¶

Other Docker container can either be accessed by connecting back to the host os or by adding its image directly to the Devilbox stack.

Table of Contents

Any Docker container on host os
Add Docker container to Devilbox network
Add Docker container to Devilbox stack

Any Docker container on host os ¶

To connect to any other Docker container on your host os from within the Devilbox Docker container, you first need to make sure, you are able to connect to your host os from within the Devilbox Docker container.

See also

Connect to host OS
Once you are able to connect to the host os, start any other Docker container and make its port that you want to access available to your host os by specifying -p. An example with e.g. an external Grafana container might look like this:
```
host> docker run -d --name=grafana -p 3000:3000 grafana/grafana
```
You can then connect to your host os on port 3000 from within the Devilbox Docker container and be able to use it.

Add Docker container to Devilbox network ¶

The Devilbox defines its own bridge network, usually called devilbox_app_net.

Note

The name may vary depending on the name of the Devilbox directory. It assembles itself by <Devilbox_dir_name>_app_net.

Start the Devilbox
Start your container of choice
```
host> docker run -d --name mycontainer
```

Attach your container to the Devilbox network

host> docker network connect devilbox_app_net mycontainer

Once you have done that, mycontainer is then part of the internal Devilbox network and is able to resolve Devilbox container by its name and vice-versa.

Connect from Devilbox PHP container to mycontainer

From inside the PHP container, you can then refer to your container by its hostname mycontainer

Add Docker container to Devilbox stack ¶

Alternatively you can also add any Docker container to the Devilbox network by adding an image it to the Devilbox stack directly.

See also

Add your own Docker image

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Connect to external hosts¶

Connecting from inside a Devilbox Docker container to any external host works out of the box. The only thing you need is internet/network access and know its hostname or IP address.

Each container has internet access, thus you can curl, fetch, connect to or download any online resources from within the container.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Add custom CNAME DNS entries¶

You can add an infinite number of custom CNAME records that will be available in your running Docker container. If Auto-DNS is turned on, those records will be available on your host operating system as well.

See also

Setup Auto DNS

Table of Contents

Why and what?
How?

Why and what?¶

This might be useful if you have an IP address or hostname on your LAN or any other domain which you want to expose to your container by a different CNAME of your choice.

Think of it as setting your /etc/hosts, but which will be distributed accross all hosts which are using the Devilbox’ bundled DNS server.

How?¶

Adjust the EXTRA_HOSTS variable inside .env to add as many CNAME’s as you need.

As an example, to create a CNAME mywebserver.com pointing to 172.16.238.1, change your .env file as shown below:

.env¶

EXTRA_HOSTS=mywebserver.loc=172.16.238.1

See also

See EXTRA_HOSTS for an in-depth explanation with multiple examples.

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

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

docker-compose.override.yml

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 Cockroachc DB Docker image:

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

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.240
    # 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_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

Custom scripts per PHP version¶

You can provide custom startup commands via bash scripts to each of the PHP container individually. This may be useful to specify additional software to install or additional settings to apply during the initial startup.

See also

Custom scripts globally (equal for all PHP versions)
Autostarting NodeJS Apps

Note

Per PHP version scripts are always executed before global scripts.

Table of Contents

General
- Where
- When
- How
Examples
- Installing Microsoft ODBC driver
- Running commands as devilbox user

General ¶

You can add custom shell scripts for each PHP version separately.

Important

Provided scripts must end by the file extension .sh and should be executable. Anything not ending by .sh will be ignored.

Important

Provided scripts will be executed by the root user within the PHP container.

Where ¶

Startup scripts can be added to cfg/php-startup-X.Y/. See the directory structure for PHP startup script directories inside ./cfg/ directory:

host> ls -l path/to/devilbox/cfg/ | grep 'php-startup'

drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-startup-5.2/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-startup-5.3/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-startup-5.4/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-startup-5.5/
drwxr-xr-x  2 cytopia cytopia 4096 Apr  3 22:04 php-startup-5.6/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-startup-7.0/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-startup-7.1/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-startup-7.2/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-startup-7.3/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-startup-7.4/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-startup-8.0/

Custom scripts are added by placing a file into cfg/php-startup-X.X/ (where X.X stands for your PHP version). The file must end by .sh in order to be executed by the PHP container.

Some of the PHP startup directories contain a few example files with the file suffix -example. If you want to use them, copy these files to a new name without the -example suffix and ensure they end by .sh.

When ¶

The scripts will be executed by the PHP container during initial startup. Whenever you change your scripts, ensure to restart the Devilbox.

How ¶

The scripts will always be executed inside the PHP container (Debian Linux) and will be run with root privileges. It is however possible to drop privileges within the script to have them executed as a normal user.

Examples ¶

Installing Microsoft ODBC driver ¶

This example will add Microsofts ODBC driver to PHP 7.1. These drivers are required in order to make the PHP modules pdo_sqlsrv and sqlsrv work. The two mentioned modules are already available in the PHP container, but are explicitly disabled via PHP_MODULES_DISABLE.

They won’t work without the ODBC driver installed, which unfortunately cannot be bundled, as it requires every user to accept a license/EULA by Microsoft.

# Navigate to starup dir of PHP 7.1
host> cd path/to/devilbox/cfg/php-startup-7.1

# Create an .sh file
host> touch ms-odbc.sh

# Open the file in your favourite editor
host> vi ms-odbc.sh

Paste the following into ms-obbc.sh and ensure to accept the EULA by changing ACCEPT_EULA=N to ACCEPT_EULA=Y.

cfg/php-startup-7.1/install-ms-odbc.sh¶

!/bin/bash
#
# This script will automatically install the Microsoft ODBC driver for MsSQL
# support for PHP during startup.
#
# In order for it to work, you must read and accept their License/EULA:
# https://odbceula.blob.core.windows.net/eula17/LICENSE172.TXT
#


# ------------------------------------------------------------------------------------------------
# EDIT THE VARIABLE BELOW TO ACCEPT THE EULA (If you agree to their terms)
# ------------------------------------------------------------------------------------------------

###
### Set this to "Y" (capital 'Y') if you accept the EULA.
###
ACCEPT_EULA=N



# ------------------------------------------------------------------------------------------------
# DO NOT EDIT BELOW THIS LINE
# ------------------------------------------------------------------------------------------------

###
### Where to retrieve the deb package
###
MSODBC_URL="https://packages.microsoft.com/debian/8/prod/pool/main/m/msodbcsql17/"


###
### Pre-flight check
###
if [ "${ACCEPT_EULA}" != "Y" ]; then
     echo "MS ODBC EULA not accepted. Aborting installation."
     exit 0
fi


###
### EULA accepted, so we can proceed
###

# Extract latest *.deb packate
MSODBC_DEB="$( curl -k -sS "${MSODBC_URL}" | grep -Eo 'msodbcsql[-._0-9]+?_amd64\.deb' | tail -1 )"

# Download to temporary location
curl -k -sS "${MSODBC_URL}${MSODBC_DEB}" > "/tmp/${MSODBC_DEB}"

# Install
ACCEPT_EULA="${ACCEPT_EULA}" dpkg -i "/tmp/${MSODBC_DEB}"

# Remove artifacts
rm -f "/tmp/${MSODBC_DEB}"

Important

The script will not work, if you have not accepted the EULA.

Running commands as devilbox user ¶

As mentioned above, all scripts are run by the root user. If you do need something to be executed as the normal user: devilbox, you can simply su inside the shell script.

The following example will install grunt and start a NodeJS application as the devilbox user for the PHP 7.1 Docker container only.

cfg/php-startup-7.1/myscript.sh¶

# Install grunt as devilbox user
su -c "npm install grunt" -l devilbox

# Start a NodeJS application with pm2 as devilbox user
su -c "cd /shared/httpd/my-node/src/; pm2 start index.js" -l devilbox

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Custom scripts globally¶

You can provide custom startup commands via bash scripts that are executed by all PHP container. This may be useful to specify additional software to install or additional settings to apply during the initial startup.

See also

Custom scripts per PHP version (individually for different PHP versions)
Autostarting NodeJS Apps

Note

Global scripts are always executed after per PHP version scripts.

Table of Contents

General
- Where
- When
- How
Examples
- Running commands as devilbox user

General ¶

You can add shell scripts that are executed for all PHP container equally.

Important

Provided scripts must end by the file extension .sh and should be executable. Anything not ending by .sh will be ignored.

Important

Provided scripts will be executed by the root user within the PHP container.

Where ¶

Startup scripts can be added to autostart/.

host> ls -l path/to/devilbox/

drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 autostart/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 backups/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 bash/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 ca/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 cfg/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 compose/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 data/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 docs/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 mail/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 mod/

Custom scripts are added by placing a file into autostart/. The file must end by .sh in order to be executed by the PHP container.

When ¶

The scripts will be executed by the PHP container during initial startup. Whenever you change your scripts, ensure to restart the Devilbox.

How ¶

The scripts will always be executed inside the PHP container (Debian Linux) and will be run with root privileges. It is however possible to drop privileges within the script to have them executed as a normal user.

Examples ¶

Running commands as devilbox user ¶

As mentioned above, all scripts are run by the root user. If you do need something to be executed as the normal user: devilbox, you can simply su inside the shell script.

The following example will install grunt and start a NodeJS application as the devilbox user for whatever PHP container has been started.

autostart/myscript.sh¶

# Install grunt as devilbox user
su -c "npm install grunt" -l devilbox

# Start a NodeJS application with pm2 as devilbox user
su -c "cd /shared/httpd/my-node/src/; pm2 start index.js" -l devilbox

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Autostarting NodeJS Apps¶

You can have all of your NodeJS applications spin up automtically as soon as you docker-compose up. This can be achieved by makeing use of pm2 (Node.js Process Manager) and the autostart feature.

See also

Read more about how to add scripts for autostart commands:

Custom scripts per PHP version (individually for different PHP versions)
Custom scripts globally (equal for all PHP versions)

Table of Contents

Self-built
- Assumption
- The script
Pre-built
Reverse proxy NodeJS

Self-built ¶

Simply add a script ending by .sh to the autostart/ directory that will accomplish this. The following example will make use of pm2 to spin up your NodeJS application.

Assumption ¶

Path to your NodeJS project (within the Docker container): /shared/httpd/my-node/src
Name of the JS file to startup: index.js

The script ¶

Add the following script to autostart/

autostart/myscript.sh¶

su -c "cd /shared/httpd/my-node/src; pm2 start index.js" -l devilbox

The whole command is wrapped into su to ensure the application will be started as the user devilbox.
cd tells it to you enter the directory where index.js can be found
And finally pm2 will take care about starting up your javascript file.

Once the Devilbox is running, you can enter the PHP container and verify with pm2 list that everything is running as expected.

Pre-built ¶

Instead of writing multiple scripts for multiple applications, you can also make use of the pre-shipped script that allows you to start unlimitted NodeJS applications via pm2 .

The following script is provided in autostart/run-node-js-projects.sh-example and needs to be copied to a file ending by .sh

host> cd /path/to/devilbox
host> cd autostart
host> cp run-node-js-projects.sh-example run-node-js-projects.sh

In that newly created file, you can simply add the full paths (path inside the Docker containre) of your Javascript files that need to be started. There is already one example which is not commented. Change this to your path and add as many lines as you have projects to startup.

autostart/run-node-js-projects.sh¶

#!/usr/bin/env bash
#
# This is a generic example to startup your NodeJS projects with
# pm2 (https://github.com/Unitech/pm2)
#
# Important: As everything is run by the root user, you must explicitly direct the
#            commands to the devilbox user.
#



# Add the full paths of your Nodejs projects startup files into this array
# Each project separated by a newline and enclosed in double quotes. (No commas!)
# Paths are internal paths inside the PHP container.
NODE_PROJECTS=(
	#"/shared/httpd/my-rhost/js/index.js"
	#"/shared/httpd/my-node-hello-world/name/run.js"
	#"/shared/httpd/another-node-project/javascript/run.js"
)


# Check if any projects have been defined
if [ ${#NODE_PROJECTS[@]} -eq 0 ]; then
	echo "No projects defined. Exiting."
	exit 0
fi


# This loops over the paths, separates base directory and filename and will run it in the background
# as the user devilbox. There shouldn't be any need to change anything here.
for item in ${NODE_PROJECTS[*]}; do
	NODE_PATH="$( dirname "${item}" )"
	NODE_FILE="$( basename "${item}" )"

	if [ ! -d "${NODE_PATH}" ]; then
		>&2 echo "[Warning], skipping startup, directory does not exist: ${NODE_PATH}"
		continue;
	fi
	if [ ! -f "${NODE_PATH}/${NODE_FILE}" ]; then
		>&2 echo "[Warning], skipping startup, file does not exist: ${NODE_PATH}/${NODE_FILE}"
		continue;
	fi

	echo "su -c \"cd ${NODE_PATH}; pm2 start ${NODE_FILE}\" -l devilbox"
	su -c "cd ${NODE_PATH}; pm2 start ${NODE_FILE}" -l devilbox
done

Reverse proxy NodeJS ¶

If you also want to know how to reverse proxy your NodeJS service and have it available via the web server including HTTPS support have a look at the following links:

See also

Imagine you have started an application within the PHP container that creates a listening port (e.g.: NodeJS). This will now only listen on the PHP container and you would have to adjust the docker-compose.yml definition in order to have that port available outside to your host OS.

Alternatively, there is a simple way to reverse proxy it to the already running web server and even make use of the already available HTTPS feature.

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Virtual host templates¶

Table of Contents

Overview
Virtual host Templates
Reverse proxy Templates

Overview ¶

What is it?¶

vhost-gen templates are yaml files which contain a general definition for a virtual host definition. Those templates contain placeholders in the form of __<NAME>__ which will be replaced by settings applied to the Devilbox.

See also

vhost-gen

Template files ¶

By default, vhost-gen templates are located within the Devilbox root directory under cfg/vhost-gen/. The templates file names are suffixed with -example-<type> and are absolutely identical to what is shipped inside each Devilbox web server Docker container.

Note

Also note that nginx stable and nginx mainline share the same template as their configuration syntax is identical.

Normal virtual host ¶

All template files ending by -example-vhost can be used to customize a normal file serving virtual host.

host> tree -L 1 cfg/vhost-gen/

cfg/vhost-gen/
├── apache22.yml-example-rproxy
├── apache22.yml-example-vhost
├── apache24.yml-example-rproxy
├── apache24.yml-example-vhost
├── nginx.yml-example-rproxy
├── nginx.yml-example-vhost
└── README.md

0 directories, 7 files

Reverse proxy ¶

All template files ending by -example-rproxy can be used to create a reverse proxy for your project.

host> tree -L 1 cfg/vhost-gen/

cfg/vhost-gen/
├── apache22.yml-example-rproxy
├── apache22.yml-example-vhost
├── apache24.yml-example-rproxy
├── apache24.yml-example-vhost
├── nginx.yml-example-rproxy
├── nginx.yml-example-vhost
└── README.md

0 directories, 7 files

Template sections ¶

All vhost-gen templates consist of three sections:

Section	Description
`vhost`	This is the part that is actually rendered into the vhost configuration. All other sections will be inserted into this one.
`vhost_type`	The vhost type determines the type of vhost: reverse proxy or document root based vhost. The Devilbox currently does not support reverse proxy vhost.
`features`	The feature section contains many sub-sections that are replaced into the `vhost` section before final rendering.

Virtual host Templates ¶

These templates can be used to alter the behaviour of the vhost on a per project base or globally.

Apache 2.2 template ¶

apache22.yml-example-vhost¶

---

# Apache 2.2 vHost Template defintion for vhost-gen.py
#
# The 'feature' section contains optional features that can be enabled via
# conf.yml and will then be replaced into the main vhost ('structure' section)
# into their corresponding position:
#
#    __XDOMAIN_REQ__
#    __PHP_FPM__
#    __ALIASES__
#    __DENIES__
#    __STATUS__
#
# The features itself also contain variables to be adjusted in conf.yml
# and will then be replaced in their corresponding feature section
# before being replaced into the vhost section (if enabled):
#
# PHP-FPM:
#    __PHP_ADDR__
#    __PHP_PORT__
# XDomain:
#    __REGEX__
# Alias:
#    __REGEX__
#    __PATH__
# Deny:
#    __REGEX__
# Status:
#    __REGEX__
#
# Variables to be replaced directly in the vhost configuration can also be set
# in conf.yml and include:
#    __VHOST_NAME__
#    __DOCUMENT_ROOT__
#    __INDEX__
#    __ACCESS_LOG__
#    __ERROR_LOG__
#    __PHP_ADDR__
#    __PHP_PORT__
#

###
### Notes about Apache
###

#
# 1. Each same directive is checked in order of definition (last one wins)
# 2. Directives are ordered: Directory, DirectoryMatch, Files, and finally Location (last one wins)
#   * Last match always takes precedence
#
# Exception: Directories, where shortest path is matched first
# Exception: ProxyPass and Alias first match and then stops

###
### Basic vHost skeleton
###
### Note: Reverse Proxy section must be last for Apache 2.2
###
vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName __VHOST_NAME__

      CustomLog  "__ACCESS_LOG__" combined
      ErrorLog   "__ERROR_LOG__"

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

###
### vHost Type (normal or reverse proxy)
###
vhost_type:
  # Normal vHost (-p)
  docroot: |
    # Define the vhost to serve files
    DocumentRoot "__DOCUMENT_ROOT__"
    <Directory "__DOCUMENT_ROOT__">
        DirectoryIndex __INDEX__

        AllowOverride All
        Options All

        RewriteEngine on
        RewriteBase /

        Order allow,deny
        Allow from all
    </Directory>

  # Reverse Proxy (-r http(s)://ADDR:PORT)
  rproxy: |
    # ProxyRequests:     Disable "Forward Proxy"
    # ProxyPreserveHost: Pass "Host" header to remote
    # ProxyVia:          Add "Via" header
    ProxyRequests     Off
    ProxyPreserveHost On
    ProxyVia          On
    <Location __LOCATION__>
        # Reverse Proxy
        ProxyPass         __PROXY_PROTO__://__PROXY_ADDR__:__PROXY_PORT__/ retry=0
        ProxyPassReverse  __PROXY_PROTO__://__PROXY_ADDR__:__PROXY_PORT__/
    </Location>

  # Reverse Proxy with websocket support (-r ws(s)://ADDR:PORT)
  rproxy_ws: |
    # ProxyRequests:     Disable "Forward Proxy"
    # ProxyPreserveHost: Pass "Host" header to remote
    # ProxyVia:          Add "Via" header
    ProxyRequests     Off
    ProxyPreserveHost On
    ProxyVia          On
    <Location __LOCATION__>
        # Websocket Rewrite Settings
        RewriteEngine On
        RewriteCond %{HTTP:Connection} Upgrade   [NC]
        RewriteCond %{HTTP:Upgrade}    websocket [NC]
        RewriteRule ^/?(.*)$ __WS_PROTO__://__PROXY_ADDR__:__PROXY_PORT__/$1 [P,L]
        # Reverse Proxy
        ProxyPass         __PROXY_PROTO__://__PROXY_ADDR__:__PROXY_PORT__/ retry=0
        ProxyPassReverse  __PROXY_PROTO__://__PROXY_ADDR__:__PROXY_PORT__/
    </Location>


###
### Optional features to be enabled in vHost
###
features:

  # SSL Configuration
  ssl: |
    SSLEngine on
    SSLCertificateFile    "__SSL_PATH_CRT__"
    SSLCertificateKeyFile "__SSL_PATH_KEY__"
    SSLProtocol           __SSL_PROTOCOLS__
    SSLHonorCipherOrder   __SSL_HONOR_CIPHER_ORDER__
    SSLCipherSuite        __SSL_CIPHERS__

  # Redirect to SSL directive
  redirect: |
    RedirectMatch (.*) https://__VHOST_NAME__:__SSL_PORT__$1

  # PHP-FPM will not be applied to a reverse proxy!
  php_fpm: |
    # PHP-FPM Definition
    ProxyPassMatch ^/(.*\.php(/.*)?)$ fcgi://__PHP_ADDR__:__PHP_PORT____DOCUMENT_ROOT__/$1 timeout=__PHP_TIMEOUT__

  alias: |
    # Alias Definition
    Alias "__ALIAS__" "__PATH____ALIAS__"
    <Location "__ALIAS__">
        ProxyPass !
    __XDOMAIN_REQ__
    </Location>
    <Directory "__PATH____ALIAS__">
        Order allow,deny
        Allow from all
    </Directory>

  deny: |
    # Deny Definition
    <LocationMatch "__REGEX__">
        Order allow,deny
        Deny from all
    </LocationMatch>

  server_status: |
    # Status Page
    <Location __REGEX__>
        SetHandler server-status
        Order allow,deny
        Allow from all
    </Location>

  # https://stackoverflow.com/a/42558499
  # https://fetch.spec.whatwg.org/#forbidden-header-name
  xdomain_request: |
    # Allow cross domain request from these hosts
    SetEnvIf Origin "__REGEX__" AccessControlAllowOrigin=$0
    Header always set Access-Control-Allow-Origin   %{AccessControlAllowOrigin}e env=AccessControlAllowOrigin
    Header always set Access-Control-Allow-Methods  "HEAD, GET, POST, PUT, PATCH, DELETE, OPTIONS"
    Header always set Access-Control-Allow-Headers  "Accept, Authorization, Content-Security-Policy, Content-Type, Location, Origin, X-Requested-With"
    Header always set Access-Control-Expose-Headers "Content-Security-Policy, Location"
    Header always set Access-Control-Max-Age "0"
    # Added a rewrite to respond with a 200 SUCCESS on every OPTIONS request.
    RewriteEngine On
    RewriteCond %{REQUEST_METHOD} OPTIONS
    RewriteRule ^(.*)$ $1 [R=200,L]

Apache 2.4 template ¶

apache24.yml-example-vhost¶

---

# Apache 2.4 vHost Template defintion for vhost-gen.py
#
# The 'feature' section contains optional features that can be enabled via
# conf.yml and will then be replaced into the main vhost ('structure' section)
# into their corresponding position:
#
#    __XDOMAIN_REQ__
#    __PHP_FPM__
#    __ALIASES__
#    __DENIES__
#    __STATUS__
#
# The features itself also contain variables to be adjusted in conf.yml
# and will then be replaced in their corresponding feature section
# before being replaced into the vhost section (if enabled):
#
# PHP-FPM:
#    __PHP_ADDR__
#    __PHP_PORT__
# XDomain:
#    __REGEX__
# Alias:
#    __REGEX__
#    __PATH__
# Deny:
#    __REGEX__
# Status:
#    __REGEX__
#
# Variables to be replaced directly in the vhost configuration can also be set
# in conf.yml and include:
#    __VHOST_NAME__
#    __DOCUMENT_ROOT__
#    __INDEX__
#    __ACCESS_LOG__
#    __ERROR_LOG__
#    __PHP_ADDR__
#    __PHP_PORT__
#

###
### Notes about Apache
###

#
# 1. Each same directive is checked in order of definition (last one wins)
# 2. Directives are ordered: Directory, DirectoryMatch, Files, and finally Location (last one wins)
#   * Last match always takes precedence
#
# Exception: Directories, where shortest path is matched first
# Exception: ProxyPass and Alias first match and then stops

###
### Basic vHost skeleton
###
vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName __VHOST_NAME__
      Protocols  __HTTP_PROTO__

      CustomLog  "__ACCESS_LOG__" combined
      ErrorLog   "__ERROR_LOG__"

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

###
### vHost Type (normal or reverse proxy)
###
vhost_type:
  # Normal vHost (-p)
  docroot: |
    # Define the vhost to serve files
    DocumentRoot "__DOCUMENT_ROOT__"
    <Directory "__DOCUMENT_ROOT__">
        DirectoryIndex __INDEX__

        AllowOverride All
        Options All

        RewriteEngine on
        RewriteBase /

        Order allow,deny
        Allow from all
        Require all granted
    </Directory>

  # Reverse Proxy (-r http(s)://ADDR:PORT)
  rproxy: |
    # ProxyRequests:     Disable "Forward Proxy"
    # ProxyPreserveHost: Pass "Host" header to remote
    # ProxyAddHeaders:   Add "X-Forward-*" headers
    # ProxyVia:          Add "Via" header
    ProxyRequests     Off
    ProxyPreserveHost On
    ProxyAddHeaders   On
    ProxyVia          On
    <Location __LOCATION__>
        # Reverse Proxy
        ProxyPass         __PROXY_PROTO__://__PROXY_ADDR__:__PROXY_PORT__/ retry=0
        ProxyPassReverse  __PROXY_PROTO__://__PROXY_ADDR__:__PROXY_PORT__/
    </Location>

  # Reverse Proxy with websocket support (-r ws(s)://ADDR:PORT)
  rproxy_ws: |
    # ProxyRequests:     Disable "Forward Proxy"
    # ProxyPreserveHost: Pass "Host" header to remote
    # ProxyAddHeaders:   Add "X-Forward-*" headers
    # ProxyVia:          Add "Via" header
    ProxyRequests     Off
    ProxyPreserveHost On
    ProxyAddHeaders   On
    ProxyVia          On
    <Location __LOCATION__>
        # Websocket Rewrite Settings
        RewriteEngine On
        RewriteCond %{HTTP:Connection} Upgrade   [NC]
        RewriteCond %{HTTP:Upgrade}    websocket [NC]
        RewriteRule ^/?(.*)$ __WS_PROTO__://__PROXY_ADDR__:__PROXY_PORT__/$1 [P,L]
        # Reverse Proxy
        ProxyPass         __PROXY_PROTO__://__PROXY_ADDR__:__PROXY_PORT__/ retry=0
        ProxyPassReverse  __PROXY_PROTO__://__PROXY_ADDR__:__PROXY_PORT__/
    </Location>


###
### Optional features to be enabled in vHost
###
features:

  # SSL Configuration
  ssl: |
    SSLEngine on
    SSLCertificateFile    "__SSL_PATH_CRT__"
    SSLCertificateKeyFile "__SSL_PATH_KEY__"
    SSLProtocol           __SSL_PROTOCOLS__
    SSLHonorCipherOrder   __SSL_HONOR_CIPHER_ORDER__
    SSLCipherSuite        __SSL_CIPHERS__

  # Redirect to SSL directive
  redirect: |
    RedirectMatch (.*) https://__VHOST_NAME__:__SSL_PORT__$1

  # PHP-FPM will not be applied to a reverse proxy!
  php_fpm: |
    # In case for PHP-FPM 5.2 compatibility use 'GENERIC' instead of 'FPM'
    # https://httpd.apache.org/docs/2.4/mod/mod_proxy_fcgi.html#proxyfcgibackendtype
    ProxyFCGIBackendType FPM

    # PHP-FPM Definition
    <FilesMatch \.php$>
        Require all granted
        SetHandler proxy:fcgi://__PHP_ADDR__:__PHP_PORT__
    </FilesMatch>

    <Proxy "fcgi://__PHP_ADDR__:__PHP_PORT__/">
        ProxySet timeout=__PHP_TIMEOUT__
        ProxySet connectiontimeout=__PHP_TIMEOUT__
    </Proxy>

    # If the php file doesn't exist, disable the proxy handler.
    # This will allow .htaccess rewrite rules to work and
    # the client will see the default 404 page of Apache
    RewriteCond %{REQUEST_FILENAME} \.php$
    RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_URI} !-f
    RewriteRule (.*) - [H=text/html]

  alias: |
    # Alias Definition
    Alias "__ALIAS__" "__PATH____ALIAS__"
    <Location "__ALIAS__">
        ProxyPass !
    __XDOMAIN_REQ__
    </Location>
    <Directory "__PATH____ALIAS__">
        Order allow,deny
        Allow from all
        Require all granted
    </Directory>

  deny: |
    # Deny Definition
    <LocationMatch "__REGEX__">
        Order allow,deny
        Deny from all
    </LocationMatch>

  server_status: |
    # Status Page
    <Location __REGEX__>
        SetHandler server-status
        Order allow,deny
        Allow from all
        Require all granted
    </Location>

  # https://stackoverflow.com/a/42558499
  # https://fetch.spec.whatwg.org/#forbidden-header-name
  xdomain_request: |
    # Allow cross domain request from these hosts
    SetEnvIf Origin "__REGEX__" AccessControlAllowOrigin=$0
    Header always set Access-Control-Allow-Origin   %{AccessControlAllowOrigin}e env=AccessControlAllowOrigin
    Header always set Access-Control-Allow-Methods  "HEAD, GET, POST, PUT, PATCH, DELETE, OPTIONS"
    Header always set Access-Control-Allow-Headers  "Accept, Authorization, Content-Security-Policy, Content-Type, Location, Origin, X-Requested-With"
    Header always set Access-Control-Expose-Headers "Content-Security-Policy, Location"
    Header always set Access-Control-Max-Age "0"
    # Added a rewrite to respond with a 200 SUCCESS on every OPTIONS request.
    RewriteEngine On
    RewriteCond %{REQUEST_METHOD} OPTIONS
    RewriteRule ^(.*)$ $1 [R=200,L]

Nginx template ¶

nginx.yml-example-vhost¶

---

# Nginx vHost Template defintion for vhost-gen.py
#
# The 'feature' section contains optional features that can be enabled via
# conf.yml and will then be replaced into the main vhost ('structure' section)
# into their corresponding position:
#
#    __XDOMAIN_REQ__
#    __PHP_FPM__
#    __ALIASES__
#    __DENIES__
#    __STATUS__
#
# The features itself also contain variables to be adjusted in conf.yml
# and will then be replaced in their corresponding feature section
# before being replaced into the vhost section (if enabled):
#
# PHP-FPM:
#    __PHP_ADDR__
#    __PHP_PORT__
# XDomain:
#    __REGEX__
# Alias:
#    __REGEX__
#    __PATH__
# Deny:
#    __REGEX__
# Status:
#    __REGEX__
#
# Variables to be replaced directly in the vhost configuration can also be set
# in conf.yml and include:
#    __VHOST_NAME__
#    __DOCUMENT_ROOT__
#    __INDEX__
#    __ACCESS_LOG__
#    __ERROR_LOG__
#    __PHP_ADDR__
#    __PHP_PORT__
#


###
### Basic vHost skeleton
###
vhost: |
  server {
      listen       __PORT____HTTP_PROTO____DEFAULT_VHOST__;
      server_name  __VHOST_NAME__;

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

  __REDIRECT__
  __SSL__
  __VHOST_DOCROOT__
  __VHOST_RPROXY__
  __PHP_FPM__
  __ALIASES__
  __DENIES__
  __SERVER_STATUS__
      # Custom directives
  __CUSTOM__
  }


###
### vHost Type (normal or reverse proxy)
###
vhost_type:
  # Normal vHost (-p)
  docroot: |
    # Define the vhost to serve files
    root         "__DOCUMENT_ROOT__";
    index        __INDEX__;

  # Reverse Proxy (-r http(s)://ADDR:PORT)
  rproxy: |
    # Define Reverse Proxy
    location __LOCATION__ {
        # https://stackoverflow.com/a/72586833
        proxy_set_header Host            $host;
        proxy_set_header X-Real-IP       $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        # Proxy connection
        proxy_pass __PROXY_PROTO__://__PROXY_ADDR__:__PROXY_PORT__;
    }

  # Reverse Proxy with websocket support (-r ws(s)://ADDR:PORT)
  rproxy_ws: |
    # Define Reverse Proxy with Websock support
    location __LOCATION__ {
        # https://stackoverflow.com/a/72586833
        proxy_set_header Host            $host;
        proxy_set_header X-Real-IP       $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        # Websocket settings
        proxy_http_version          1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "Upgrade";
        # Proxy connection
        proxy_pass __PROXY_PROTO__://__PROXY_ADDR__:__PROXY_PORT__;
    }


###
### Optional features to be enabled in vHost
###
features:

  # SSL Configuration
  ssl: |
    ssl_certificate           __SSL_PATH_CRT__;
    ssl_certificate_key       __SSL_PATH_KEY__;
    ssl_protocols             __SSL_PROTOCOLS__;
    ssl_prefer_server_ciphers __SSL_HONOR_CIPHER_ORDER__;
    ssl_ciphers               __SSL_CIPHERS__;

  # Redirect to SSL directive
  redirect: |
    return 301 https://__VHOST_NAME__:__SSL_PORT__$request_uri;

  # PHP-FPM will not be applied to a reverse proxy!
  php_fpm: |
    # PHP-FPM Definition
    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }
    location ~ \.php?$ {
        try_files $uri = 404;
        include fastcgi_params;

        # https://stackoverflow.com/questions/1733306/nginx-errors-readv-and-recv-failed/51457613#51457613
        fastcgi_keep_conn off;

        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_split_path_info ^(.+\.php)(.*)$;

        fastcgi_pass __PHP_ADDR__:__PHP_PORT__;
        fastcgi_read_timeout __PHP_TIMEOUT__;

        fastcgi_index index.php;
        fastcgi_intercept_errors on;
    }

  alias: |
    # Alias Definition
    location ~ __ALIAS__ {
        root  __PATH__;
    __XDOMAIN_REQ__
    }

  deny: |
    # Deny Definition
    location ~ __REGEX__ {
        deny all;
    }

  server_status: |
    # Status Page
    location ~ __REGEX__ {
        stub_status on;
        access_log off;
    }

  xdomain_request: |
    # Allow cross domain request from these hosts
    # https://fetch.spec.whatwg.org/#forbidden-header-name
    if ( $http_origin ~* (__REGEX__) ) {
        add_header "Access-Control-Allow-Origin"   "$http_origin";
        add_header 'Access-Control-Allow-Methods'  'HEAD, GET, POST, PUT, PATCH, DELETE, OPTIONS';
        add_header 'Access-Control-Allow-Headers'  'Accept, Authorization, Content-Security-Policy, Content-Type, Location, Origin, X-Requested-With';
        add_header 'Access-Control-Expose-Headers' 'Content-Security-Policy, Location';
        add_header 'Access-Control-Max-Age' 0;
        return 200;
    }

Reverse proxy Templates ¶

These templates can be used to change a normal vhost into a reverse proxy project. This might be useful if you use NodeJs applications for example.

Important

Do not apply those templates globally. They are intended to be used on a per project base.

Note

In order to use the Reverse Proxy templates you will only need to adjust the listening port, everything else will work as already defined. So you simply need to copy those files into your project directory. Lines that need to be changed are marked below. The currently set default listening port is 8000.

Apache 2.2 template ¶

apache22.yml-example-rproxy¶

---

# Apache 2.2 Reverse Proxy Template defintion for vhost-gen.py
#
# The 'feature' section contains optional features that can be enabled via
# conf.yml and will then be replaced into the main vhost ('structure' section)
# into their corresponding position:
#
#    __XDOMAIN_REQ__
#    __ALIASES__
#    __DENIES__
#    __STATUS__
#
# The features itself also contain variables to be adjusted in conf.yml
# and will then be replaced in their corresponding feature section
# before being replaced into the vhost section (if enabled):
#
# XDomain:
#    __REGEX__
# Alias:
#    __REGEX__
#    __PATH__
# Deny:
#    __REGEX__
# Status:
#    __REGEX__
#
# Variables to be replaced directly in the vhost configuration can also be set
# in conf.yml and include:
#    __VHOST_NAME__
#    __DOCUMENT_ROOT__
#    __INDEX__
#    __ACCESS_LOG__
#    __ERROR_LOG__
#

###
### Notes about Apache
###

#
# 1. Each same directive is checked in order of definition (last one wins)
# 2. Directives are ordered: Directory, DirectoryMatch, Files, and finally Location (last one wins)
#   * Last match always takes precedence
#
# Exception: Directories, where shortest path is matched first
# Exception: ProxyPass and Alias first match and then stops

###
### Basic vHost skeleton
###
### Note: Reverse Proxy section must be last for Apache 2.2
###
vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName __VHOST_NAME__

      CustomLog  "__ACCESS_LOG__" combined
      ErrorLog   "__ERROR_LOG__"

      # ProxyRequests:     Disable "Forward Proxy"
      # ProxyPreserveHost: Pass "Host" header to remote
      # ProxyVia:          Add "Via" header
      ProxyRequests     Off
      ProxyPreserveHost On
      ProxyVia          On
      <Location />
          # Reverse Proxy definition (Ensure to adjust the port, currently '8000')
          ProxyPass         http://php:8000/ retry=0
          ProxyPassReverse  http://php:8000/
      </Location>

  __REDIRECT__
  __SSL__
  __ALIASES__
  __DENIES__
  __SERVER_STATUS__
      # Custom directives
  __CUSTOM__
  </VirtualHost>

###
### vHost Type (normal or reverse proxy)
###
vhost_type:
  docroot: ""
  rproxy: ""

###
### Optional features to be enabled in vHost
###
features:

  # SSL Configuration
  ssl: |
    SSLEngine on
    SSLCertificateFile    "__SSL_PATH_CRT__"
    SSLCertificateKeyFile "__SSL_PATH_KEY__"
    SSLProtocol           __SSL_PROTOCOLS__
    SSLHonorCipherOrder   __SSL_HONOR_CIPHER_ORDER__
    SSLCipherSuite        __SSL_CIPHERS__

  # Redirect to SSL directive
  redirect: |
    RedirectMatch (.*) https://__VHOST_NAME__:__SSL_PORT__$1

  # PHP-FPM left empty, as we are an reverse proxy configuration
  php_fpm: ""

  alias: |
    # Alias Definition
    Alias "__ALIAS__" "__PATH____ALIAS__"
    <Location "__ALIAS__">
        ProxyPass !
    __XDOMAIN_REQ__
    </Location>
    <Directory "__PATH____ALIAS__">
        Order allow,deny
        Allow from all
    </Directory>

  deny: |
    # Deny Definition
    <LocationMatch "__REGEX__">
        Order allow,deny
        Deny from all
    </LocationMatch>

  server_status: |
    # Status Page
    <Location __REGEX__>
        SetHandler server-status
        Order allow,deny
        Allow from all
    </Location>

  # https://stackoverflow.com/a/42558499
  # https://fetch.spec.whatwg.org/#forbidden-header-name
  xdomain_request: |
    # Allow cross domain request from these hosts
    SetEnvIf Origin "__REGEX__" AccessControlAllowOrigin=$0
    Header always set Access-Control-Allow-Origin   %{AccessControlAllowOrigin}e env=AccessControlAllowOrigin
    Header always set Access-Control-Allow-Methods  "HEAD, GET, POST, PUT, PATCH, DELETE, OPTIONS"
    Header always set Access-Control-Allow-Headers  "Accept, Authorization, Content-Security-Policy, Content-Type, Location, Origin, X-Requested-With"
    Header always set Access-Control-Expose-Headers "Content-Security-Policy, Location"
    Header always set Access-Control-Max-Age "0"
    # Added a rewrite to respond with a 200 SUCCESS on every OPTIONS request.
    RewriteEngine On
    RewriteCond %{REQUEST_METHOD} OPTIONS
    RewriteRule ^(.*)$ $1 [R=200,L]

Apache 2.4 template ¶

apache24.yml-example-rproxy¶

---

# Apache 2.4 Reverse Proxy Template defintion for vhost-gen.py
#
# The 'feature' section contains optional features that can be enabled via
# conf.yml and will then be replaced into the main vhost ('structure' section)
# into their corresponding position:
#
#    __XDOMAIN_REQ__
#    __ALIASES__
#    __DENIES__
#    __STATUS__
#
# The features itself also contain variables to be adjusted in conf.yml
# and will then be replaced in their corresponding feature section
# before being replaced into the vhost section (if enabled):
#
# XDomain:
#    __REGEX__
# Alias:
#    __REGEX__
#    __PATH__
# Deny:
#    __REGEX__
# Status:
#    __REGEX__
#
# Variables to be replaced directly in the vhost configuration can also be set
# in conf.yml and include:
#    __VHOST_NAME__
#    __DOCUMENT_ROOT__
#    __INDEX__
#    __ACCESS_LOG__
#    __ERROR_LOG__
#

###
### Notes about Apache
###

#
# 1. Each same directive is checked in order of definition (last one wins)
# 2. Directives are ordered: Directory, DirectoryMatch, Files, and finally Location (last one wins)
#   * Last match always takes precedence
#
# Exception: Directories, where shortest path is matched first
# Exception: ProxyPass and Alias first match and then stops

###
### Basic vHost skeleton
###
vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName __VHOST_NAME__
      Protocols  __HTTP_PROTO__

      CustomLog  "__ACCESS_LOG__" combined
      ErrorLog   "__ERROR_LOG__"

      # ProxyRequests:     Disable "Forward Proxy"
      # ProxyPreserveHost: Pass "Host" header to remote
      # ProxyAddHeaders:   Add "X-Forward-*" headers
      # ProxyVia:          Add "Via" header
      ProxyRequests     Off
      ProxyPreserveHost On
      ProxyAddHeaders   On
      ProxyVia          On
      <Location />
          # Reverse Proxy definition (Ensure to adjust the port, currently '8000')
          ProxyPass         http://php:8000/ retry=0
          ProxyPassReverse  http://php:8000/
      </Location>

  __REDIRECT__
  __SSL__
  __ALIASES__
  __DENIES__
  __SERVER_STATUS__
      # Custom directives
  __CUSTOM__
  </VirtualHost>

###
### vHost Type (normal or reverse proxy)
###
vhost_type:
  docroot: ""
  rproxy: ""

###
### Optional features to be enabled in vHost
###
features:

  # SSL Configuration
  ssl: |
    SSLEngine on
    SSLCertificateFile    "__SSL_PATH_CRT__"
    SSLCertificateKeyFile "__SSL_PATH_KEY__"
    SSLProtocol           __SSL_PROTOCOLS__
    SSLHonorCipherOrder   __SSL_HONOR_CIPHER_ORDER__
    SSLCipherSuite        __SSL_CIPHERS__

  # Redirect to SSL directive
  redirect: |
    RedirectMatch (.*) https://__VHOST_NAME__:__SSL_PORT__$1

  # PHP-FPM left empty, as we are an reverse proxy configuration
  php_fpm: ""

  alias: |
    # Alias Definition
    Alias "__ALIAS__" "__PATH____ALIAS__"
    <Location "__ALIAS__">
        ProxyPass !
    __XDOMAIN_REQ__
    </Location>
    <Directory "__PATH____ALIAS__">
        Order allow,deny
        Allow from all
        Require all granted
    </Directory>

  deny: |
    # Deny Definition
    <LocationMatch "__REGEX__">
        Order allow,deny
        Deny from all
    </LocationMatch>

  server_status: |
    # Status Page
    <Location __REGEX__>
        SetHandler server-status
        Order allow,deny
        Allow from all
        Require all granted
    </Location>

  # https://stackoverflow.com/a/42558499
  # https://fetch.spec.whatwg.org/#forbidden-header-name
  xdomain_request: |
    # Allow cross domain request from these hosts
    SetEnvIf Origin "__REGEX__" AccessControlAllowOrigin=$0
    Header always set Access-Control-Allow-Origin   %{AccessControlAllowOrigin}e env=AccessControlAllowOrigin
    Header always set Access-Control-Allow-Methods  "HEAD, GET, POST, PUT, PATCH, DELETE, OPTIONS"
    Header always set Access-Control-Allow-Headers  "Accept, Authorization, Content-Security-Policy, Content-Type, Location, Origin, X-Requested-With"
    Header always set Access-Control-Expose-Headers "Content-Security-Policy, Location"
    Header always set Access-Control-Max-Age "0"
    # Added a rewrite to respond with a 200 SUCCESS on every OPTIONS request.
    RewriteEngine On
    RewriteCond %{REQUEST_METHOD} OPTIONS
    RewriteRule ^(.*)$ $1 [R=200,L]

Nginx template ¶

nginx.yml-example-rproxy¶

---

# Nginx Reverse Proxy Template defintion for vhost-gen.py
#
# The 'feature' section contains optional features that can be enabled via
# conf.yml and will then be replaced into the main vhost ('structure' section)
# into their corresponding position:
#
#    __XDOMAIN_REQ__
#    __ALIASES__
#    __DENIES__
#    __STATUS__
#
# The features itself also contain variables to be adjusted in conf.yml
# and will then be replaced in their corresponding feature section
# before being replaced into the vhost section (if enabled):
#
# XDomain:
#    __REGEX__
# Alias:
#    __REGEX__
#    __PATH__
# Deny:
#    __REGEX__
# Status:
#    __REGEX__
#
# Variables to be replaced directly in the vhost configuration can also be set
# in conf.yml and include:
#    __VHOST_NAME__
#    __DOCUMENT_ROOT__
#    __INDEX__
#    __ACCESS_LOG__
#    __ERROR_LOG__
#


###
### Basic vHost skeleton
###
vhost: |
  server {
      listen       __PORT____HTTP_PROTO____DEFAULT_VHOST__;
      server_name  __VHOST_NAME__;

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

      # Reverse Proxy definition (Ensure to adjust the port, currently '8000')
      location / {
        # https://stackoverflow.com/a/72586833
        proxy_set_header Host            $host;
        proxy_set_header X-Real-IP       $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        # Proxy connection
        proxy_pass http://php:8000;
      }

  __REDIRECT__
  __SSL__
  __ALIASES__
  __DENIES__
  __SERVER_STATUS__
      # Custom directives
  __CUSTOM__
  }

###
### vHost Type (normal or reverse proxy)
###
vhost_type:
  docroot: ""
  rproxy: ""

###
### Optional features to be enabled in vHost
###
features:

  # SSL Configuration
  ssl: |
    ssl_certificate           __SSL_PATH_CRT__;
    ssl_certificate_key       __SSL_PATH_KEY__;
    ssl_protocols             __SSL_PROTOCOLS__;
    ssl_prefer_server_ciphers __SSL_HONOR_CIPHER_ORDER__;
    ssl_ciphers               __SSL_CIPHERS__;

  # Redirect to SSL directive
  redirect: |
    return 301 https://__VHOST_NAME__:__SSL_PORT__$request_uri;

  # PHP-FPM left empty, as we are an reverse proxy configuration
  php_fpm: ""

  alias: |
    # Alias Definition
    location ~ __ALIAS__ {
        root  __PATH__;
    __XDOMAIN_REQ__
    }

  deny: |
    # Deny Definition
    location ~ __REGEX__ {
        deny all;
    }

  server_status: |
    # Status Page
    location ~ __REGEX__ {
        stub_status on;
        access_log off;
    }

  xdomain_request: |
    # Allow cross domain request from these hosts
    # https://fetch.spec.whatwg.org/#forbidden-header-name
    if ( $http_origin ~* (__REGEX__) ) {
        add_header "Access-Control-Allow-Origin"   "$http_origin";
        add_header 'Access-Control-Allow-Methods'  'HEAD, GET, POST, PUT, PATCH, DELETE, OPTIONS';
        add_header 'Access-Control-Allow-Headers'  'Accept, Authorization, Content-Security-Policy, Content-Type, Location, Origin, X-Requested-With';
        add_header 'Access-Control-Expose-Headers' 'Content-Security-Policy, Location';
        add_header 'Access-Control-Max-Age' 0;
        return 200;
    }

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Customize all virtual hosts globally¶

Table of Contents

Prerequisite
Apply templates globally to all vhosts

Prerequisite ¶

Ensure you have read and understood how vhost-gen templates work and where to find them

See also

Virtual host templates

Apply templates globally to all vhosts ¶

When applying those templates, you do it globally for all projects. The only exception is if you have already a specific vhost template for a project in place.

See also

Customize specific virtual host

In order for template files to be picked up by the web server they must be copied to their correct filename.

Web server	Example template	Template name
Apache 2.2	`apache22.yml-example-vhost`	`apache22.yml`
Apache 2.4	`apache24.yml-example-vhost`	`apache24.yml`
Nginx stable	`nginx.yml-example-vhost`	`nginx.yml`
Nginx mainline	`nginx.yml-example-vhost`	`nginx.yml`

Important

Do not use *.yml-example-rproxy templates for global configuration. These are only intended to be used on a per project base.

Note

If you simply copy the files to their corresponding template file name, nothing will change as those templates reflect the same values the web servers are using.

Apache 2.2 ¶

Navigate to cfg/vhost-gen/ inside the Devilbox directory
Copy apache22.yml-example-vhost to apache22.yml and restart the Devilbox
Whenever you adjust apache22.yml, you need to restart the Devilbox

Apache 2.4 ¶

Navigate to cfg/vhost-gen/ inside the Devilbox directory
Copy apache24.yml-example-vhost to apache24.yml and restart the Devilbox
Whenever you adjust apache24.yml, you need to restart the Devilbox

Nginx stable and Nginx mainline ¶

Navigate to cfg/vhost-gen/ inside the Devilbox directory
Copy nginx.yml-example-vhost to nginx.yml and restart the Devilbox
Whenever you adjust nginx.yml, you need to restart the Devilbox

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Customize specific virtual host¶

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 project 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 cfg/vhost-gen/.

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 cfg/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/cfg/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: .devilbox.

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 cfg/vhost-gen/*.yml-example-* ./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	`apache24.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.

Virtual host vs Reverse Proxy¶

Note

Ensure you have read Virtual host templates

Table of Contents

Motivation
Benefits
Creating a reverse proxy

Motivation ¶

By default, all virtual hosts will simply serve files located in your document root directory within your project directory. Sometimes however your project is already its own server that will serve requests through a listening network port. (e.g. a running NodeJS application). This listening port will however only be available inside the PHP container (or any other container) you have added to the Devilbox and the webserver is not aware of this.

For this kind of project you will want to create a reverse proxy which simply forwards the requests incoming to the webserver to your application (either to the PHP container to a specific port or to any other container you have attached).

Benefits ¶

By using the already available web server to reverse proxy requests to your service you will be able to have all the current features for you application such as:

Have it displayed in the intranet page
Have standardized domain names
Have valid HTTPS

Creating a reverse proxy ¶

Creating a reverse proxy is as simply as copying the vhost-gen templates to your project directory.

In order to make your life simple there are a few generic docs that get you started and let you know more about the theory behind it:

See also

If this is too generic you can also have a look at two specific examples to setup fully automated Reverse Proxies including autostarting your application on docker-compose up.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Example: add 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 project with multiple subdomains with a customized virtual host config via vhost-gen.

Table of Contents

Simple sub domains for one project ¶

When you just want to serve your project under different sub domains, 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	`local`	`http://my-test.local`
www.my-test	`local`	`http://www.my-test.local`
t2.www.my-test	`local`	`http://t2.www.my-test.local`

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

Important

The project directories must be real directories and not symlinks! See example below for how to set it up.

Example ¶

Prerequisite ¶

Let’s assume the following settings.

Variable	Value
TLD_SUFFIX	`loc`
HTTPD_HTTP2_ENABLE	`htdocs`
Project name / directory	`my-test`
Sub domain 1 / directory	`api.my-test`
Sub domain 2 / directory	`www.my-test`

Project which holds the data is my-test
Web root of my-test is in my-test/FRAMEWORK/public
Same project should be available under api.my-test and www.my-test

Directory structure ¶

host> tree -L 2
.
├── my-test
│   ├── FRAMEWORK
│   └── htdocs -> FRAMEWORK/public
├── api.my-test
│   └── htdocs -> ../my-test/FRAMEWORK/public
└── www.my-test
    └── htdocs -> ../my-test/FRAMEWORK/public

my-test, api.my-test and www.my-test must be normal directories (not symlinks).
The framework data resided in my-test.
Each projects htdocs directory is a symlink pointing to the web root of the framework in my-test

With this structure you will have three domains available pointing to the same project:

Complex sub domains for one project ¶

When you want to have more complex 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

Virtual host templates: Ensure you have read and understand how to customize virtual hosts globally with vhost-gen.
Customize all virtual hosts globally: Ensure you have read and understand how to customize virtual hosts globally with vhost-gen.
Customize specific virtual host: 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 cfg/vhost-gen/*.yml ./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 a``ServerAlias`` directive:

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

vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName   __VHOST_NAME__
      ServerAlias  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: Setup 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 a ServerAlias directive which does catch-all:

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

vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName   __VHOST_NAME__
      ServerAlias  *.__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: Setup 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 cfg/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

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Reverse Proxy with HTTPS¶

Imagine you have started an application within the PHP container that creates a listening port (e.g.: NodeJS). This will now only listen on the PHP container and you would have to adjust the docker-compose.yml definition in order to have that port available outside to your host OS.

Alternatively, there is a simple way to reverse proxy it to the already running web server and even make use of the available HTTPS feature.

See also

Read more about how to autostart applications:

Custom scripts per PHP version (individually for different PHP versions)
Custom scripts globally (equal for all PHP versions)

Table of Contents

Walkthrough

Walkthrough ¶

Assumption ¶

Let’s imagine you have started an application in the PHP container with the following settings:

TLD_SUFFIX: loc
Project directory inside PHP container: /shared/httpd/my-app
HOST_PATH_HTTPD_DATADIR on the host: ./data/www
HTTPD_TEMPLATE_DIR: .devilbox
Listening port: 8081
Listening host: php (any of the PHP container)
Resulting vhost name: my-app.loc

Copy vhost-gen templates ¶

The reverse vhost-gen templates are available in cfg/vhost-gen:

host> tree -L 1 cfg/vhost-gen/

cfg/vhost-gen/
├── apache22.yml-example-rproxy
├── apache22.yml-example-vhost
├── apache24.yml-example-rproxy
├── apache24.yml-example-vhost
├── nginx.yml-example-rproxy
├── nginx.yml-example-vhost
└── README.md

0 directories, 7 files

For this example we will copy all *-example-rproxy files into /shared/httpd/my-app/.devilbox to ensure this will work with all web servers.

host> cd /path/to/devilbox
host> cp cfg/vhost-gen/apache22.yml-example-rproxy data/www/my-app/.devilbox/apache22.yml
host> cp cfg/vhost-gen/apache24.yml-example-rproxy data/www/my-app/.devilbox/apache24.yml
host> cp cfg/vhost-gen/nginx.yml-example-rproxy data/www/my-app/.devilbox/nginx.yml

Adjust port ¶

By default, all vhost-gen templates will forward requests to port 8000 into the PHP container. Our current example however uses port 8081, so we must change that accordingly for all three templates.

Adjust Apache 2.2 template ¶

Open the apache22.yml vhost-gen template in your project:

host> cd /path/to/devilbox
host> vi data/www/my-app/.devilbox/apache22.yml

Find the two lines with ProxyPass and ProxyPassReverse and change the port from 8000 to 8081

data/www/my-app/.devilbox/apache22.yml¶

# ... more lines above ... #

###
### Basic vHost skeleton
###
vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName   __VHOST_NAME__

      CustomLog  "__ACCESS_LOG__" combined
      ErrorLog   "__ERROR_LOG__"

      # Reverse Proxy definition (Ensure to adjust the port, currently '8000')
      ProxyRequests On
      ProxyPreserveHost On
      ProxyPass / http://php:8081/
      ProxyPassReverse / http://php:8081/

# ... more lines below ... #

Adjust Apache 2.4 template ¶

Open the apache24.yml vhost-gen template in your project:

host> cd /path/to/devilbox
host> vi data/www/my-app/.devilbox/apache24.yml

Find the two lines with ProxyPass and ProxyPassReverse and change the port from 8000 to 8081

data/www/my-app/.devilbox/apache24.yml¶

# ... more lines above ... #

###
### Basic vHost skeleton
###
vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName   __VHOST_NAME__

      CustomLog  "__ACCESS_LOG__" combined
      ErrorLog   "__ERROR_LOG__"

      # Reverse Proxy definition (Ensure to adjust the port, currently '8000')
      ProxyRequests On
      ProxyPreserveHost On
      ProxyPass / http://php:8081/
      ProxyPassReverse / http://php:8081/

# ... more lines below ... #

Adjust Nginx template ¶

Open the nginx.yml vhost-gen template in your project:

host> cd /path/to/devilbox
host> vi data/www/my-app/.devilbox/nginx.yml

Find the lines with proxy_pass and change the port from 8000 to 8081

data/www/my-app/.devilbox/nginx.yml¶

# ... more lines above ... #

###
### Basic vHost skeleton
###
vhost: |
  server {
      listen       __PORT____DEFAULT_VHOST__;
      server_name  __VHOST_NAME__;

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

      # Reverse Proxy definition (Ensure to adjust the port, currently '8000')
      location / {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_pass http://php:8081;
      }

# ... more lines below ... #

Restart the Devilbox ¶

Now for the changes to take affect, simply restart the Devilbox (or start if not yet running):

host> cd /path/to/devilbox

# Stop the Devilbox
host> docker-compose stop
host> docker-compose rm -f

# Start the Devilbox (PHP and HTTPD container only)
host> docker-compose up -d php httpd bind

Start your application ¶

Enter the PHP container and start your application which creates the listening port in port 8081.

See also

This can also be automated to happen automatically during docker-compose up via:

Custom scripts per PHP version (individually for different PHP versions)
Custom scripts globally (equal for all PHP versions)
Example: Autostarting NodeJS Apps

Visit your project ¶

That’s it, your service application will now be available via:

http://my-app.loc

It will also be available on HTTPS. This is by default and automatically:

https://my-app.loc

See also

Add your own Docker image

And is even shown as a project in the Devilbox intranet:

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Reverse Proxy for custom Docker¶

Imagine you have added a custom service container to the Devilbox which has a project that is available via http on a very specific port in that container.

You do not want to expose this port to the host system, but rather want to make it available via the bundled web server and also be able to see it on the Devilbox intranet vhost section.

Additionally you want the project to make use of the same DNS naming scheme and also have HTTPS for it.

You can easily achieve this by setting up a reverse proxy for it.

See also

Table of Contents

Walkthrough

Walkthrough ¶

Assumption ¶

Let’s imagine you have added a custom Python Docker image to the Devilbox which starts up a Django application listening on port 3000.

TLD_SUFFIX: loc
Desired DNS name: my-python.loc
HOST_PATH_HTTPD_DATADIR on the host: ./data/www
HTTPD_TEMPLATE_DIR: .devilbox
Listening port: 3000
Listening host: python (hostname of the Python container)

Create virtual directory ¶

In order to create a reverse proxy for that custom container, you must add a virtual project directory without any data in it. This directory is purely for the purpose of determining the DNS name and for having the vhost-gen configuration in.

Navigate to the HOST_PATH_HTTPD_DATADIR directory and create your project

host> cd /path/to/devilbox
host> cd /path/to/devilbox/data/www

# Create the project directory
host> mkdir my-python

# Create the htdocs directory (to have a valid project for the Intranet page)
host> mkdir my-python/htdocs


# Create the vhost-gen directory (to be apply to apply custom templates)
host> mkdir my-python/.devilbox

This part is now sufficient to have the project visible on the Devilbox intranet.

Copy vhost-gen templates ¶

The reverse vhost-gen templates are available in cfg/vhost-gen:

host> tree -L 1 cfg/vhost-gen/

cfg/vhost-gen/
├── apache22.yml-example-rproxy
├── apache22.yml-example-vhost
├── apache24.yml-example-rproxy
├── apache24.yml-example-vhost
├── nginx.yml-example-rproxy
├── nginx.yml-example-vhost
└── README.md

0 directories, 7 files

For this example we will copy all *-example-rproxy files into /shared/httpd/my-python/.devilbox to ensure this will work with all web servers.

host> cd /path/to/devilbox
host> cp cfg/vhost-gen/apache22.yml-example-rproxy data/www/my-python/.devilbox/apache22.yml
host> cp cfg/vhost-gen/apache24.yml-example-rproxy data/www/my-python/.devilbox/apache24.yml
host> cp cfg/vhost-gen/nginx.yml-example-rproxy data/www/my-python/.devilbox/nginx.yml

Adjust port ¶

By default, all vhost-gen templates will forward requests to port 8000 into the PHP container. Our current example however uses port 3000 and host python, so we must change that accordingly for all three templates.

Adjust Apache 2.2 template ¶

Open the apache22.yml vhost-gen template in your project:

host> cd /path/to/devilbox
host> vi data/www/my-python/.devilbox/apache22.yml

Find the two lines with ProxyPass and ProxyPassReverse and change the port from 8000 to 3000 and host php to python:

data/www/my-python/.devilbox/apache22.yml¶

# ... more lines above ... #

###
### Basic vHost skeleton
###
vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName   __VHOST_NAME__

      CustomLog  "__ACCESS_LOG__" combined
      ErrorLog   "__ERROR_LOG__"

      # Reverse Proxy definition (Ensure to adjust the port, currently '8000')
      ProxyRequests On
      ProxyPreserveHost On
      ProxyPass / http://python:3000/
      ProxyPassReverse / http://python:3000/

# ... more lines below ... #

Adjust Apache 2.4 template ¶

Open the apache24.yml vhost-gen template in your project:

host> cd /path/to/devilbox
host> vi data/www/my-python/.devilbox/apache24.yml

Find the two lines with ProxyPass and ProxyPassReverse and change the port from 8000 to 3000 and host php to python:

data/www/my-python/.devilbox/apache24.yml¶

# ... more lines above ... #

###
### Basic vHost skeleton
###
vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName   __VHOST_NAME__

      CustomLog  "__ACCESS_LOG__" combined
      ErrorLog   "__ERROR_LOG__"

      # Reverse Proxy definition (Ensure to adjust the port, currently '8000')
      ProxyRequests On
      ProxyPreserveHost On
      ProxyPass / http://python:3000/
      ProxyPassReverse / http://python:3000/

# ... more lines below ... #

Adjust Nginx template ¶

Open the nginx.yml vhost-gen template in your project:

host> cd /path/to/devilbox
host> vi data/www/my-python/.devilbox/nginx.yml

Find the line with proxy_pass and change the port from 8000 to 3000 and host php to python:

data/www/my-python/.devilbox/nginx.yml¶

# ... more lines above ... #

###
### Basic vHost skeleton
###
vhost: |
  server {
      listen       __PORT____DEFAULT_VHOST__;
      server_name  __VHOST_NAME__;

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

      # Reverse Proxy definition (Ensure to adjust the port, currently '8000')
      location / {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_pass http://python:3000;
      }

# ... more lines below ... #

Restart the Devilbox ¶

Now for the changes to take affect, simply restart the Devilbox (or start if not yet running):

host> cd /path/to/devilbox

# Stop the Devilbox
host> docker-compose stop
host> docker-compose rm -f

# Start the Devilbox (Your Python container and the PHP and HTTPD container only)
host> docker-compose up -d php httpd bind python

Visit your project ¶

That’s it, your service application will now be available via:

http://my-python.loc

It will also be available on HTTPS. This is by default and automatically:

https://my-python.loc

See also

And is even shown as a project in the Devilbox intranet:

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Enable all additional container¶

Besides providing basic LAMP/MEAN stack container, which are well integrated into the Devilbox intranet, the Devilbox also ships additional pre-configured container that can easily be enabled.

Table of Contents

Available additional container
Enable all additional container
Configure additional container

Available additional container ¶

The following table shows you the currently additional available container:

Container	Name	Hostname	IP Address
PHP Community	php	php	172.16.238.10
Blackfire	blackfire	blackfire	172.16.238.200
MailHog	mailhog	mailhog	172.16.238.201
Ngrok	ngrok	ngrok	172.16.238.202
RabbitMQ	rabbit	rabbit	172.16.238.210
Solr	solr	solr	172.16.238.220
Varnish	varnish	varnish	172.16.238.230
HAProxy (SSL offloader for Varnish)	haproxy	haproxy	172.16.238.231
ELK: Elastic Search	elastic	elastic	172.16.238.240
ELK: Logstash	logstash	logstash	172.16.238.241
ELK: Kibana	kibana	kibana	172.16.238.242
Python Flask	flask1	flask1	172.16.238.250

Enable all additional container ¶

Copy docker-compose.override.yml-all into the root of the Devilbox git directory.

host> cp compose/docker-compose.override.yml-all docker-compose.override.yml

That’s it, if you docker-compose up, all container will be started. This however is not adviced as it will eat up a lot of resources. You are better off by selectively specifying the container you want to run.

See also

Configure additional container ¶

The additional container also provide many configuration options just as the default ones do. That includes, but is not limited to:

Image version
Exposed ports
Mount points
And various container specific settings

In order to fully customize each container, refer to their own documentation section:

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Enable and configure PHP Community¶

This section will guide you through getting PHP community images integrated into the Devilbox.

See also

Table of Contents

Overview
Instructions
TL;DR

Overview ¶

Available overwrites ¶

The Devilbox ships various example configurations to overwrite the default stack. Those files are located under compose/ in the Devilbox git directory.

docker-compose.override.yml-all has all examples combined in one file for easy copy/paste. However, each example also exists in its standalone file as shown below:

host> tree -L 1 compose/
compose/
├── docker-compose.override.yml-all
├── docker-compose.override.yml-blackfire
├── docker-compose.override.yml-elk
├── docker-compose.override.yml-mailhog
├── docker-compose.override.yml-meilisearch
├── docker-compose.override.yml-ngrok
├── docker-compose.override.yml-php-community
├── docker-compose.override.yml-python-flask
├── docker-compose.override.yml-rabbitmq
├── docker-compose.override.yml-solr
├── docker-compose.override.yml-varnish
└── README.md

0 directories, 10 files

See also

PHP-FPM Community settings ¶

In case of PHP-FPM Community, the file is compose/docker-compose.override.yml-php-community. This file must be copied into the root of the Devilbox git directory.

What	How and where
Example compose file	`compose/docker-compose.override.yml-all` or `compose/docker-compose.override.yml-php-community`
Container IP address	`172.16.238.10`
Container host name	`php`
Container name	`php`
Mount points	Same as default php image
Exposed port	Same as default php image
Available at	n.a.
Further configuration	`PHP_COMMUNITY_FLAVOUR` must be set via `.env`

PHP Community env variables ¶

Additionally the following .env variables can be created for easy configuration:

Variable	Default value	Description
`PHP_COMMUNITY_FLAVOUR`	`devilbox`	Controls the PHP Community flavour.

Instructions ¶

1. Copy docker-compose.override.yml ¶

Copy the PHP-FPM Community Docker Compose overwrite file into the root of the Devilbox git directory. (It must be at the same level as the default docker-compose.yml file).

host> cp compose/docker-compose.override.yml-php-community docker-compose.override.yml

See also

2. Adjust `env` settings ¶

By default PHP-FPM Community is using the Devilbox reference flavour devilbox. You can change this flavour via the .env variable PHP_COMMUNITY_FLAVOUR.

.env¶

PHP_COMMUNITY_FLAVOUR=devilbox

See also

3. Start the Devilbox ¶

The final step is to start the Devilbox with the newly added PHP-FPM Community images.

Let’s assume you want to start php, httpd, and bind.

host> docker-compose up -d php httpd bind

See also

TL;DR ¶

For the lazy readers, here are all commands required to get you started. Simply copy and paste the following block into your terminal from the root of your Devilbox git directory:

# Copy compose-override.yml into place
cp compose/docker-compose.override.yml-php-community docker-compose.override.yml

# Set Community flavour
echo "PHP_COMMUNITY_FLAVOUR=devilbox" >> .env

# Start container
docker-compose up -d php httpd bind

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Enable and configure Blackfire¶

This section will guide you through getting Blackfire integrated into the Devilbox.

See also

Table of Contents

Overview
Instructions
TL;DR

Overview ¶

Available overwrites ¶

The Devilbox ships various example configurations to overwrite the default stack. Those files are located under compose/ in the Devilbox git directory.

docker-compose.override.yml-all has all examples combined in one file for easy copy/paste. However, each example also exists in its standalone file as shown below:

host> tree -L 1 compose/
compose/
├── docker-compose.override.yml-all
├── docker-compose.override.yml-blackfire
├── docker-compose.override.yml-elk
├── docker-compose.override.yml-mailhog
├── docker-compose.override.yml-meilisearch
├── docker-compose.override.yml-ngrok
├── docker-compose.override.yml-php-community
├── docker-compose.override.yml-python-flask
├── docker-compose.override.yml-rabbitmq
├── docker-compose.override.yml-solr
├── docker-compose.override.yml-varnish
└── README.md

0 directories, 10 files

See also

Blackfire settings ¶

In case of Blackfire, the file is compose/docker-compose.override.yml-blackfire. This file must be copied into the root of the Devilbox git directory.

What	How and where
Example compose file	`compose/docker-compose.override.yml-all` or `compose/docker-compose.override.yml-blackfire`
Container IP address	`172.16.238.200`
Container host name	`blackfire`
Container name	`blackfire`
Mount points	none
Exposed port	none
Available at	n.a.
Further configuration	`BLACKFIRE_SERVER_ID` and `BLACKFIRE_SERVER_TOKEN` must be set via `.env`

Blackfire env variables ¶

Additionally the following .env variables can be created for easy configuration:

Variable	Default value	Description
`BLACKFIRE_SERVER`	`latest`	Controls the Blackfire version to use.
`BLACKFIRE_SERVER_ID`	`id`	A valid server id is required in order to start `blackfire-agent`.
`BLACKFIRE_SERVER_TOKEN`	`token`	A valid server token is required in order to start `blackfire-agent`.
`BLACKFIRE_CLIENT_ID`	`id`	A valid client id is required in order to use `blackfire` cli.
`BLACKFIRE_CLIENT_TOKEN`	`token`	A valid client token is required in order to use `blackfire` cli.

Instructions ¶

1. Copy docker-compose.override.yml ¶

Copy the Blackfire Docker Compose overwrite file into the root of the Devilbox git directory. (It must be at the same level as the default docker-compose.yml file).

host> cp compose/docker-compose.override.yml-blackfire docker-compose.override.yml

See also

2. Adjust `env` settings ¶

By default Blackfire is using some dummy values for BLACKFIRE_SERVER_ID and BLACKFIRE_SERVER_TOKEN. You must however aquire valid values and set the in your .env file in order for Blackfire to properly start. Those values can be obtained at their official webpage.

.env¶

BLACKFIRE_SERVER_ID=<valid server id>
BLACKFIRE_SERVER_TOKEN=<valid server token>

#BLACKFIRE_SERVER=1.12.0
#BLACKFIRE_SERVER=1.13.0
#BLACKFIRE_SERVER=1.14.0
#BLACKFIRE_SERVER=1.14.1
#BLACKFIRE_SERVER=1.15.0
#BLACKFIRE_SERVER=1.16.0
#BLACKFIRE_SERVER=1.17.0
#BLACKFIRE_SERVER=1.17.1
#BLACKFIRE_SERVER=1.18.0
BLACKFIRE_SERVER=latest

You must also explicitly enable the PHP blackfire module and disable xdebug via .env

.env¶

PHP_MODULES_ENABLE=blackfire
PHP_MODULES_DISABLE=xdebug

See also

3. Copy blackfire php.ini template ¶

In order for the PHP blackfire module to know where the blackfire-agent is listening, we must configure its PHP settings. There is already a default template that you can simply copy.

host> cp cfg/php-ini-7.2/devilbox-php.ini-blackfire cfg/php-ini-7.2/blackfire.ini

See also

The above example shows the procedure for PHP 7.2, if you are using a different version, you must navigate to its corresponding configuration directory.

4. Configure blackfire cli (optional)¶

If you want to use the blackfire cli from within the PHP container, its configuration must be configured. There is already a startup template which does it for you.

You first need to add the Blackfire client id and token to .env:

.env¶

BLACKFIRE_CLIENT_ID=<valid client id>
BLACKFIRE_CLIENT_TOKEN=<valid client token>

Then all that’s left to do is to copy the startup script which configures the blackfire cli for you.

host> cp autostart/configure-blackfire-cli.sh-example autostart/configure-blackfire-cli.sh

See also

Custom scripts globally

5. Start the Devilbox ¶

The final step is to start the Devilbox with Blackfire.

Let’s assume you want to start php, httpd, bind and blackfire.

host> docker-compose up -d php httpd bind blackfire

See also

TL;DR ¶

For the lazy readers, here are all commands required to get you started. Simply copy and paste the following block into your terminal from the root of your Devilbox git directory:

# Copy compose-override.yml into place
cp compose/docker-compose.override.yml-blackfire docker-compose.override.yml

# Copy php.ini into place
cp cfg/php-ini-7.2/devilbox-php.ini-blackfire cfg/php-ini-7.2/blackfire.ini

# Set Blackfire server id and token
echo "BLACKFIRE_SERVER_ID=<valid server id>"       >> .env
echo "BLACKFIRE_SERVER_TOKEN=<valid server token>" >> .env

# Set Blackfire client id and token
echo "BLACKFIRE_CLIENT_ID=<valid client id>"       >> .env
echo "BLACKFIRE_CLIENT_TOKEN=<valid client token>" >> .env

echo "#BLACKFIRE_SERVER=1.12.0"                    >> .env
echo "#BLACKFIRE_SERVER=1.13.0"                    >> .env
echo "#BLACKFIRE_SERVER=1.14.0"                    >> .env
echo "#BLACKFIRE_SERVER=1.14.1"                    >> .env
echo "#BLACKFIRE_SERVER=1.15.0"                    >> .env
echo "#BLACKFIRE_SERVER=1.16.0"                    >> .env
echo "#BLACKFIRE_SERVER=1.17.0"                    >> .env
echo "#BLACKFIRE_SERVER=1.17.1"                    >> .env
echo "#BLACKFIRE_SERVER=1.18.0"                    >> .env
echo "BLACKFIRE_SERVER=latest"                     >> .env

# Ensure blackfire is enabled and xdebug is disabled
# IMPORTANT: This replacement is only an example and will overwrite
#            all other enabled/disabled modules.
#            Do not do it this way.
sed -i'' 's/^PHP_MODULES_ENABLE=.*/PHP_MODULES_ENABLE=blackfire/g' .env
sed -i'' 's/^PHP_MODULES_DISABLE=.*/PHP_MODULES_ENABLE=xdebug/g' .env

# Start container
docker-compose up -d php httpd bind blackfire

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Enable and configure ELK Stack¶

This section will guide you through getting ELK stack (Elastic Search, Logstash and Kibana) integrated into the Devilbox.

See also

Table of Contents

Overview
Instructions
TL;DR

Overview ¶

Available overwrites ¶

The Devilbox ships various example configurations to overwrite the default stack. Those files are located under compose/ in the Devilbox git directory.

docker-compose.override.yml-all has all examples combined in one file for easy copy/paste. However, each example also exists in its standalone file as shown below:

host> tree -L 1 compose/
compose/
├── docker-compose.override.yml-all
├── docker-compose.override.yml-blackfire
├── docker-compose.override.yml-elk
├── docker-compose.override.yml-mailhog
├── docker-compose.override.yml-meilisearch
├── docker-compose.override.yml-ngrok
├── docker-compose.override.yml-php-community
├── docker-compose.override.yml-python-flask
├── docker-compose.override.yml-rabbitmq
├── docker-compose.override.yml-solr
├── docker-compose.override.yml-varnish
└── README.md

0 directories, 10 files

See also

ELK settings ¶

In case of ELK stack, the file is compose/docker-compose.override.yml-elk. This file must be copied into the root of the Devilbox git directory.

What	How and where
Example compose file	`compose/docker-compose.override.yml-all` or `compose/docker-compose.override.yml-elk`

Elastic Search ¶

What	How and where
Container IP address	`172.16.238.240`
Container host name	`elastic`
Container name	`elastic`
Mount points	none
Exposed port	`9200` (can be changed via `.env`)
Available at	`http://localhost:9200`
Further configuration	`.env` vars

Logstash ¶

What	How and where
Container IP address	`172.16.238.241`
Container host name	`logstash`
Container name	`logstash`
Mount points	none
Exposed port	`9600` (can be changed via `.env`)
Available at	`tcp://localhost:9600`
Further configuration	`.env` vars

kibana ¶

What	How and where
Container IP address	`172.16.238.242`
Container host name	`kibana`
Container name	`kibana`
Mount points	none
Exposed port	`9600` (can be changed via `.env`)
Available at	`tcp://localhost:9600`
Further configuration	`.env` vars

ELK env variables ¶

Additionally the following .env variables can be created for easy configuration:

Elastic Search ¶

Variable	Default value	Description
`HOST_PORT_ELK_ELASTIC`	`9200`	Controls the host port on which Elastic Search will be available at.
`ELK_SERVER`	`6.6.1`	Controls the ELK stack version to use.
`TIMEZONE`	`UTC`	Timezone for Elastic Search (already available in `.env`).

Logstash ¶

Variable	Default value	Description
`HOST_PORT_ELK_LOGSTASH`	`9600`	Controls the host port on which Logstash will be available at.
`ELK_SERVER`	`6.6.1`	Controls the ELK stack version to use.
`TIMEZONE`	`UTC`	Timezone for Logstash (already available in `.env`).

Kibana ¶

Variable	Default value	Description
`HOST_PORT_ELK_KIBANA`	`5601`	Controls the host port on which Kibana will be available at.
`ELK_SERVER`	`6.6.1`	Controls the ELK stack version to use.
`TIMEZONE`	`UTC`	Timezone for Kibana (already available in `.env`).

Instructions ¶

1. Copy docker-compose.override.yml ¶

Copy the ELK stack Docker Compose overwrite file into the root of the Devilbox git directory. (It must be at the same level as the default docker-compose.yml file).

host> cp compose/docker-compose.override.yml-elk docker-compose.override.yml

See also

2. Adjust `.env` settings (optional)¶

The ELK stack is using sane defaults, which can be changed by adding variables to the .env file and assigning custom values.

Add the following variables to .env and adjust them to your needs:

.env¶

# ELK stack general
# See here for all versions: https://www.docker.elastic.co/
#ELK_SERVER=6.1.4
#ELK_SERVER=6.2.4
#ELK_SERVER=6.3.2
#ELK_SERVER=6.4.3
#ELK_SERVER=6.5.4
ELK_SERVER=6.6.1

# Elastic Search settings
HOST_PORT_ELK_ELASTIC=9200

# Logstash settings
HOST_PORT_ELK_LOGSTASH=9600

# Kibana settings
HOST_PORT_ELK_KIBANA=5601

See also

3. Start the Devilbox ¶

The final step is to start the Devilbox with ELK stack.

Let’s assume you want to start php, httpd, bind, elastic, logstash, kibana.

host> docker-compose up -d php httpd bind elastic logstash kibana

See also

TL;DR ¶

For the lazy readers, here are all commands required to get you started. Simply copy and paste the following block into your terminal from the root of your Devilbox git directory:

# Copy compose-override.yml into place
cp compose/docker-compose.override.yml-elk docker-compose.override.yml

# Create .env variable
echo "# ELK stack general"               >> .env
echo "# See here for all versions:"      >> .env
echo "# https://www.docker.elastic.co/"  >> .env
echo "#ELK_SERVER=6.1.4"                 >> .env
echo "#ELK_SERVER=6.2.4"                 >> .env
echo "#ELK_SERVER=6.3.2"                 >> .env
echo "#ELK_SERVER=6.4.3"                 >> .env
echo "#ELK_SERVER=6.5.4"                 >> .env
echo "ELK_SERVER=6.6.1"                  >> .env
echo "# Elastic Search settings"         >> .env
echo "HOST_PORT_ELK_ELASTIC=9200"        >> .env
echo "# Logstash settings"               >> .env
echo "HOST_PORT_ELK_LOGSTASH=9600"       >> .env
echo "# Kibana settings"                 >> .env
echo "HOST_PORT_ELK_KIBANA=5601"         >> .env

# Start container
docker-compose up -d php httpd bind elastic logstash kibana

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Enable and configure MailHog¶

This section will guide you through getting MailHog integrated into the Devilbox.

See also

Table of Contents

Overview
Instructions
TL;DR

Overview ¶

Available overwrites ¶

The Devilbox ships various example configurations to overwrite the default stack. Those files are located under compose/ in the Devilbox git directory.

docker-compose.override.yml-all has all examples combined in one file for easy copy/paste. However, each example also exists in its standalone file as shown below:

host> tree -L 1 compose/
compose/
├── docker-compose.override.yml-all
├── docker-compose.override.yml-blackfire
├── docker-compose.override.yml-elk
├── docker-compose.override.yml-mailhog
├── docker-compose.override.yml-meilisearch
├── docker-compose.override.yml-ngrok
├── docker-compose.override.yml-php-community
├── docker-compose.override.yml-python-flask
├── docker-compose.override.yml-rabbitmq
├── docker-compose.override.yml-solr
├── docker-compose.override.yml-varnish
└── README.md

0 directories, 10 files

See also

MailHog settings ¶

In case of MailHog, the file is compose/docker-compose.override.yml-mailhog. This file must be copied into the root of the Devilbox git directory.

What	How and where
Example compose file	`compose/docker-compose.override.yml-all` or `compose/docker-compose.override.yml-mailhog`
Container IP address	`172.16.238.201`
Container host name	`mailhog`
Container name	`mailhog`
Mount points	none
Exposed port	`8025` (can be changed via `.env`)
Available at	`http://localhost:8025`
Further configuration	php.ini settings need to be applied per version

MailHog env variables ¶

Additionally the following .env variables can be created for easy configuration:

Variable	Default value	Description
`HOST_PORT_MAILHOG`	`8025`	Controls the host port on which MailHog will be available at.
`MAILHOG_SERVER`	`latest`	Controls the MailHog version to use.

Instructions ¶

1. Copy docker-compose.override.yml ¶

Copy the MailHog Docker Compose overwrite file into the root of the Devilbox git directory. (It must be at the same level as the default docker-compose.yml file).

host> cp compose/docker-compose.override.yml-mailhog docker-compose.override.yml

See also

2. Adjust PHP settings ¶

The next step is to tell PHP that it should use a different mail forwarder.

Let’s assume you are using PHP 7.2.

# Navigate to the PHP ini configuration directory of your chosen version
host> cd cfg/php-ini-7.2

# Create and open a new *.ini file
host> vi mailhog.ini

Add the following content to the newly created ini file:

mailhog.ini¶

[mail function]
sendmail_path = '/usr/local/bin/mhsendmail --smtp-addr="mailhog:1025"'

See also

php.ini

3. Adjust `.env` settings (optional)¶

By Default MailHog is using the host port 8025, this can be adjusted in the .env file. Add HOST_PORT__MAILHOG to .env and customize its value.

Additionally also the MailHog version can be controlled via MAILHOG_SERVER.

.env¶

HOST_PORT_MAILHOG=8025
MAILHOG_SERVER=latest

See also

4. Start the Devilbox ¶

The final step is to start the Devilbox with MailHog.

Let’s assume you want to start php, httpd, bind and mailhog.

host> docker-compose up -d php httpd bind mailhog

See also

5. Start using it ¶

Once the Devilbox is running, visit http://localhost:8025 in your browser.
Any email send by any of the Devilbox managed projects will then appear in MailHog

TL;DR ¶

For the lazy readers, here are all commands required to get you started. Simply copy and paste the following block into your terminal from the root of your Devilbox git directory:

# Copy compose-override.yml into place
cp compose/docker-compose.override.yml-mailhog docker-compose.override.yml

# Create php.ini
echo "[mail function]" > cfg/php-ini-7.2/mailhog.ini
echo "sendmail_path = '/usr/local/bin/mhsendmail --smtp-addr=\"mailhog:1025\"'" >> cfg/php-ini-7.2/mailhog.ini

# Create .env variable
echo "HOST_PORT_MAILHOG=8025" >> .env
echo "MAILHOG_SERVER=latest" >> .env

# Start container
docker-compose up -d php httpd bind mailhog

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Enable and configure Meilisearch¶

This section will guide you through getting Meilisearch integrated into the Devilbox.

See also

Table of Contents

Overview
Instructions
TL;DR

Overview ¶

Available overwrites ¶

The Devilbox ships various example configurations to overwrite the default stack. Those files are located under compose/ in the Devilbox git directory.

docker-compose.override.yml-all has all examples combined in one file for easy copy/paste. However, each example also exists in its standalone file as shown below:

host> tree -L 1 compose/
compose/
├── docker-compose.override.yml-all
├── docker-compose.override.yml-blackfire
├── docker-compose.override.yml-elk
├── docker-compose.override.yml-mailhog
├── docker-compose.override.yml-meilisearch
├── docker-compose.override.yml-ngrok
├── docker-compose.override.yml-php-community
├── docker-compose.override.yml-python-flask
├── docker-compose.override.yml-rabbitmq
├── docker-compose.override.yml-solr
├── docker-compose.override.yml-varnish
└── README.md

0 directories, 10 files

See also

Meilisearch settings ¶

In case of Meilisearch, the file is compose/docker-compose.override.yml-meilisearch. This file must be copied into the root of the Devilbox git directory.

What	How and where
Example compose file	`compose/docker-compose.override.yml-all` or `compose/docker-compose.override.yml-meilisearch`
Container IP address	`172.16.238.203`
Container host name	`meilisearch`
Container name	`meilisearch`
Mount points	via Docker volumes
Exposed port	`7700` (can be changed via `.env`)
Available at	`http://localhost:7700` (API and Admin WebUI)
Further configuration	none

Meilisearch env variables ¶

Additionally the following .env variables can be created for easy configuration:

Variable	Default value	Description
`HOST_PORT_MEILI`	`7700`	Controls the host port on which Meilisearch API and WebUI will be available at.
`MEILI_SERVER`	`latest`	Controls the Meilisearch version to use.
`MEILI_MASTER_KEY`	none	Default Meilisearch master key.

Instructions ¶

1. Copy docker-compose.override.yml ¶

Copy the Meilisearch Docker Compose overwrite file into the root of the Devilbox git directory. (It must be at the same level as the default docker-compose.yml file).

host> cp compose/docker-compose.override.yml-meilisearch docker-compose.override.yml

See also

2. Adjust `.env` settings (optional)¶

Meilisearch is using sane defaults, which can be changed by adding variables to the .env file and assigning custom values.

Add the following variables to .env and adjust them to your needs:

.env¶

# Meilisearch version to choose
#MEILI_SERVER=v0.26.0
#MEILI_SERVER=v0.27.0
#MEILI_SERVER=v0.28
MEILI_SERVER=latest

MEILI_MASTER_KEY=
HOST_PORT_MEILI=7700

See also

3. Start the Devilbox ¶

The final step is to start the Devilbox with Meilisearch.

Let’s assume you want to start php, httpd, bind, meilisearch.

host> docker-compose up -d php httpd bind meilisearch

See also

TL;DR ¶

For the lazy readers, here are all commands required to get you started. Simply copy and paste the following block into your terminal from the root of your Devilbox git directory:

# Copy compose-override.yml into place
cp compose/docker-compose.override.yml-meilisearch docker-compose.override.yml

# Create .env variable
echo "# Meilisearch version to choose"   >> .env
echo "#MEILI_SERVER=v0.26.0"             >> .env
echo "#MEILI_SERVER=v0.27.0"             >> .env
echo "#MEILI_SERVER=v0.28"               >> .env
echo "MEILI_SERVER=latest"               >> .env
echo "MEILI_MASTER_KEY="                 >> .env
echo "HOST_PORT_MEILI=7700"              >> .env

# Start container
docker-compose up -d php httpd bind meilisearch

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Enable and configure Ngrok¶

This section will guide you through getting Ngrok integrated into the Devilbox.

See also

Table of Contents

Overview
Instructions
TL;DR

Overview ¶

Available overwrites ¶

The Devilbox ships various example configurations to overwrite the default stack. Those files are located under compose/ in the Devilbox git directory.

docker-compose.override.yml-all has all examples combined in one file for easy copy/paste. However, each example also exists in its standalone file as shown below:

host> tree -L 1 compose/
compose/
├── docker-compose.override.yml-all
├── docker-compose.override.yml-blackfire
├── docker-compose.override.yml-elk
├── docker-compose.override.yml-mailhog
├── docker-compose.override.yml-meilisearch
├── docker-compose.override.yml-ngrok
├── docker-compose.override.yml-php-community
├── docker-compose.override.yml-python-flask
├── docker-compose.override.yml-rabbitmq
├── docker-compose.override.yml-solr
├── docker-compose.override.yml-varnish
└── README.md

0 directories, 10 files

See also

Ngrok settings ¶

In case of Ngrok, the file is compose/docker-compose.override.yml-ngrok. This file must be copied into the root of the Devilbox git directory.

What	How and where
Example compose file	`compose/docker-compose.override.yml-all` or `compose/docker-compose.override.yml-ngrok`
Container IP address	`172.16.238.202`
Container host name	`ngrok`
Container name	`ngrok`
Mount points	none
Exposed port	`4040` (can be changed via `.env`)
Available at	`http://localhost:4040`
Further configuration	`NGROK_HTTP_TUNNELS`, `NGROK_AUTHTOKEN` and `NGROK_REGION`

Ngrok env variables ¶

Additionally the following .env variables can be created for easy configuration:

Variable	Default value	Description
`HOST_PORT_NGROK`	`4040`	Controls the host port on which Ngrok admin UI will be available at.
`NGROK_HTTP_TUNNELS`	`httpd:httpd:80`	Defines one or more Ngrok tunnels (depending on your license)
`NGROK_AUTHTOKEN`	empty	Free or paid license token for Ngrok (can also be empty)
`NGROK_REGION`	`us`	Choose the region where the ngrok client will connect to host its tunnels.

NGROK_HTTP_TUNNELS ¶

Ngrok tunnel definitions can be in the form of:

<domain.tld>:<addr>:<port>
<domain1.tld>:<addr>:<port>,<domain2.tld>:<addr>:<port>

Note

If you don’t use a license you can only specify a single tunnel. If your license is pro enough, you can have multiple comma separated tunnels.

<domain.tld> is the virtual hostname that you want to serve via Ngrok
<addr> is the hostname or IP address of the web server
<port> is the port on which the web server is reachable via HTTP

# Make vhost "project1.loc" which runs on localhost:8080 available
HTTP_TUNNELS=project1.loc:localhost:8080

# Make two vhosts available which run on host apache:80
HTTP_TUNNELS=project1.loc:apache:80,project2.loc:apache:80

# Make two vhosts from two different web server addresses available
HTTP_TUNNELS=project1.loc:localhost:8080,project2.loc:apache:80

Instructions ¶

1. Copy docker-compose.override.yml ¶

Copy the Ngrok Docker Compose overwrite file into the root of the Devilbox git directory. (It must be at the same level as the default docker-compose.yml file).

host> cp compose/docker-compose.override.yml-ngrok docker-compose.override.yml

See also

2. Adjust `.env` settings (optional)¶

By Default Ngrok will forward the httpd domain, which is represents the default virtual host (the Devilbox intranet) to your web server (also named httpd) and makes the admin UI available on port 4040 on your local machine.

You can of course change the domain as well as where to forward it to (e.g.: to Varnish or HAProxy instead).

Additionally you can also specify a license token in order to allow for more tunnels via NGROK_AUTHTOKEN.

.env¶

HOST_PORT_NGROK=4040
# Share project1.loca over the internet
NGROK_HTTP_TUNNELS=project1.loc:httpd:80
# No license token specified
NGROK_AUTHTOKEN=

See also

3. Start the Devilbox ¶

The final step is to start the Devilbox with Ngrok.

Let’s assume you want to start php, httpd, bind and ngrok.

host> docker-compose up -d php httpd bind ngrok

See also

4. Start using it ¶

Once the Devilbox is running, visit http://localhost:4040 in your browser.
Get URL for public available project

TL;DR ¶

For the lazy readers, here are all commands required to get you started. Simply copy and paste the following block into your terminal from the root of your Devilbox git directory:

# Copy compose-override.yml into place
cp compose/docker-compose.override.yml-ngrok docker-compose.override.yml

# Create .env variable
echo "HOST_PORT_NGROK=4040"                      >> .env
echo "# Share project1.loca over the internet"   >> .env
echo "NGROK_HTTP_TUNNELS=project1.loc:httpd:80"  >> .env
echo "# No license token specified"              >> .env
echo "NGROK_AUTHTOKEN="                          >> .env
echo "NGROK_REGION=us"                           >> .env

# Start container
docker-compose up -d php httpd bind ngrok

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Enable and configure Python Flask¶

This section will guide you through getting Python Flask integrated into the Devilbox.

See also

Table of Contents

Overview
Instructions
TL;DR

Overview ¶

Available overwrites ¶

The Devilbox ships various example configurations to overwrite the default stack. Those files are located under compose/ in the Devilbox git directory.

docker-compose.override.yml-all has all examples combined in one file for easy copy/paste. However, each example also exists in its standalone file as shown below:

host> tree -L 1 compose/
compose/
├── docker-compose.override.yml-all
├── docker-compose.override.yml-blackfire
├── docker-compose.override.yml-elk
├── docker-compose.override.yml-mailhog
├── docker-compose.override.yml-meilisearch
├── docker-compose.override.yml-ngrok
├── docker-compose.override.yml-php-community
├── docker-compose.override.yml-python-flask
├── docker-compose.override.yml-rabbitmq
├── docker-compose.override.yml-solr
├── docker-compose.override.yml-varnish
└── README.md

0 directories, 10 files

See also

Python Flask settings ¶

In case of Python Flask, the file is compose/docker-compose.override.yml-python-flask. This file must be copied into the root of the Devilbox git directory.

What	How and where
Example compose file	`compose/docker-compose.override.yml-all` or `compose/docker-compose.override.yml-python-flask`
Container IP address	`172.16.238.250`
Container host name	`flask1`
Container name	`flask1`
Mount points	data/www`
Exposed port	none
Available at	Devilbox intranet via Reverse Proxy configuration
Further configuration	Setup reverse proxy Python Flask

Python Flask env variables ¶

Additionally the following .env variables can be created for easy configuration:

Variable	Default value	Description
`FLASK_PROJECT`	none	Specifies your Python Flask project dir in data/www.
`PYTHON_VERSION`	`3.8`	Specifies the Python version to use for Flask.

Instructions ¶

1. Copy docker-compose.override.yml ¶

Copy the Python Flask Docker Compose overwrite file into the root of the Devilbox git directory. (It must be at the same level as the default docker-compose.yml file).

host> cp compose/docker-compose.override.yml-python-flask docker-compose.override.yml

See also

2. Adjust `.env` settings (optional)¶

Python Flask is using sane defaults, which can be changed by adding variables to the .env file and assigning custom values.

Add the following variables to .env and adjust them to your needs:

.env¶

# Project directory in data/www
FLASK_PROJECT=my-flask

# Python version to choose
#PYTHON_VERSION=2.7
#PYTHON_VERSION=3.5
#PYTHON_VERSION=3.6
#PYTHON_VERSION=3.7
PYTHON_VERSION=3.8

See also

Setup reverse proxy Python Flask

3. Configure Reverse Proxy ¶

Before starting up the devilbox you will need to configure your python flask project and the reverse proxy settings.

See also

TL;DR ¶

For the lazy readers, here are all commands required to get you started. Simply copy and paste the following block into your terminal from the root of your Devilbox git directory:

# Copy compose-override.yml into place
cp compose/docker-compose.override.yml-flask1 docker-compose.override.yml

# Create .env variable
echo "# Project directory in data/www"   > .env
echo "FLASK_PROJECT=my-flask"           >> .env
echo "# Python version to choose"       >> .env
echo "#PYTHON_VERSION=2.7"              >> .env
echo "#PYTHON_VERSION=3.5"              >> .env
echo "#PYTHON_VERSION=3.6"              >> .env
echo "#PYTHON_VERSION=3.7"              >> .env
echo "PYTHON_VERSION=3.8"               >> .env

before starting up the devilbox you will need to configure your python flask project and the reverse proxy settings.

See also

Setup reverse proxy Python Flask

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Enable and configure RabbitMQ¶

This section will guide you through getting RabbitMQ integrated into the Devilbox.

See also

Table of Contents

Overview
Instructions
TL;DR

Overview ¶

Available overwrites ¶

The Devilbox ships various example configurations to overwrite the default stack. Those files are located under compose/ in the Devilbox git directory.

docker-compose.override.yml-all has all examples combined in one file for easy copy/paste. However, each example also exists in its standalone file as shown below:

host> tree -L 1 compose/
compose/
├── docker-compose.override.yml-all
├── docker-compose.override.yml-blackfire
├── docker-compose.override.yml-elk
├── docker-compose.override.yml-mailhog
├── docker-compose.override.yml-meilisearch
├── docker-compose.override.yml-ngrok
├── docker-compose.override.yml-php-community
├── docker-compose.override.yml-python-flask
├── docker-compose.override.yml-rabbitmq
├── docker-compose.override.yml-solr
├── docker-compose.override.yml-varnish
└── README.md

0 directories, 10 files

See also

RabbitMQ settings ¶

In case of RabbitMQ, the file is compose/docker-compose.override.yml-rabbitmq. This file must be copied into the root of the Devilbox git directory.

What	How and where
Example compose file	`compose/docker-compose.override.yml-all` or `compose/docker-compose.override.yml-rabbitmq`
Container IP address	`172.16.238.210`
Container host name	`rabbit`
Container name	`rabbit`
Mount points	via Docker volumes
Exposed port	`5672` and `15672` (can be changed via `.env`)
Available at	`http://localhost:15672` (Admin WebUI)
Further configuration	none

RabbitMQ env variables ¶

Additionally the following .env variables can be created for easy configuration:

Variable	Default value	Description
`HOST_PORT_RABBIT`	`5672`	Controls the host port on which RabbitMQ API will be available at.
`HOST_PORT_RABBIT_MGMT`	`15672`	Controls the host port on which RabbitMQ Admin WebUI will be available at.
`RABBIT_SERVER`	`management`	Controls the RabbitMQ version to use.
`RABBIT_DEFAULT_VHOST`	`my_vhost`	Default RabbitMQ vhost name. (not a webserver vhost name)
`RABBIT_DEFAULT_USER`	`guest`	Default username for Admin WebUI.
`RABBIT_DEFAULT_PASS`	`guest`	Default password for Admin WebUI.

Instructions ¶

1. Copy docker-compose.override.yml ¶

Copy the RabbitMQ Docker Compose overwrite file into the root of the Devilbox git directory. (It must be at the same level as the default docker-compose.yml file).

host> cp compose/docker-compose.override.yml-rabbitmq docker-compose.override.yml

See also

2. Adjust `.env` settings (optional)¶

RabbitMQ is using sane defaults, which can be changed by adding variables to the .env file and assigning custom values.

Add the following variables to .env and adjust them to your needs:

.env¶

# RabbitMQ version to choose
#RABBIT_SERVER=3.6
#RABBIT_SERVER=3.6-management
#RABBIT_SERVER=3.7
#RABBIT_SERVER=3.7-management
#RABBIT_SERVER=latest
RABBIT_SERVER=management

RABBIT_DEFAULT_VHOST=my_vhost
RABBIT_DEFAULT_USER=guest
RABBIT_DEFAULT_PASS=guest

HOST_PORT_RABBIT=5672
HOST_PORT_RABBIT_MGMT=15672

See also

3. Start the Devilbox ¶

The final step is to start the Devilbox with RabbitMQ.

Let’s assume you want to start php, httpd, bind, rabbit.

host> docker-compose up -d php httpd bind rabbit

See also

TL;DR ¶

For the lazy readers, here are all commands required to get you started. Simply copy and paste the following block into your terminal from the root of your Devilbox git directory:

# Copy compose-override.yml into place
cp compose/docker-compose.override.yml-rabbitmq docker-compose.override.yml

# Create .env variable
echo "# RabbitMQ version to choose"           >> .env
echo "#RABBIT_SERVER=3.6"                     >> .env
echo "#RABBIT_SERVER=3.6-management"          >> .env
echo "#RABBIT_SERVER=3.7"                     >> .env
echo "#RABBIT_SERVER=3.7-management"          >> .env
echo "#RABBIT_SERVER=latest"                  >> .env
echo "RABBIT_SERVER=management"               >> .env
echo "RABBIT_DEFAULT_VHOST=my_vhost"          >> .env
echo "RABBIT_DEFAULT_USER=guest"              >> .env
echo "RABBIT_DEFAULT_PASS=guest"              >> .env
echo "HOST_PORT_RABBIT=5672"                  >> .env
echo "HOST_PORT_RABBIT_MGMT=15672"            >> .env

# Start container
docker-compose up -d php httpd bind rabbit

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Enable and configure Solr¶

This section will guide you through getting Solr integrated into the Devilbox.

See also

Table of Contents

Overview
Instructions
TL;DR

Overview ¶

Available overwrites ¶

The Devilbox ships various example configurations to overwrite the default stack. Those files are located under compose/ in the Devilbox git directory.

docker-compose.override.yml-all has all examples combined in one file for easy copy/paste. However, each example also exists in its standalone file as shown below:

host> tree -L 1 compose/
compose/
├── docker-compose.override.yml-all
├── docker-compose.override.yml-blackfire
├── docker-compose.override.yml-elk
├── docker-compose.override.yml-mailhog
├── docker-compose.override.yml-meilisearch
├── docker-compose.override.yml-ngrok
├── docker-compose.override.yml-php-community
├── docker-compose.override.yml-python-flask
├── docker-compose.override.yml-rabbitmq
├── docker-compose.override.yml-solr
├── docker-compose.override.yml-varnish
└── README.md

0 directories, 10 files

See also

Solr settings ¶

In case of Solr, the file is compose/docker-compose.override.yml-solr. This file must be copied into the root of the Devilbox git directory.

What	How and where
Example compose file	`compose/docker-compose.override.yml-all` or `compose/docker-compose.override.yml-solr`
Container IP address	`172.16.238.220`
Container host name	`solr`
Container name	`solr`
Mount points	via Docker volumes
Exposed port	`8983` (can be changed via `.env`)
Available at	`http://localhost:8983` (API and Admin WebUI)
Further configuration	none

Solr env variables ¶

Additionally the following .env variables can be created for easy configuration:

Variable	Default value	Description
`HOST_PORT_SOLR`	`8983`	Controls the host port on which Solr API and WebUIwill be available at.
`SOLR_SERVER`	`latest`	Controls the Solr version to use.
`SOLR_CORE_NAME`	`devilbox`	Default Solr core name

Instructions ¶

1. Copy docker-compose.override.yml ¶

Copy the Solr Docker Compose overwrite file into the root of the Devilbox git directory. (It must be at the same level as the default docker-compose.yml file).

host> cp compose/docker-compose.override.yml-solr docker-compose.override.yml

See also

2. Adjust `.env` settings (optional)¶

Solr is using sane defaults, which can be changed by adding variables to the .env file and assigning custom values.

Add the following variables to .env and adjust them to your needs:

.env¶

# Solr version to choose
#SOLR_SERVER=5
#SOLR_SERVER=6
#SOLR_SERVER=7
SOLR_SERVER=latest

SOLR_CORE_NAME=devilbox
HOST_PORT_SOLR=8983

See also

3. Start the Devilbox ¶

The final step is to start the Devilbox with Solr.

Let’s assume you want to start php, httpd, bind, solr.

host> docker-compose up -d php httpd bind solr

See also

TL;DR ¶

For the lazy readers, here are all commands required to get you started. Simply copy and paste the following block into your terminal from the root of your Devilbox git directory:

# Copy compose-override.yml into place
cp compose/docker-compose.override.yml-solr docker-compose.override.yml

# Create .env variable
echo "# Solr version to choose"         >> .env
echo "#SOLR_SERVER=5"                   >> .env
echo "#SOLR_SERVER=6"                   >> .env
echo "#SOLR_SERVER=7"                   >> .env
echo "SOLR_SERVER=latest"               >> .env
echo "SOLR_CORE_NAME=devilbox"          >> .env
echo "HOST_PORT_SOLR=8983"              >> .env

# Start container
docker-compose up -d php httpd bind solr

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Enable and configure Varnish¶

This section will guide you through getting Varnish integrated into the Devilbox.

As Varnish itself does not handle HTTPS, its Docker Compose override definition also defines an optional HAProxy that can be started and run in front of Varnish to provide HTTPS support and take care of the SSL offloading before requests hit Varnish.

See also

Table of Contents

Overview
Instructions
TL;DR

Overview ¶

Available overwrites ¶

The Devilbox ships various example configurations to overwrite the default stack. Those files are located under compose/ in the Devilbox git directory.

docker-compose.override.yml-all has all examples combined in one file for easy copy/paste. However, each example also exists in its standalone file as shown below:

host> tree -L 1 compose/
compose/
├── docker-compose.override.yml-all
├── docker-compose.override.yml-blackfire
├── docker-compose.override.yml-elk
├── docker-compose.override.yml-mailhog
├── docker-compose.override.yml-meilisearch
├── docker-compose.override.yml-ngrok
├── docker-compose.override.yml-php-community
├── docker-compose.override.yml-python-flask
├── docker-compose.override.yml-rabbitmq
├── docker-compose.override.yml-solr
├── docker-compose.override.yml-varnish
└── README.md

0 directories, 10 files

See also

Stack settings ¶

In case of Varnish, the file is compose/docker-compose.override.yml-varnish. This file must be copied into the root of the Devilbox git directory.

What	How and where
Example compose file	`compose/docker-compose.override.yml-all` or `compose/docker-compose.override.yml-varnish`

Varnish ¶

What	How and where
Container IP address	`172.16.238.230`
Container host name	`varnish`
Container name	`varnish`
Mount points	none
Exposed port	`6081` (can be changed via `.env`)
Available at	`http://localhost:6081` (or via `http:<project>.<TLD>:6081`)
Further configuration	none

HAProxy ¶

What	How and where
Container IP address	`172.16.238.231`
Container host name	`haproxy`
Container name	`haproxy`
Mount points	none
Exposed port	`8080` for HTTP and `8443` for HTTPS (can be changed via `.env`)
Available at	`http://localhost:8080`, `http://localhost:8443` (or via `http:<project>.<TLD>:8080\|8443`)
Further configuration	none

Stack env variables ¶

Additionally the following .env variables can be created for easy configuration:

Varnish ¶

Variable	Default value	Description
`HOST_PORT_VARNISH`	`6081`	Controls the host port on which Varnish will be available at.
`VARNISH_SERVER`	`6`	Controls the Varnish version to use.
`VARNISH_CONFIG`	`/etc/varnish/default.vcl`	Path to Varnish configuration file (custom config can be mounted).
`VARNISH_CACHE_SIZE`	`128m`	Varnish Cache size.
`VARNISH_PARAMS`	`-p default_ttl=3600 -p default_grace=3600`	Additional Varnish startup parameter.

HAProxy ¶

Variable	Default value	Description
`HOST_PORT_HAPROXY`	`8080`	Controls the host port on which HTTP requests will be available for HAProxy.
`HOST_PORT_HAPROXY_SSL`	`8443`	Controls the host port on which HTTPS requests will be available for HAProxy.

Instructions ¶

1. Copy docker-compose.override.yml ¶

Copy the Varnish Docker Compose overwrite file into the root of the Devilbox git directory. (It must be at the same level as the default docker-compose.yml file).

host> cp compose/docker-compose.override.yml-varnish docker-compose.override.yml

See also

2. Adjust `.env` settings (optional)¶

Varnish and HAProxy are using sane defaults, which can be changed by adding variables to the .env file and assigning custom values.

Add the following variables to .env and adjust them to your needs:

.env¶

# Varnish version to choose
#VARNISH_SERVER=4
#VARNISH_SERVER=5
VARNISH_SERVER=6

# Varnish settings
VARNISH_CONFIG=/etc/varnish/default.vcl
VARNISH_CACHE_SIZE=128m
VARNISH_PARAMS=-p default_ttl=3600 -p default_grace=3600
HOST_PORT_VARNISH=6081

# HAProxy settings
HOST_PORT_HAPROXY=8080
HOST_PORT_HAPROXY_SSL=8443

See also

3. Custom Varnish config (optional)¶

Varnish comes with a pretty generic default configuration that should fit most frameworks or CMS’s. If you do however want to provide your own custom Varnish configuration, you can do so for each Varnish version separately.

Place any *.vcl files in to the Varnish configuration directories (found in cfg/).

host> tree -L 1 cfg/ | grep varnish
├── varnish-4
├── varnish-5
├── varnish-6

The varnish-X/ directory will be mounted into /etc/varnish.d/ into the running Varnish container
Adjust the VARNISH_CONFIG variable to point to your custom Varnish config file.

3.1 Example ¶

For this example we will assume you are using Varnish 6

Add my-varnish.vcl into cfg/varnish-6/
Set VARNISH_CONFIG to /etc/varnish.d/my-varnish.vcl
Ensure that the Backend server points to httpd in your custom varnish config
Ensure that the Backend port points to 80 in your custom varnish config

4. Start the Devilbox ¶

The final step is to start the Devilbox with Varnish.

See also

https://github.com/cytopia/docker-bind

4.1 Varnish only ¶

Let’s assume you want to start php, httpd, bind, varnish.

host> docker-compose up -d php httpd bind varnish

4.2 HTTPS offloading with HAProxy in front of Varnish ¶

If you also want full HTTPS support, simply start HAproxy as well with Varnish.

host> docker-compose up -d php httpd bind haproxy varnish

TL;DR ¶

For the lazy readers, here are all commands required to get you started. Simply copy and paste the following block into your terminal from the root of your Devilbox git directory:

# Copy compose-override.yml into place
cp compose/docker-compose.override.yml-varnish docker-compose.override.yml

# Create .env variable
echo "# Varnish version to choose"                               >> .env
echo "#VARNISH_SERVER=4"                                         >> .env
echo "#VARNISH_SERVER=5"                                         >> .env
echo "VARNISH_SERVER=6"                                          >> .env
echo "# Varnish settings"                                        >> .env
echo "VARNISH_CONFIG=/etc/varnish/default.vcl"                   >> .env
echo "VARNISH_CACHE_SIZE=128m"                                   >> .env
echo "VARNISH_PARAMS=-p default_ttl=3600 -p default_grace=3600"  >> .env
echo "HOST_PORT_VARNISH=6081"                                    >> .env
echo "# HAProxy settings"                                        >> .env
echo "HOST_PORT_HAPROXY=8080"                                    >> .env
echo "HOST_PORT_HAPROXY_SSL=8443"                                >> .env

# Start container
docker-compose up -d php httpd bind varnish

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Shared Devilbox server in LAN¶

Devilbox as a shared development, staging or CI server is setup in a similar way as you would do locally. The only three important parts to take care of are:

Project access to deploy/update code
Handle DNS entries
Share Devilbox CA

Table of Contents

Prerequisites
Project access
- SSH
- Samba
Handle DNS records
Share Devilbox CA

Prerequisites ¶

This walk-through will use the following example values:

LAN / Network	Devilbox server	TLD_SUFFX	LOCAL_LISTEN_ADDR
`192.168.0.0/24`	`192.168.0.12`	`loc`	`192.168.0.12` or empty

See also

Project access ¶

SSH ¶

Enable and start an SSH server and give access to whatever system or user requires it. This can be done directly on the host system or via various other Docker container that offer ssh server.

Copy via sftp ¶

If your SSH server is setup, users can use their sftp clients to deploy code updates. This however is not encouraged and you should use git or any other version control system.

Manually git pull/checkout ¶

When using git, users can directly ssh into the shared Devilbox server and git pull or git checkout <branch> on their projects.

Automated git pull/checkout ¶

In case you are using a staging or CI server, use Jenkins jobs or other automation tools (e.g. Ansible) to auto-deploy via SSH.

Samba ¶

For a shared development server, you could also setup Samba network shares for each projects and have users deploy their code via Samba.

Handle DNS records ¶

There are multiple ways of having DNS records available accross the LAN.

Before you read on, have a quick look on the decision Matrix to find the best method for your use-case.

Method	Sub-method	Outcome
Real domain		All network devices will have Auto DNS
Own DNS server		All network devices will have Auto DNS
Devilbox DNS server	Manual	Every network device must configure its DNS settings
Devilbox DNS server	DHCP distributed	All network devices will have Auto DNS
Hosts entry		Every network device must manually set hosts entries for each project. (Does not work for phones)

Important

When using a shared Devilbox server and another Devilbox setup on your local computer, ensure that you are using different TLD_SUFFIX in order to not confuse DNS records.

Use a real domain ¶

(This will allow all devices on the network to have Auto-DNS)

If you own a real domain, such as my-company.com, you can create a wildcard DNS record for a subdomain, such as *.dev.my-company.com which must point to 192.168.0.12.. This should be done in your hosting provider’s DNS configuration pannel.

You must then also change the TLD_SUFFIX to that subdomain.

.env¶

TLD_SUFFIX=dev.my-company.com

Handle DNS records in your own DNS server ¶

(This will allow all devices on the network to have Auto-DNS)

If your LAN already provides its own customizable DNS server, you can setup a new wildcard DNS zone for *.loc which points to 192.168.0.12.

Run a second instance of the Devilbox DNS server ¶

If the above two methods for automated DNS records don’t apply to you, you will need to run a second stand-alone Docker container of the Devilbox DNS server.

Run this container permantently on the shared Devilbox server with the following command:

host> docker run -d \
        --restart unless-stopped \
        -p 53:53/tcp \
        -p 53:53/udp \
        -e WILDCARD_DNS='loc=192.168.0.12' \
        -t cytopia/bind

See also

Now there are two ways to consume the DNS records on your local machine:

Manual
DHCP distributed

Manual DNS settings ¶

(Each device on the network needs to manually set the DNS server)

When using this approach, you have to manually add the DNS server (IP: 192.168.0.12) to your host operating system.

Important

Keep in mind that you have to do this for every machine within the network which wants to access the shared Devilbox server.

See also

DHCP distributed ¶

(This will allow all devices on the network to have Auto-DNS)

This is the automated and more pain-free approach, as all devices within the network will be able to access projects on the shared Devilbox server.

Self-managed DHCP server ¶

If you run your own DHCP server within a network, you probably know how to add other DNS servers. The only thing you should keep in mind is, that the Devilbox DNS server should be the first in the list.

DSL box / LAN or WIFI router ¶

Most SOHO networks probably use some vendor router which has a web interface. Generally speaking, you need to find the DNS/DHCP settings in its web interface and add the Devilbox DNS server as the first in the list (192.168.0.12).

See also

Change DNS server in Fritzbox

Add hosts entries for every project ¶

(Each device on the network needs to manually set the hosts entries for every single projcet)

As you also do for the Devilbox locally when not using Auto-DNS, you can do as well for remote computer. Just edit your local hosts file and add one DNS entry for every project on the shared Devilbox server.

Keep in mind that this time you will have to use 192.168.0.12 instead of 127.0.0.1.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Use external databases¶

Table of Contents

Why
Database on host os
Database on network
Database on internet

Why ¶

Some people or companies might have concerns with dockerized databases and rather rely on good old host-based database setups. There could already be a database cluster in your network or you rather want to use AWS RDS or other cloud-based solutions.

There are many reasons for having an external database.

Database on host os ¶

Note

If the local database is listening on an IP address that is reachable over your current LAN, you can directly skip to: Database on network

In order to use an already existing database that is running on the host os, you need to make sure the following is met:

Be able to connect to the host os from inside the container

See also

Connect to host OS
Configure your application to use the IP/CNAME of the host os

When starting the Devilbox, explicitly specify the service to use and exclude the databases:

# Explicitly specify services to start (otherwise all will start)
# Omit the database
host> docker-compose up -d php httpd bind redis

See also

Database on network ¶

In order to use an already existing database that is running on the network, you need to make sure the following is met:

Configure your application to use the IP/CNAME of the database host

When starting the Devilbox, explicitly specify the service to use and exclude the databases:

# Explicitly specify services to start (otherwise all will start)
# Omit the database
host> docker-compose up -d php httpd bind redis

See also

Database on internet ¶

In order to use an already existing database that is running on the network, you need to make sure the following is met:

Configure your application to use the IP/CNAME of the database host

When starting the Devilbox, explicitly specify the service to use and exclude the databases:

# Explicitly specify services to start (otherwise all will start)
# Omit the database
host> docker-compose up -d php httpd bind redis

See also

Connect to external hosts

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Showcase over the internet¶

Table of Contents

Why
How
- Examples

Why ¶

Sometimes it is just convinient to make your local project available over the internet to quickly showcase your current work to a customer. Instead of having to deploy it somewhere and even be able to live code during the showcase the Devilbox provides an easy way to accomplish exactly this via Ngrok.

How ¶

First you want to add Ngrok to the Devilbox stack via its pre-defined Docker Compose override file.

See also

Enable and configure Ngrok

Once you have followed the above documentation everything works with default settings. To actually customize and choose the virtual host to expose you will need to alter the NGROK_HTTP_TUNNELS .env variable.

How this can be done exactly will be shown in a couple of examples below.

Examples ¶

Recall the following formats for the variable:

<domain.tld>:<addr>:<port>
<domain1.tld>:<addr>:<port>,<domain2.tld>:<addr>:<port>

Note

Even more than two tunnels are supported, but this will again depend on your Ngrok license.

Where each individual part consists of:

<domain.tld> is the virtual hostname that you want to serve via Ngrok
<addr> is the hostname or IP address of the web server
<port> is the port on which the web server is reachable via HTTP

Expose `my-project.loc` via web server ¶

<domain.tld>: my-project.loc
<addr>: httpd
<port>: httpd80

So the resulting .env value will be:

NGROK_HTTP_TUNNELS=my-project.loc:httpd:80

Expose `my-project.loc` via Varnish ¶

<domain.tld>: my-project.loc
<addr>: varnish
<port>: 6081

So the resulting .env value will be:

NGROK_HTTP_TUNNELS=my-project.loc:varnish:6081

Expose `my-project.loc` via HAProxy ¶

<domain.tld>: my-project.loc
<addr>: haproxy
<port>: 80

So the resulting .env value will be:

NGROK_HTTP_TUNNELS=my-project.loc:haproxy:80

Expose `my-project.loc` and `website1.loc` via web server ¶

Note

Exposing more than one vhost will require a pro enough license from Ngrok.

<domain.tld>: my-project.loc
<addr>: httpd
<port>: 80

and

<domain.tld>: website1.loc
<addr>: httpd
<port>: 80

So the resulting .env value will be:

NGROK_HTTP_TUNNELS=my-project.loc:httpd:80,website1.loc:httpd:80

Expose `my-project.loc` via web server and varnish ¶

Note

Exposing more than one vhost will require a pro enough license from Ngrok.

<domain.tld>: my-project.loc
<addr>: httpd
<port>: 80

and

<domain.tld>: my-project.loc
<addr>: varnish
<port>: 6081

So the resulting .env value will be:

NGROK_HTTP_TUNNELS=my-project.loc:httpd:80,my-project.loc:varnish:6081

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Checkout different Devilbox release¶

You now have the devilbox downloaded at the latest version (git master branch). This is also recommended as it receives bugfixes frequently. If you however want to stay on a stable release, you need to check out a specific git tag.

Lets say you want your devilbox setup to be at release v1.0.1, all you have to do is to check out this specific git tag.

host> cd path/to/devilbox
# Ensure you have latest from remote
host> git fetch
# Switch to this release
host> git checkout v1.0.1

Warning

Whenever you check out a different version, make sure that your .env file is up-to-date with the bundled env-example file. Different Devilbox releases might require different settings to be available inside the .env file. Refer to the next section for how to create the .env file.

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Remove stopped container¶

Why should I?¶

If you simply docker-compose stop in order to stop all containers, they are still preserved in the docker ps -a process list and still have state.

In case you change any path variables inside the .env file (or silently due to git updates), you need to completely re-create the state.

This is done by first fully removing the container and then simply starting it again.

How to do it?¶

host> docker-compose stop
host> docker-compose rm

When to do it?¶

Whenever path values inside the .env file change.

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Update the Devilbox¶

If you are in the initial install process, you can safely skip this section and come back once you actually want to update the Devilbox.

Table of Contents

Update git repository
Update Docker images
Checklist git repository
Checklist Docker images

Update git repository ¶

Stop container ¶

Before updating your git branch or checking out a different tag or commit, make sure to properly stop all devilbox containers:

# Stop containers
host> cd path/to/devilbox
host> docker-compose stop
# Remove stopped container (required)
host> docker-compose rm -f

# Ensure containers are stopped
host> docker-compose ps

Case 1: Update master branch ¶

If you simply want to update the master branch, do a git pull origin master:

# Update master branch
host> cd path/to/devilbox
host> git pull origin master

Case 2: Checkout release tag ¶

If you want to checkout a specific release tag (such as 0.12.1), do a git checkout 0.12.1:

# Checkout release
host> cd path/to/devilbox
# Ensure you have latest from remote
host> git fetch
host> git checkout v1.0.1

Keep `.env` file in sync ¶

Important

Whenever you check out a different version, make sure that your .env file is up-to-date with the bundled env-example file. Different Devilbox releases might require different settings to be available inside the .env file.

You can also compare your current .env file with the provided env-example file by using your favorite diff editor:

host> vimdiff .env env-example

host> diff .env env-example

host> meld .env env-example

Keep `vhost-gen` templates in sync ¶

Important

Whenever you check out a different version, make sure that the vhost-gen templates that have been copied to any virtual hosts are up-to-date with the templates provided in cfg/vhost-gen/.

Recreate container ¶

Whenever the path of a volume changes (either due to upstream changes in git or due to you changing it manually in the .env file) you need to remove the stopped container and have them fully recreated during the next start.

# Remove anonymous volumes
host> cd path/to/devilbox
host> docker-compose rm -f

See also

Remove stopped container

Update Docker images ¶

Updating the git branch shouldn’t be needed to often, most changes are actually shipped via newer Docker images, so you should frequently update those.

This is usually achieved by issueing a docker pull command with the correct image name and image version or docker-compose pull for all currently selected images in .env file. For your convenience there is a shell script in the Devilbox git directory: update-docker.sh which will update all available Docker images at once for every version.

Note

The Devilbox own Docker images (Apache, Nginx, PHP and MySQL) are even built every night to ensure latest security patches and tool versions are applied.

Update one Docker image ¶

Updating or pulling a single Docker image is accomplished by docker pull <image>:<tag>. This is not very handy as it is quite troublesome to do it separately per Docker image.

You first need to find out the image name and then also the currently used image tag.

host> grep 'image:' docker-compose.yml

image: cytopia/bind:0.11
image: devilbox/php-fpm:${PHP_SERVER}-work
image: devilbox/${HTTPD_SERVER}:0.13
image: devilbox/mysql-${MYSQL_SERVER}
image: postgres:${PGSQL_SERVER}
image: redis:${REDIS_SERVER}
image: memcached:${MEMCD_SERVER}
image: mongo:${MONGO_SERVER}

After having found the possible candidates, you will still have to find the corresponding value inside the ..env file. Let’s do it for the PHP image:

host> grep '^PHP_SERVER' .env

PHP_SERVER=7.2

So now you can substitute the ${PHP_SERVER} variable from the first command with 7.2 and finally pull a newer version:

host> docker pull devilbox/php-fpm:7.2-work

Not very efficient.

Update all currently set Docker images ¶

This approach is using docker-compose pull to update all images, but only for the versions that are actually set in .env.

host> docker-compose pull

Pulling bind (cytopia/bind:0.11)...
Pulling php (devilbox/php-fpm:5.6-work)...
Pulling httpd (devilbox/apache-2.2:0.13)...
Pulling mysql (cytopia/mysql-5.7:latest)...
Pulling pgsql (postgres:9.6)...
Pulling redis (redis:4.0)...
Pulling memcd (memcached:1.5.2)...
Pulling mongo (mongo:3.0)...

This is most likely the variant you want.

Update all available Docker images for all versions ¶

In case you also want to pull/update every single of every available Devilbox image, you can use the provided shell script, which has all versions hardcoded and pulls them for you:

host> ./update-docker.sh

Checklist git repository ¶

Ensure containers are stopped and removed/recreated (docker-compose stop && docker-compose rm)
Ensure desired branch, tag or commit is checked out or latest changes are pulled
Ensure .env file is in sync with env-example file
Ensure all of your custom applied vhost-gen templates are in sync with the default templates

Checklist Docker images ¶

Ensure docker-compose pull or ./update-docker.sh is executed
Ensure docker-compose rm -f is executed after stopping the Devilbox

See also

Troubleshooting: What to always do first

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Remove the Devilbox¶

If you want to completely remove the Devilbox follow this tutorial.

Table of Contents

Backups
Remove the Devilbox
Revert your system changes

Backups ¶

Before deleting the Devilbox git directory, ask yourself if you want to make backups of all customizations you have done so far as well as of all data that may be present within that directory.

Dump databases ¶

Before shutting down the Devilbox, do a final backup of all of your databases:

See also

Dumps will end up in backups/.

Shutdown the Devilbox ¶

Before attempting to backup any file system data, make sure the Devilbox is properly shutdown.

host> docker-compose stop

Backup configuration files ¶

You should now backup the following configuration files:

Backup your customized .env file
Backup your customized .docker-compose.override.yml file
Backup your customized bash configuration from bash/
Backup all custom service configurations from cfg/
Backup the Devilbox root certificate from ca/

Backup data and dumps ¶

You should now backup the following data:

Backup any backups created in backups/
Backup any project or Docker data from data/

Remove the Devilbox ¶

If you have followed the backup routine, you can continue deleting all created components.

Remove Devilbox containers ¶

Navigate to the Devilbox git directory and remove all Devilbox container:

host> docker-compose rm -f

Remove Devilbox network ¶

List all existing Docker networks via

host> docker network ls

NETWORK ID          NAME                                 DRIVER              SCOPE
0069843ff0c3        bridge                               bridge              local
...
9c8d4a84cf2d        devilbox_app_net                     bridge              local

Find the NETWORK ID of the Devilbox network and delete it:
```
host> docker network rm 9c8d4a84cf2d
```

Remove Devilbox git directory ¶

You can simply delete the whole Devilbox git directory

Revert your system changes ¶

AutoDNS ¶

Revert any changes you have done for Auto-DNS to work.

See also

Setup Auto DNS

Manual DNS entries ¶

Revert any changes you have done in /etc/hosts (or C:\Windows\System32\drivers\etc for Windows)

See also

Remove Devilbox CA from your browser ¶

Remove the Devilbox CA from your browser

See also

Setup valid HTTPS

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

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

phpMyAdmin ¶

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

Adminer ¶

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

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.

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

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
Restore

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

phpPgAdmin ¶

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

Adminer ¶

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

Restore ¶

psql ¶

In order to restore or import PostgreSQL databases on the command line, you need to use pgsql . 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

phpPgAdmin ¶

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

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

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

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

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

.env file¶

All docker-compose configuration is done inside the .env file which simply defines key-value pairs evaluated by docker-compose.yml.

If this file does not exist at the root of your Devilbox git directory, then copy env-example to .env to initially create it with sane defaults.

See also

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_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_ENTRYPOINT`	`0`, `1`, `2`, `3`, `4`	`2`

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`

Warning

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

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.

Warning

Do not use official domain endings such as .com, .org, .net, etc. If you do, all name resolutions to any .com address (e.g.: google.com) will be resolved to the Devilbox’s PHP server IP address.

The bundled DNS server does a catch-all on the given TLD_SUFFIX and resolves everything below it to the PHP container.

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

Have a look at Wikipedia to get a list of valid timezones: Wikipedia: List of database timezones

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

Add custom environment variables

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`

DEVILBOX_VENDOR_PHPMYADMIN_AUTOLOGIN ¶

By default phpMyAdmin will autologin without having to specify username or password. The phpMyAdmin vendor is not protected once you protect the Intranet. If you want users to enter username and password here as well, you should set the value to 0.

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

DEVILBOX_VENDOR_PHPPGADMIN_AUTOLOGIN ¶

By default phpPgAdmin will autologin without having to specify username or password. The phpPgAdmin vendor is not protected once you protect the Intranet. If you want users to enter username and password here as well, you should set the value to 0.

Name	Allowed values	Default value
`DEVILBOX_VENDOR_PHPPGADMIN_AUTOLOGIN`	`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.2` `php-fpm-5.3` `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.3` `php-fpm-7.4` `php-fpm-8.0` `php-fpm-8.1` `php-fpm-8.2`	`php-fpm-8.1`

Important

PHP 5.2 is available to use, but it is not officially supported. The Devilbox intranet does not work with this version as PHP 5.2 does not support namespaces. Furthermore PHP 5.2 does only work with Apache 2.4, Nginx stable and Nginx mainline. It does not work with Apache 2.2. Use at your own risk.

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.2
#PHP_SERVER=php-fpm-5.3
#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=php-fpm-7.4
#PHP_SERVER=php-fpm-8.0
PHP_SERVER=php-fpm-8.1
#PHP_SERVER=php-fpm-8.2

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.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 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=percona-5.5
#MYSQL_SERVER=percona-5.6
#MYSQL_SERVER=percona-5.7
#MYSQL_SERVER=percona-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=mariadb-10.4
#MYSQL_SERVER=mariadb-10.5
MYSQL_SERVER=mariadb-10.6
#MYSQL_SERVER=mariadb-10.7
#MYSQL_SERVER=mariadb-10.8
#MYSQL_SERVER=mariadb-10.9
#MYSQL_SERVER=mariadb-10.10

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	`14-alpine`

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.0
#PGSQL_SERVER=9.1
#PGSQL_SERVER=9.2
#PGSQL_SERVER=9.2-alpine
#PGSQL_SERVER=9.3
#PGSQL_SERVER=9.3-alpine
#PGSQL_SERVER=9.4
#PGSQL_SERVER=9.4-alpine
#PGSQL_SERVER=9.5
#PGSQL_SERVER=9.5-alpine
#PGSQL_SERVER=9.6
#PGSQL_SERVER=9.6-alpine
#PGSQL_SERVER=10
#PGSQL_SERVER=10-alpine
#PGSQL_SERVER=11
#PGSQL_SERVER=11-alpine
#PGSQL_SERVER=12
#PGSQL_SERVER=12-alpine
#PGSQL_SERVER=13
#PGSQL_SERVER=13-alpine
#PGSQL_SERVER=14
PGSQL_SERVER=14-alpine
#PGSQL_SERVER=15
#PGSQL_SERVER=15-alpine
#PGSQL_SERVER=latest
#PGSQL_SERVER=alpine

Note

This is the official PostgreSQL server which might already have other tags available, check their official website for even more versions. PostgreSQL

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	`6.2-alpine`

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.0-alpine
#REDIS_SERVER=3.2
#REDIS_SERVER=3.2-alpine
#REDIS_SERVER=4.0
#REDIS_SERVER=4.0-alpine
#REDIS_SERVER=5.0
#REDIS_SERVER=5.0-alpine
#REDIS_SERVER=6.0
#REDIS_SERVER=6.0-alpine
#REDIS_SERVER=6.2
REDIS_SERVER=6.2-alpine
#REDIS_SERVER=7.0
#REDIS_SERVER=7.0-alpine
#REDIS_SERVER=latest
#REDIS_SERVER=alpine

Note

This is the official Redis server which might already have other tags available, check their official website for even more versions. Redis

MEMCD_SERVER ¶

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

Name	Allowed values	Default value
`MEMCD_SERVER`	`1.4` `1.4-alpine` `1.5` `1.5-alpine` and many more	`1.6-alpine`

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
#MEMCD_SERVER=1.4-alpine
#MEMCD_SERVER=1.5
#MEMCD_SERVER=1.5-alpine
#MEMCD_SERVER=1.6
MEMCD_SERVER=1.6-alpine
#MEMCD_SERVER=latest
#MEMCD_SERVER=alpine

Note

This is the official Memcached server which might already have other tags available, check their official website for even more versions. 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	`5.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 MONGO_SERVER .env

#MONGO_SERVER=2.8
#MONGO_SERVER=3.0
#MONGO_SERVER=3.2
#MONGO_SERVER=3.4
#MONGO_SERVER=3.6
#MONGO_SERVER=4.0
#MONGO_SERVER=4.2
#MONGO_SERVER=4.4
MONGO_SERVER=5.0
#MONGO_SERVER=latest

Note

This is the official MongoDB server which might already have other tags available, check their official website for even more versions. MongoDB

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.

MOUNT_OPTIONS ¶

This variable allows you to add custom mount options/flags to all mounted directories. Initially only rw or ro are applied to mount points, you can however extend this before starting up the Devilbox.

Name	Allowed values	Default value
`MOUNT_OPTIONS`	valid mount option	empty

If you are on Linux with SELinux enabled, you will want to set this value to ,z to modify SELinux labels in order to share mounts among multiple container.

See also

Important

When adding custom mount options, ensure to start with a leading ,, as those options are prepended to already existing options.

MOUNT_OPTIONS=,z
MOUNT_OPTIONS=,cached

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_BACKUPDIR ¶

The path on your host OS of the database backup directory to be mounted into the PHP container into /shared/backups.

Name	Allowed values	Default value
`HOST_PATH_BACKUPDIR`	valid path	`./backups`

HOST_PATH_SSH_DIR ¶

The path on your host OS of the ssh directory to be mounted into the PHP container into /home/devilbox/.ssh.

Note

The path is mounted read-only to ensure you cannot accidentally delete any ssh keys from inside the php container.

Name	Allowed values	Default value
`HOST_PATH_SSH_DIR`	valid path	`~/.ssh`

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 and the Devilbox: 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.

Name	Allowed values	Default value
`HOST_PORT_HTTPD_SSL`	`1` - `65535`	`443`

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: Setup Auto DNS.

Container settings ¶

PHP ¶

PHP_MODULES_ENABLE ¶

Enable any non-standard PHP modules in a comma separated list.

Name	Allowed values	Default value
`PHP_MODULES_ENABLE`	comma separated list of module names	empty

Note

Currently only ioncube and blackfire are available to enable.

Example:

.env¶

# Enable ionCube
PHP_MODULES_ENABLE=ioncube

# When enabling blackfire or ionCube you must also disable xdebug:
# https://xdebug.org/docs/install#compat
PHP_MODULES_DISABLE=xdebug

.env¶

# Enable blackfire
PHP_MODULES_ENABLE=blackfire

# When enabling blackfire or ionCube you must also disable xdebug:
# https://xdebug.org/docs/install#compat
PHP_MODULES_DISABLE=xdebug

.env¶

# Enable both, blackfire and ionCube
PHP_MODULES_ENABLE=blackfire,ioncube

# When enabling blackfire or ionCube you must also disable xdebug:
# https://xdebug.org/docs/install#compat
PHP_MODULES_DISABLE=xdebug

PHP_MODULES_DISABLE ¶

Disable any PHP modules in a comma separated list.

Name	Allowed values	Default value
`PHP_MODULES_DISABLE`	comma separated list of module names	`oci8,PDO_OCI,pdo_sqlsrv,sqlsrv,rdkafka,swoole`

Example:

.env¶

# Disable Xdebug, Imagick and Swoole
PHP_MODULES_DISABLE=xdebug,imagick,swoole

PHP_MAIL_CATCH_ALL ¶

Postfix settings for email catch-all.

When set to 0 postfix will be disabled and not started.

When set to 1 postfix is normally started and made available. However you still need to configure it to your needs yourself. For that you can use the autostart scripts and define a couple of postconf -e name=value commands.

When set to 2 (email catch-all) postfix is started, but no mail will leave the Devilbox. It is automatically internally routed the the devilbox mail account and you can see each sent mail in the bundled intranet: https://localhost/mail.php

Name	Allowed values	Default value
`PHP_MAIL_CATCH_ALL`	`0`, `1`, `2`	`2`

Example:

.env¶

# Enable Postfix without email catch-all
PHP_MAIL_CATCH_ALL=1

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

Web server ¶

HTTPD_SSL_TYPE ¶

SSL (HTTP/HTTPS) settings for automated vhost generation.

By default each project will have two vhosts (one for HTTP and one for HTTPS). You can control the SSL settings for your projects via the below stated values.

This is internally achieved via the -m argument of vhost-gen

both will serve HTTP and HTTPS for all projects
redir will always redirect HTTP to HTTPS
ssl will only serve HTTPS
plain will only serve HTTP

Name	Allowed values	Default value
`HTTPD_SSL_TYPE`	`both`, `redir`, `ssl`, `plain`	`both`

HTTPD_HTTP2_ENABLE ¶

HTTP/2 protocol settings.

By default each HTTP server (Apache and Nginx) will use HTTP/2 when the browser supports it. This setting cannot be set on a vhost level, but must be set globally on a server level.

If you wiush to disable HTTP/2, you can do so with this variable.

1 HTTP/2 enabled (default)
0 HTTP/2 disabled

Name	Allowed values	Default value
`HTTPD_HTTP2_ENABLE`	`0`, `1`	`1`

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 cfg/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 cfg/vhost-gen/*.yml 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:

vhost-gen: Virtual host templates
vhost-gen: Customize all virtual hosts globally
vhost-gen: Customize specific virtual host
vhost-gen: Example: add sub domains

HTTPD_BACKEND_TIMEOUT ¶

This variable specifies after how many seconds the webserver should quit an unanswered connection to PHP-FPM.

Ensure that this value is higher than PHP’s max_execution_time, otherwise the PHP script could still run and the webserver will simply drop the connection before getting an answer by PHP.

If HTTPD_BACKEND_TIMEOUT is smaller then max_execution_time and a script runs longer than max_execution_time, you will get a: 504 Gateway timeout in the browser.

If HTTPD_BACKEND_TIMEOUT is greater then max_execution_time and a script runs longer than max_execution_time, you will get a proper PHP error message in the browser.

Name	Allowed values	Default value
`HTTPD_BACKEND_TIMEOUT`	positive integer	`180`

HTTPD_NGINX_WORKER_PROCESSES ¶

Defines the number of worker processes for Nginx, i.e, the number of CPU cores.

The optimal value depends on many factors including (but not limited to) the number of CPU cores, the number of hard disk drives that store data, and load pattern. When one is in doubt, setting it to the number of available CPU cores would be a good start (the value “auto” will try to autodetect it).

Name	Allowed values	Default value
`HTTPD_NGINX_WORKER_PROCESSES`	positive integer \| auto	`auto`

Note

This setting only applies to Nginx and has no effect for Apache.

HTTPD_NGINX_WORKER_CONNECTIONS ¶

Sets the maximum number of simultaneous connections that can be opened by a worker process.

It should be kept in mind that this number includes all connections (e.g. connections with proxied servers, among others), not only connections with clients. Another consideration is that the actual number of simultaneous connections cannot exceed the current limit on the maximum number of open files, which can be changed by worker_rlimit_nofile.

Name	Allowed values	Default value
`HTTPD_NGINX_WORKER_CONNECTIONS`	positive integer	`1024`

Note

This setting only applies to Nginx and has no effect for Apache.

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.

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.

PGSQL_HOST_AUTH_METHOD ¶

This variable has been set to trust by default to allow empty PostgreSQL root user passwords. If you want to set a password for the root user, ensure this variable is empty.

Name	Allowed values	Default value
`PGSQL_HOST_AUTH_METHOD`	`trust` or empty	`trust`

Redis ¶

REDIS_ARGS ¶

This option lets you add extra startup parameters to Redis. This could include adding a password protection to Redis or increasing its verbosity.

Name	Allowed values	Default value
`REDIS_ARGS`	valid `redis-server` startup parameter	empty

Example: Adding password protection ¶

REDIS_ARGS=--requirepass my-redis-root-password

Important

Do not quote the password and do not use spaces inside the password.

Example: Increasing verbosity ¶

REDIS_ARGS=--loglevel verbose

Example: Combining options ¶

REDIS_ARGS=--loglevel verbose --requirepass my-redis-root-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

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

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

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

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

How does docker-compose.override.yml work?
Create docker-compose.override.yml
- Copy example file
- Create new file from scratch
Further reading

How does docker-compose.override.yml work?¶

When you run docker-compose up, it searches for a file named docker-compose.yml and reads all configured services, networks, volumes etc to create your Docker stack. If you also additionally have a file named docker-compose.override.yml this will be read as well and used as an override file to complement. It works in the following order:

All definitions from docker-compose.yml will be used
All definitions that are also defined in docker-compose.override.yml will automatically overwrite the settings from docker-compose.yml
All definitions only available in docker-compose.override.yml will be added additionally.

For starting up your Docker Compose stack there are no additional steps or command line arguments required. If both files exist, they will be read automatically.

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:

vhost-gen: Virtual host templates
vhost-gen: Customize all virtual hosts globally
vhost-gen: Customize specific virtual host
vhost-gen: Example: add sub domains

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.

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

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:

vhost-gen: Virtual host templates
vhost-gen: Customize all virtual hosts globally
vhost-gen: Customize specific virtual host
vhost-gen: Example: add sub domains

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.

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

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.2/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-ini-5.3/
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/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-ini-7.3/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-ini-7.4/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-ini-8.0/

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 contains two example files: devilbox-php.ini-default and devilbox-php.ini-xdebug.

devilbox-php.ini-default

This file holds the exact settings that are currently in place by each PHP-FPM container. Copy it (do not simply rename it) to a different file ending by .ini and start adjusting it.

devilbox-php.ini-xdebug

This file holds some sane example configuration to get you started with Xdebug. Copy it (do not simply rename it) to a different file ending by .ini and start adjusting it.

Important

For Xdebug to work, there are other changes requires as well: Configure PHP Xdebug

How to apply the settings

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.

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

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.2/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-fpm-5.3/
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/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-fpm-7.3/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-fpm-7.4/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 php-fpm-8.0/

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 contains three example file: devilbox-fpm.conf-default, devilbox-fpm.conf-pm_dynamic and devilbox-fpm.conf-pm_ondemand.

devilbox-fpm.conf-default

This file holds the exact settings that are currently in place by each PHP-FPM container. Copy it (do not simply rename it) to a different file ending by .conf and start adjusting it.

devilbox-fpm.conf-pm_dynamic

This file holds some sane example configuration to switch PHP-FPM scheduler to dynamic (The default is ondemand). Copy it (do not simply rename it) to a different file ending by .conf and start adjusting it.

devilbox-fpm.conf-pm_ondemand

This file holds the current default values for the PHP-FPM scheduler which is using ondemand. Copy it (do not simply rename it) to a different file ending by .conf and start adjusting it.

How to apply the settings

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.

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

my.cnf¶

my.ini changes are global to all projects, but will only affect the currently selected MySQL version.

Important

When using Docker Toolbox and the Devilbox 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-5.5/
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 mariadb-10.4/
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/
drwxr-xr-x  2 cytopia cytopia 4096 Mar  5 21:53 percona-8.0/

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.

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

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

Official CakePHP Documentation

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.

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup CakePHP¶

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

Important

Using composer requires the underlying file system to support symlinks. If you use Docker Toolbox you need to explicitly allow/enable this. See below for instructions:

Docker Toolbox and Symlinks

After completing the below listed steps, you will have a working CakePHP setup ready to be served via http and https.

See also

Table of Contents

Overview
Walk through
Next steps

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 https://my-cake.loc

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

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

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

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

See also

Official CodeIgniter Documentation

3. Install CakePHP ¶

Navigate into your newly created vhost directory and install CakePHP with composer.

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

How does the directory structure look after installation:

devilbox@php-7.0.20 in /shared/httpd/my-cake $ tree -L 1
.
└── cakephp

1 directory, 0 files

4. Symlink webroot ¶

Symlinking the actual webroot directory to htdocs is important. The web server expects every project’s document root to be in <vhost dir>/htdocs/. This is the path where it will serve the files. This is also the path where your frameworks entrypoint (usually index.php) should be found.

Some frameworks however provide its actual content in nested directories of unknown levels. This would be impossible to figure out by the web server, so you manually have to symlink it back to its expected path.

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

How does the directory structure look after symlinking:

devilbox@php-7.0.20 in /shared/httpd/my-cake $ tree -L 1
.
├── cakephp
└── htdocs -> cakephp/webroot

2 directories, 0 files

As you can see from the above directory structure, htdocs is available in its expected path and points to the frameworks entrypoint.

Important

When using Docker Toolbox, you need to explicitly allow the usage of symlinks. See below for instructions:

Docker Toolbox and Symlinks

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 have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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

8. Open your browser ¶

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

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup CodeIgniter¶

This example will use wget to install CodeIgniter from within the Devilbox PHP container.

After completing the below listed steps, you will have a working CodeIgniter setup ready to be served via http and https.

See also

Table of Contents

Overview
Walk through
Next steps

Overview ¶

The following configuration will be used:

Project name	VirtualHost directory	Database	TLD_SUFFIX	Project URL
my-ci	/shared/httpd/my-ci	my_ci	loc	http://my-ci.loc https://my-ci.loc

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

Walk through ¶

It will be ready in eight simple steps:

Enter the PHP container
Create a new VirtualHost directory
Download CodeIgniter
Symlink webroot directory
Add MySQL database
Configure datbase connection
Setup DNS record
Visit http://my-ci.loc in your browser

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

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

See also

3. Download CodeIgniter ¶

Navigate into your newly created vhost directory and install CodeIgniter.

devilbox@php-7.0.20 in /shared/httpd $ cd my-ci
devilbox@php-7.0.20 in /shared/httpd/my-ci $ wget https://github.com/bcit-ci/CodeIgniter/archive/3.1.8.tar.gz
devilbox@php-7.0.20 in /shared/httpd/my-ci $ tar xfvz 3.1.8.tar.gz

How does the directory structure look after installation:

devilbox@php-7.0.20 in /shared/httpd/my-ci $ tree -L 1
.
├── 3.1.8.tar.gz
└── CodeIgniter-3.1.8

1 directory, 1 file

4. Symlink webroot ¶

Symlinking the actual webroot directory to htdocs is important. The web server expects every project’s document root to be in <vhost dir>/htdocs/. This is the path where it will serve the files. This is also the path where your frameworks entrypoint (usually index.php) should be found.

Some frameworks however provide its actual content in nested directories of unknown levels. This would be impossible to figure out by the web server, so you manually have to symlink it back to its expected path.

devilbox@php-7.0.20 in /shared/httpd/my-ci $ ln -s CodeIgniter-3.1.8/ htdocs

How does the directory structure look after symlinking:

devilbox@php-7.0.20 in /shared/httpd/my-ci $ tree -L 1
.
├── 3.1.8.tar.gz
├── CodeIgniter-3.1.8
└── htdocs -> CodeIgniter-3.1.8

2 directories, 1 file

As you can see from the above directory structure, htdocs is available in its expected path and points to the frameworks entrypoint.

Important

When using Docker Toolbox, you need to explicitly allow the usage of symlinks. See below for instructions:

Docker Toolbox and Symlinks

5. Add MySQL Database ¶

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

6. Configure database connection ¶

devilbox@php-7.0.20 in /shared/httpd/my-ci $ vi htdocs/application/config/database.php

htdocs/application/config/database.php¶

<?php
$db['default'] = array(
        'dsn'   => '',
        'hostname' => '127.0.0.1',
        'username' => 'root',
        'password' => '',
        'database' => 'my_ci',
        'dbdriver' => 'mysqli',
        'dbprefix' => '',
        'pconnect' => FALSE,
        'db_debug' => (ENVIRONMENT !== 'production'),
        'cache_on' => FALSE,
        'cachedir' => '',
        'char_set' => 'utf8',
        'dbcollat' => 'utf8_general_ci',
        'swap_pre' => '',
        'encrypt' => FALSE,
        'compress' => FALSE,
        'stricton' => FALSE,
        'failover' => array(),
        'save_queries' => TRUE
);

7. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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-ci.loc

See also

8. Open your browser ¶

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

See also

Official CodeIgniter Documentation

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup CodeIgniter4¶

After completing the below listed steps, you will have a working CodeIgniter setup ready to be served via http and https.

See also

Table of Contents

Overview
Walk through
Next steps

Overview ¶

The following configuration will be used:

Project name	VirtualHost directory	Database	TLD_SUFFIX	Project URL
my-ci	/shared/httpd/my-ci	my_ci	loc	http://my-ci.loc https://my-ci.loc

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

Walk through ¶

It will be ready in eight simple steps:

Enter the PHP container
Create a new VirtualHost directory
Download CodeIgniter
Symlink webroot directory
Add MySQL database
Configure datbase connection
Setup DNS record
Visit http://my-ci.loc in your browser

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

devilbox@php-8.1.6 in /shared/httpd $ mkdir my-ci

See also

3. Download CodeIgniter ¶

Navigate into your newly created vhost directory and install CodeIgniter.

devilbox@php-8.1.6 in /shared/httpd $ cd my-ci
devilbox@php-8.1.6 in /shared/httpd/my-ci $ composer create-project codeigniter4/appstarter ci4app

How does the directory structure look after installation:

devilbox@php-8.1.6 in /shared/httpd/my-ci $ tree -L 1
.
└── ci4app

1 directory, 0 files

4. Symlink webroot ¶

Symlinking the actual webroot directory to htdocs is important. The web server expects every project’s document root to be in <vhost dir>/htdocs/. This is the path where it will serve the files. This is also the path where your frameworks entrypoint (usually index.php) should be found.

Some frameworks however provide its actual content in nested directories of unknown levels. This would be impossible to figure out by the web server, so you manually have to symlink it back to its expected path.

devilbox@php-8.1.6 in /shared/httpd/my-ci $ ln -s ci4app/public htdocs

How does the directory structure look after symlinking:

devilbox@php-8.1.6 in /shared/httpd/my-ci $ tree -L 1
.
├── ci4app
└── htdocs -> ci4app/public

2 directories, 0 files

As you can see from the above directory structure, htdocs is available in its expected path and points to the frameworks entrypoint.

Important

When using Docker Toolbox, you need to explicitly allow the usage of symlinks. See below for instructions:

Docker Toolbox and Symlinks

5. Add MySQL Database ¶

devilbox@php-8.1.6 in /shared/httpd/my-ci $ mysql -u root -h 127.0.0.1 -p -e 'CREATE DATABASE my_ci;'

6. Configure database connection ¶

devilbox@php-8.1.6 in /shared/httpd/my-ci $ vi htdocs/app/Config/Database.php

htdocs/app/Config/Database.php¶

<?php
     public $default = [
         'DSN'      => '',
         'hostname' => '127.0.0.1',
         'username' => 'root',
         'password' => '',
         'database' => 'my_ci',
         'DBDriver' => 'MySQLi',
         'DBPrefix' => '',
         'pConnect' => false,
         'DBDebug'  => (ENVIRONMENT !== 'production'),
         'charset'  => 'utf8',
         'DBCollat' => 'utf8_general_ci',
         'swapPre'  => '',
         'encrypt'  => false,
         'compress' => false,
         'strictOn' => false,
         'failover' => [],
         'port'     => 3306,
     ];

7. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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-ci.loc

See also

8. Open your browser ¶

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

See also

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup Contao¶

Important

You can find a more up-to-date version in the official Contao Documentation: Official Contao Devilbox Documentation

This example will use composer to install Contao CMS from within the Devilbox PHP container.

Important

Using composer requires the underlying file system to support symlinks. If you use Docker Toolbox you need to explicitly allow/enable this. See below for instructions:

Docker Toolbox and Symlinks

After completing the below listed steps, you will have a working Contao CMS setup ready to be served via http and https.

See also

Table of Contents

Overview ¶

The following configuration will be used:

Project name	VirtualHost directory	Database	TLD_SUFFIX	Project URL
my-contao	/shared/httpd/my-contao	my_contao	loc	http://my-contao.loc https://my-contao.loc

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

The following Devilbox configuration is required:

Service	Version	Implications
Webserver	Apache 2.4	Apache is required instead of Nginx as Contao provides default `.htaccess` files for routing
PHP	PHP-FPM 7.2	Chosen for this example as it is the Devilbox default version
Database	MariaDB 10.3	Chosen for this example as it is the Devilbox default version

Note

If you want to use Nginx instead, you will need to adjust the vhost congfiguration accordingly to Contao CMS requirements.

Walk through ¶

It will be ready in eight simple steps:

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

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

devilbox@php-7.2.15 in /shared/httpd $ mkdir my-contao

See also

Official CraftCMS Documentation

3. Install Contao ¶

Navigate into your newly created vhost directory and install Contao with composer.

devilbox@php-7.2.15 in /shared/httpd $ cd my-contao
devilbox@php-7.2.15 in /shared/httpd/my-contao $ composer create-project contao/managed-edition contao

How does the directory structure look after installation:

devilbox@php-7.2.15 in /shared/httpd/my-contao $ tree -L 1
.
└── contao

1 directory, 0 files

4. Symlink web ¶

Symlinking the actual webroot directory to htdocs is important. The web server expects every project’s document root to be in <vhost dir>/htdocs/. This is the path where it will serve the files. This is also the path where your frameworks entrypoint (usually index.php) should be found.

Some frameworks however provide its actual content in nested directories of unknown levels. This would be impossible to figure out by the web server, so you manually have to symlink it back to its expected path.

devilbox@php-7.2.15 in /shared/httpd/my-contao $ ln -s contao/web/ htdocs

How does the directory structure look after symlinking:

devilbox@php-7.2.15 in /shared/httpd/my-contao $ tree -L 1
.
├── contao
└── htdocs -> contao/web

2 directories, 0 files

As you can see from the above directory structure, htdocs is available in its expected path and points to the frameworks entrypoint.

Important

When using Docker Toolbox, you need to explicitly allow the usage of symlinks. See below for instructions:

Docker Toolbox and Symlinks

5. Add MySQL Database ¶

devilbox@php-7.2.15 in /shared/httpd/my-contao $ mysql -u root -h mysql -p -e 'CREATE DATABASE my_contao;'

6. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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-contao.loc

See also

7. Open your browser ¶

Open your browser at http://my-contao.loc or https://my-contao.loc and follow the installation steps.

7.1 Frontend page ¶

Contao installation: Installation incomplete note

Follow the presented instructions and go to:
- either http://my-contao.loc/contao/install
- or https://my-contao.loc/contao/install

7.2 Accept license ¶

Accept the license by clicking on Accept license

Contao installation: Accept license

7.3 Set install tool password ¶

Set a password for the install tool itself

Contao installation: Set install tool password

7.4 Database setup ¶

Database host: mysql
Database port: 3306
Database user: root
Database pass: empty (if not otherwise set during Devilbox configuration)

Contao installation: Database setup

7.5 Update database ¶

Click on update database to populate the database.

Contao installation: Update database

7.6 Set admin user ¶

The admin user is required to setup Contao itself and to gain access to the backend.

Contao installation: Create admin user

7.7 Finished ¶

Installation is done, click on the Contao back end to continue to setup the CMS itself.

Contao installation: Installation successfully finished

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup CraftCMS¶

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

Important

Using composer requires the underlying file system to support symlinks. If you use Docker Toolbox you need to explicitly allow/enable this. See below for instructions:

Docker Toolbox and Symlinks

After completing the below listed steps, you will have a working CraftCMS setup ready to be served via http and https.

See also

Table of Contents

Overview
Walk through
Next steps

Overview ¶

The following configuration will be used:

Project name	VirtualHost directory	Database	TLD_SUFFIX	Project URL
my-craft	/shared/httpd/my-craft	my_craft	loc	http://my-craft.loc https://my-craft.loc

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

Walk through ¶

It will be ready in eight simple steps:

Enter the PHP container
Create a new VirtualHost directory
Install CraftCMS via composer
Symlink webroot directory
Add MySQL database
Setup DNS record
Run setup wizard
Visit http://my-craft.loc in your browser

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

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

See also

Official CraftCMS Documentation

3. Install CraftCMS ¶

Navigate into your newly created vhost directory and install CraftCMS with composer.

devilbox@php-7.0.20 in /shared/httpd $ cd my-craft
devilbox@php-7.0.20 in /shared/httpd/my-craft $ composer create-project craftcms/craft craftcms

How does the directory structure look after installation:

devilbox@php-7.0.20 in /shared/httpd/my-craft $ tree -L 1
.
└── craftcms

1 directory, 0 files

4. Symlink webroot ¶

Symlinking the actual webroot directory to htdocs is important. The web server expects every project’s document root to be in <vhost dir>/htdocs/. This is the path where it will serve the files. This is also the path where your frameworks entrypoint (usually index.php) should be found.

Some frameworks however provide its actual content in nested directories of unknown levels. This would be impossible to figure out by the web server, so you manually have to symlink it back to its expected path.

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

How does the directory structure look after symlinking:

devilbox@php-7.0.20 in /shared/httpd/my-craft $ tree -L 1
.
├── craftcms
└── htdocs -> craftcms/web

2 directories, 0 files

As you can see from the above directory structure, htdocs is available in its expected path and points to the frameworks entrypoint.

Important

When using Docker Toolbox, you need to explicitly allow the usage of symlinks. See below for instructions:

Docker Toolbox and Symlinks

5. Add MySQL Database ¶

devilbox@php-7.0.20 in /shared/httpd/my-craft $ mysql -u root -h 127.0.0.1 -p -e 'CREATE DATABASE my_craft CHARACTER SET utf8 COLLATE utf8_unicode_ci;'

6. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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-craft.loc

See also

7. Run setup wizard ¶

After everything is setup, you need to run the setup wizard. CraftCMS bundles a commandline tool that you can use.

7.1 Via command line tool ¶

devilbox@php-7.0.20 in /shared/httpd/my-craft $ php craftcms/craft setup

Which database driver are you using? [mysql,pgsql,?]: mysql
Database server name or IP address: [localhost] 127.0.0.1
Database port: [3306]
Database username: [root]
Database password:
Database name: my_craft
Database table prefix:
Testing database credentials... success!
Saving database credentials to your .env file... done

Install Craft now? (yes|no) [yes]:

Username: [admin]
Email: admin@devilbox.org
Password:
Confirm:
Site name: craftcms
Site URL: [@web] my-craft.loc
Site language: [en-US]

...

*** installed Craft successfully (time: 14.660s)

7.2 Via browser ¶

If you do not feel too comfortable on the command line, you can also run the setup wizard via the browser. See their official documentation for screenshots.

See also

To open the setup wizard, visit: http://my-craft.loc/admin/install or https://my-craft.loc/admin/install

Driver: MySQL
Server: 127.0.0.1
Port: 3306
Username: root
Password: your MySQL password
Database Name: my_craft
Prefix: leave empty

Important

When chosing the Database server, use 127.0.0.1 as the hostname.

8. Open your browser ¶

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

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup Drupal¶

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

After completing the below listed steps, you will have a working Drupal setup ready to be served via http and https.

See also

Official Drupal Documentation

Table of Contents

Overview
Walk through
Next steps

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 https://my-drupal.loc

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

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

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

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

See also

Official ExpressionEngine Documentation

3. Install Drupal ¶

Navigate into your newly created vhost directory and install Drupal with drush.

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

How does the directory structure look after installation:

devilbox@php-7.0.20 in /shared/httpd/my-drupal $ tree -L 1
.
└── drupal-8.3.3

1 directory, 0 files

4. Symlink webroot ¶

Symlinking the actual webroot directory to htdocs is important. The web server expects every project’s document root to be in <vhost dir>/htdocs/. This is the path where it will serve the files. This is also the path where your frameworks entrypoint (usually index.php) should be found.

Some frameworks however provide its actual content in nested directories of unknown levels. This would be impossible to figure out by the web server, so you manually have to symlink it back to its expected path.

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

How does the directory structure look after symlinking:

devilbox@php-7.0.20 in /shared/httpd/my-drupal $ tree -L 1
.
├── drupal-8.3.3
└── htdocs -> CodeIgniter-3.1.8

2 directories, 0 fils

As you can see from the above directory structure, htdocs is available in its expected path and points to the frameworks entrypoint.

Important

When using Docker Toolbox, you need to explicitly allow the usage of symlinks. See below for instructions:

Docker Toolbox and Symlinks

5. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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

6. Open your browser ¶

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

Note

When asked about MySQL hostname, choose 127.0.0.1.

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup ExpressionEngine¶

This example will use curl to install ExpressionEngine from within the Devilbox PHP container.

After completing the below listed steps, you will have a working ExpressionEngine setup ready to be served via http and https.

See also

Table of Contents

Overview
Walk through
Next steps

Overview ¶

The following configuration will be used:

Project name	VirtualHost directory	Database	TLD_SUFFIX	Project URL
my-ee	/shared/httpd/my-ee	my_ee	loc	http://my-ee.loc https://my-ee.loc

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

Walk through ¶

It will be ready in eight simple steps:

Enter the PHP container
Create a new VirtualHost directory
Download and extract ExpressionEngine
Symlink webroot directory
Add MySQL Database
Setup DNS record
Install ExpressionEngine
View your site

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

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

See also

Official Joomla Documentation

3. Download and extract ExpressionEngine ¶

Navigate into your newly created vhost directory and install ExpressionEngine.

devilbox@php-7.0.20 in /shared/httpd $ cd my-ee
devilbox@php-7.0.20 in /shared/httpd/my-ee $ curl 'https://expressionengine.com/?ACT=243' -H 'Referer: https://expressionengine.com/' --compressed -o ee.zip
devilbox@php-7.0.20 in /shared/httpd/my-ee $ mkdir ee
devilbox@php-7.0.20 in /shared/httpd/my-ee $ unzip ee.zip -d ee

How does the directory structure look after installation:

devilbox@php-7.0.20 in /shared/httpd/my-ee $ tree -L 1
.
├── ee
└── ee.zip

1 directory, 1 file

4. Symlink webroot ¶

Symlinking the actual webroot directory to htdocs is important. The web server expects every project’s document root to be in <vhost dir>/htdocs/. This is the path where it will serve the files. This is also the path where your frameworks entrypoint (usually index.php) should be found.

Some frameworks however provide its actual content in nested directories of unknown levels. This would be impossible to figure out by the web server, so you manually have to symlink it back to its expected path.

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

How does the directory structure look after symlinking it:

devilbox@php-7.0.20 in /shared/httpd/my-ee $ tree -L 1
.
├── ee
├── ee.zip
└── htdocs -> ee

2 directories, 1 file

As you can see from the above directory structure, htdocs is available in its expected path and points to the frameworks entrypoint.

Important

When using Docker Toolbox, you need to explicitly allow the usage of symlinks. See below for instructions:

Docker Toolbox and Symlinks

5. Add MySQL Database ¶

devilbox@php-7.0.20 in /shared/httpd/my-ee $ mysql -u root -h 127.0.0.1 -p -e 'CREATE DATABASE my_ee CHARACTER SET utf8 COLLATE utf8_unicode_ci;'

Note

Remember the database name you create here. It will be needed again during the installation process.

6. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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-ee.loc

See also

7. Install ExpressionEngine ¶

Point your browser to http://my-ee.loc/admin.php or https://my-ee.loc/admin.php and follow the on-screen instructions to install ExpressionEngine.

Important

Once the Installation Wizard is finished, you should rename or remove the system/ee/installer/ directory from your install directory if it was not done by the install wizard.

8. View Your Site ¶

All set now, you can visit your site’s homepage by opening http://my-ee.loc or https://my-ee.loc in your browser.

Your control panel will also be available by opening http://my-ee.loc/admin.php or https://my-ee.loc/admin.php in your browser.

Note

If you chose not to install the default theme, your site’s homepage will appear blank because no templates or content has been created yet.
If you’re new to ExpressionEngine, get started with the 10 Minute Primer

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup Joomla¶

This example will use wget to install Joomla from within the Devilbox PHP container.

After completing the below listed steps, you will have a working Joomla setup ready to be served via http and https.

See also

Table of Contents

Overview
Walk through
Next steps

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 https://my-joomla.loc

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

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

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

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

See also

Official Laravel Documentation

3. Download and extract Joomla ¶

Navigate into your newly created vhost directory and install 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/my-joomla $ mkdir joomla
devilbox@php-7.0.20 in /shared/httpd/my-joomla $ tar xvfz joomla.tar.gz -C joomla/

How does the directory structure look after installation:

devilbox@php-7.0.20 in /shared/httpd/my-joomla $ tree -L 1
.
├── joomla.tar.gz
└── joomla

1 directory, 1 file

4. Symlink webroot ¶

Symlinking the actual webroot directory to htdocs is important. The web server expects every project’s document root to be in <vhost dir>/htdocs/. This is the path where it will serve the files. This is also the path where your frameworks entrypoint (usually index.php) should be found.

Some frameworks however provide its actual content in nested directories of unknown levels. This would be impossible to figure out by the web server, so you manually have to symlink it back to its expected path.

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

How does the directory structure look after symlinking it:

devilbox@php-7.0.20 in /shared/httpd/my-joomla $ tree -L 1
.
├── joomla.tar.gz
├── joomla
└── htdocs -> joomla

2 directories, 1 file

As you can see from the above directory structure, htdocs is available in its expected path and points to the frameworks entrypoint.

Important

When using Docker Toolbox, you need to explicitly allow the usage of symlinks. See below for instructions:

Docker Toolbox and Symlinks

5. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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

6. Open your browser ¶

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

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup Laravel¶

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

After completing the below listed steps, you will have a working Laravel setup ready to be served via http and https.

See also

Table of Contents

Overview
Walk through
Next steps

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 https://my-laravel.loc

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

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

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

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

See also

Official Magento 2 Documentation

3. Install Laravel ¶

Navigate into your newly created vhost directory and install Laravel with laravel cli.

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

How does the directory structure look after installation:

devilbox@php-7.0.20 in /shared/httpd/my-laravel $ tree -L 1
.
└── laravel-project

1 directory, 0 files

4. Symlink webroot ¶

Symlinking the actual webroot directory to htdocs is important. The web server expects every project’s document root to be in <vhost dir>/htdocs/. This is the path where it will serve the files. This is also the path where your frameworks entrypoint (usually index.php) should be found.

Some frameworks however provide its actual content in nested directories of unknown levels. This would be impossible to figure out by the web server, so you manually have to symlink it back to its expected path.

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

How does the directory structure look after symlinking:

devilbox@php-7.0.20 in /shared/httpd/my-laravel $ tree -L 1
.
├── laravel-project
└── htdocs -> laravel-project/public

2 directories, 0 files

As you can see from the above directory structure, htdocs is available in its expected path and points to the frameworks entrypoint.

Important

When using Docker Toolbox, you need to explicitly allow the usage of symlinks. See below for instructions:

Docker Toolbox and Symlinks

5. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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

This will ensure that your host operating system’s browser will direct any calls on http://my-laravel.loc or https://my-laravel.loc to the Devilbox which is listening on 127.0.0.1.

See also

6. Open your browser ¶

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

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup Magento 2¶

This example will use git and composer to install Magento 2 from within the Devilbox PHP container.

Important

Using composer requires the underlying file system to support symlinks. If you use Docker Toolbox you need to explicitly allow/enable this. See below for instructions:

Docker Toolbox and Symlinks

After completing the below listed steps, you will have a working Magento 2 setup ready to be served via http and https.

See also

Table of Contents

Overview
Requirements
Walk through
Next steps

Overview ¶

The following configuration will be used:

Project name	VirtualHost directory	Database	TLD_SUFFIX	Project URL
my-magento	/shared/httpd/my-magento	my_magento	loc	http://my-magento.loc https://my-magento.loc

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

Requirements ¶

This example requires to use Apache 2.4, as Magento does a lot of .htaccess magic by default and these files are not interpreted by Nginx.

If you still want to use Nginx instead, you will have to overwrite your vhost configuration to ensure the .htaccess rules are glued into your Nginx vhost configuration.

See also

Walk through ¶

It will be ready in eight simple steps:

Enter the PHP container
Create a new VirtualHost directory
Install Magento 2 via git and composer
Symlink webroot directory
Add MySQL database
Setup DNS record
Visit http://my-magento.loc in your browser

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

devilbox@php-7.1.20 in /shared/httpd $ mkdir my-magento

See also

Official Phalcon Documentation

3. Install Magento 2 ¶

Navigate into your newly created vhost directory and install Magento 2 with git.

devilbox@php-7.1.20 in /shared/httpd $ cd my-magento

# Download Magento 2 via git
devilbox@php-7.1.20 in /shared/httpd/my-magento $ git clone https://github.com/magento/magento2

# Checkout the latest stable git tag
devilbox@php-7.1.20 in /shared/httpd/my-magento $ cd magento2
devilbox@php-7.1.20 in /shared/httpd/my-magento/magento2 $ git checkout 2.2.5

# Install dependencies with Composer
devilbox@php-7.1.20 in /shared/httpd/my-magento/magento2 $ composer install

How does the directory structure look after installation:

devilbox@php-7.1.20 in /shared/httpd/my-magento $ tree -L 1
.
└── magento2

1 directory, 0 files

4. Symlink webroot ¶

Symlinking the actual webroot directory to htdocs is important. The web server expects every project’s document root to be in <vhost dir>/htdocs/. This is the path where it will serve the files. This is also the path where your frameworks entrypoint (usually index.php) should be found.

Some frameworks however provide its actual content in nested directories of unknown levels. This would be impossible to figure out by the web server, so you manually have to symlink it back to its expected path.

devilbox@php-7.1.20 in /shared/httpd/my-magento $ ln -s magento2/ htdocs

How does the directory structure look after symlinking:

devilbox@php-7.1.20 in /shared/httpd/my-magento $ tree -L 1
.
├── magento2
└── htdocs -> magento2

2 directories, 0 files

As you can see from the above directory structure, htdocs is available in its expected path and points to the frameworks entrypoint.

Important

When using Docker Toolbox, you need to explicitly allow the usage of symlinks. See below for instructions:

Docker Toolbox and Symlinks

5. Add MySQL Database ¶

devilbox@php-7.1.20 in /shared/httpd/my-magento $ mysql -u root -h 127.0.0.1 -p -e 'CREATE DATABASE my_magento;'

7. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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-magento.loc

See also

8. Open your browser ¶

All set now, you can visit http://my-magento.loc or https://my-magento.loc in your browser and follow the installation steps.

Important

Use 127.0.0.1 for the MySQL database hostname.

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup Phalcon¶

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

After completing the below listed steps, you will have a working Phalcon setup ready to be served via http and https.

See also

Table of Contents

Overview
Walk through
Next steps

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 https://my-phalcon.loc

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

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
(Nginx) Create custom vhost config file

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

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

See also

Official Photon CMS Documentation

3. Install Phalcon ¶

Navigate into your newly created vhost directory and install Phalcon with phalcon cli.

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

How does the directory structure look after installation:

devilbox@php-7.0.20 in /shared/httpd/my-phalcon $ tree -L 1
.
└── phalconphp

1 directory, 0 files

4. Symlink webroot ¶

Symlinking the actual webroot directory to htdocs is important. The web server expects every project’s document root to be in <vhost dir>/htdocs/. This is the path where it will serve the files. This is also the path where your frameworks entrypoint (usually index.php) should be found.

Some frameworks however provide its actual content in nested directories of unknown levels. This would be impossible to figure out by the web server, so you manually have to symlink it back to its expected path.

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

How does the directory structure look after symlinking:

devilbox@php-7.0.20 in /shared/httpd/my-phalcon $ tree -L 1
.
├── phalconphp
└── htdocs -> phalconphp/public

2 directories, 0 files

As you can see from the above directory structure, htdocs is available in its expected path and points to the frameworks entrypoint.

Important

When using Docker Toolbox, you need to explicitly allow the usage of symlinks. See below for instructions:

Docker Toolbox and Symlinks

5. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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

6. Open your browser ¶

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

7. Create custom vhost config file (Nginx Only)¶

By default routes will not work if using Nginx. To fix this, you will need to create a custom vhost configuration.

In your project folder, you will need to create a folder called .devilbox unless you changed HTTPD_TEMPLATE_DIR in your .env

Copy the default nginx config from ./cfg/vhost-gen/nginx.yml-example-vhost to ./data/www/my-project/.devilbox/nginx.yml

Carefully edit the nginx.yml file and change:

try_files $uri $uri/ /index.php$is_args$args; to try_files $uri $uri/ /index.php?_url=$uri&$args;

and

location ~ \.php?$ { to location ~ [^/]\.php(/|$) {

save the file as nginx.yml and ensure not to use any tabs in the file or devilbox will not use the custom configuration. You can use yamllint nginx.yml whilst inside the Devilbox shell to check the file before restarting devilbox.

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup Photon CMS¶

This example will use photon cli to install Photon CMS from within the Devilbox PHP container.

After completing the below listed steps, you will have a working Photon CMS setup ready to be served via http and https.

See also

Table of Contents

Overview
Walk through
Next steps

Overview ¶

The following configuration will be used:

Project name	VirtualHost directory	Database	TLD_SUFFIX	Project URL
my-photon	/shared/httpd/my-photon	blog	loc	http://my-photon.loc https://my-photon.loc

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

Walk through ¶

It will be ready in six simple steps:

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

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

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

See also

Official PrestaShop Documentation

3. Install Photon ¶

Navigate into your newly created vhost directory and install Photom CMS with photon cli.

Note

During the installation you will be asked for the MySQL hostname, username and password. Ensure not to specify localhost, but instead use 127.0.0.1 for the hostname. Additionally, provide a pair of credentials that has permissions to create a database or create the database itself beforehand.

devilbox@php-7.0.20 in /shared/httpd $ cd my-photon
devilbox@php-7.0.20 in /shared/httpd/my-photon $ photon new blog
...What is your mysql hostname? [localhost]  127.0.0.1
...What is your mysql username? [root]root
...What is your mysql password? []

How does the directory structure look after installation:

devilbox@php-7.0.20 in /shared/httpd/my-photon $ tree -L 1
.
└── blog

1 directory, 0 files

4. Symlink webroot ¶

Symlinking the actual webroot directory to htdocs is important. The web server expects every project’s document root to be in <vhost dir>/htdocs/. This is the path where it will serve the files. This is also the path where your frameworks entrypoint (usually index.php) should be found.

Some frameworks however provide its actual content in nested directories of unknown levels. This would be impossible to figure out by the web server, so you manually have to symlink it back to its expected path.

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

How does the directory structure look after symlinking:

devilbox@php-7.0.20 in /shared/httpd/my-photon $ tree -L 1
.
├── blog
└── htdocs -> blog/public

2 directories, 0 files

As you can see from the above directory structure, htdocs is available in its expected path and points to the frameworks entrypoint.

Important

When using Docker Toolbox, you need to explicitly allow the usage of symlinks. See below for instructions:

Docker Toolbox and Symlinks

5. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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-photon.loc

See also

6. Open your browser ¶

Open your browser at http://my-photon.loc or https://my-photon.loc

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup PrestaShop¶

This example will use git and composer to install PrestaShop from within the Devilbox PHP container.

Important

Using composer requires the underlying file system to support symlinks. If you use Docker Toolbox you need to explicitly allow/enable this. See below for instructions:

Docker Toolbox and Symlinks

After completing the below listed steps, you will have a working PrestaShop setup ready to be served via http and https.

See also

Table of Contents

Overview
Walk through
Next steps

Overview ¶

The following configuration will be used:

Project name	VirtualHost directory	Database	TLD_SUFFIX	Project URL
my-presta	/shared/httpd/my-presta	my_presta	loc	http://my-presta.loc https://my-presta.loc

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

Walk through ¶

It will be ready in eight simple steps:

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

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

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

See also

Official ProcessWire Documentation

3. Install PrestaShop ¶

Navigate into your newly created vhost directory and install PrestaShop with git and composer.

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

# Download PrestaShop with git
devilbox@php-7.0.20 in /shared/httpd/my-presta $ git clone https://github.com/PrestaShop/PrestaShop

# Checkout the latest stable git tag
devilbox@php-7.0.20 in /shared/httpd/my-presta $ cd PrestaShop
devilbox@php-7.0.20 in /shared/httpd/my-presta $ git checkout 1.7.4.2

# Install dependencies with Composer
devilbox@php-7.0.20 in /shared/httpd/my-presta $ composer install

How does the directory structure look after installation:

devilbox@php-7.0.20 in /shared/httpd/my-presta $ tree -L 1
.
└── PrestaShop

1 directory, 0 files

4. Symlink webroot ¶

Symlinking the actual webroot directory to htdocs is important. The web server expects every project’s document root to be in <vhost dir>/htdocs/. This is the path where it will serve the files. This is also the path where your frameworks entrypoint (usually index.php) should be found.

Some frameworks however provide its actual content in nested directories of unknown levels. This would be impossible to figure out by the web server, so you manually have to symlink it back to its expected path.

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

How does the directory structure look after symlinking:

devilbox@php-7.0.20 in /shared/httpd/my-presta $ tree -L 1
.
├── PrestaShop
└── htdocs -> PrestaShop

2 directories, 0 files

As you can see from the above directory structure, htdocs is available in its expected path and points to the frameworks entrypoint.

Important

When using Docker Toolbox, you need to explicitly allow the usage of symlinks. See below for instructions:

Docker Toolbox and Symlinks

5. Add MySQL Database ¶

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

6. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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-presta.loc

See also

7. Open your browser ¶

All set now, you can visit http://my-presta.loc or https://my-presta.loc in your browser and follow the installation steps.

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup ProcessWire¶

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

Important

Using composer requires the underlying file system to support symlinks. If you use Docker Toolbox you need to explicitly allow/enable this. See below for instructions:

Docker Toolbox and Symlinks

After completing the below listed steps, you will have a working ProcessWire setup ready to be served via http and https.

See also

Table of Contents

Overview
Walk through
Next steps

Overview ¶

The following configuration will be used:

Project name	VirtualHost directory	Database	TLD_SUFFIX	Project URL
my-pw	/shared/httpd/my-pw	my_pw	loc	http://my-pw.loc https://my-pw.loc

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

The following Devilbox configuration is required:

Service	Version	Implications
Webserver	Apache 2.4	Apache is required instead of Nginx as ProcessWire provides default `.htaccess` files for routing
PHP	PHP-FPM 7.2	Chosen for this example as it is the Devilbox default version
Database	MariaDB 10.3	Chosen for this example as it is the Devilbox default version

Note

If you want to use Nginx instead, you will need to adjust the vhost congfiguration accordingly to ProcessWire requirements.

Walk through ¶

It will be ready in eight simple steps:

Enter the PHP container
Create a new VirtualHost directory
Install ProcessWire via composer
Symlink webroot directory
Setup DNS record
Open your browser
Step through guided web installation

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

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

See also

3. Install ProcessWire ¶

Navigate into your newly created vhost directory and install ProcessWire with composer.

devilbox@php-7.0.20 in /shared/httpd $ cd my-pw
devilbox@php-7.0.20 in /shared/httpd/my-pw $ composer create-project processwire/processwire

How does the directory structure look after installation:

devilbox@php-7.0.20 in /shared/httpd/my-pw $ tree -L 1
.
└── processwire

1 directory, 0 files

4. Symlink webroot ¶

Symlinking the actual webroot directory to htdocs is important. The web server expects every project’s document root to be in <vhost dir>/htdocs/. This is the path where it will serve the files. This is also the path where your frameworks entrypoint (usually index.php) should be found.

Some frameworks however provide its actual content in nested directories of unknown levels. This would be impossible to figure out by the web server, so you manually have to symlink it back to its expected path.

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

How does the directory structure look after symlinking:

devilbox@php-7.0.20 in /shared/httpd/my-pw $ tree -L 1
.
├── processwire
└── htdocs -> processwire

2 directories, 0 files

As you can see from the above directory structure, htdocs is available in its expected path and points to the frameworks entrypoint.

Important

When using Docker Toolbox, you need to explicitly allow the usage of symlinks. See below for instructions:

Docker Toolbox and Symlinks

5. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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-pw.loc

See also

6. Open your browser ¶

Open your browser at http://my-pw.loc or https://my-pw.loc.

7. Step through guided web installation ¶

ProcessWire installation: Overview

ProcessWire installation: Profile Choice

ProcessWire installation: Choose Default Profile

ProcessWire installation: Compatibility Check

ProcessWire installation: General Setup

ProcessWire installation: Admin Setup

ProcessWire installation: Setup completed

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup Shopware¶

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

After completing the below listed steps, you will have a working Shopware setup ready to be served via http and https.

See also

Table of Contents

Overview
Walk through
Encountered problems
Next steps

Overview ¶

The following configuration will be used:

Project name	VirtualHost directory	Database	TLD_SUFFIX	Project URL
my-sw	/shared/httpd/my-sw	my_sw	loc	http://my-sw.loc https://my-sw.loc

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

Walk through ¶

It will be ready in seven simple steps:

Enter the PHP container
Create a new VirtualHost directory
Download Shopware via git
Symlink webroot directory
Add MySQL database
Setup DNS record
Follow installation steps in http://my-sw.loc in your browser

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

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

See also

Official Symfony Documentation

3. Download Shopware ¶

Navigate into your newly created vhost directory and install Shopware with git.

devilbox@php-7.0.20 in /shared/httpd $ cd my-sw
devilbox@php-7.0.20 in /shared/httpd/my-sw $ git clone https://github.com/shopware/shopware

How does the directory structure look after installation:

devilbox@php-7.0.20 in /shared/httpd/my-sw $ tree -L 1
.
└── shopware

1 directory, 0 files

4. Symlink webroot ¶

Symlinking the actual webroot directory to htdocs is important. The web server expects every project’s document root to be in <vhost dir>/htdocs/. This is the path where it will serve the files. This is also the path where your frameworks entrypoint (usually index.php) should be found.

Some frameworks however provide its actual content in nested directories of unknown levels. This would be impossible to figure out by the web server, so you manually have to symlink it back to its expected path.

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

How does the directory structure look after symlinking:

devilbox@php-7.0.20 in /shared/httpd/my-sw $ tree -L 1
.
├── shopware
└── htdocs -> shopware

2 directories, 0 files

As you can see from the above directory structure, htdocs is available in its expected path and points to the frameworks entrypoint.

Important

When using Docker Toolbox, you need to explicitly allow the usage of symlinks. See below for instructions:

Docker Toolbox and Symlinks

5. Add MySQL Database ¶

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

6. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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-sw.loc

See also

7. Follow install steps in your browser ¶

All set now, you can visit http://my-sw.loc or https://my-sw.loc in your browser and follow the installation steps as described in the Official Shopware Documentation :

Important

When setting up database connection use the following values:

Database server: 127.0.0.1
Database user: root (if you don’t have a dedicated user already)
Database pass: by default the root password is empty
Database name: my_sw

Encountered problems ¶

By the time of writing (2018-07-07) Shopware had loading issues with the combination of PHP 5.6 and Apache 2.4. Use any other combination.

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup Symfony¶

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

After completing the below listed steps, you will have a working Symfony setup ready to be served via http and https.

See also

Table of Contents

Overview
Walk through
Next steps

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 https://my-symfony.loc

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

Walk through ¶

It will be ready in six simple steps:

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

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

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

See also

Official Typo3 Documentation

3. Install Symfony ¶

Navigate into your newly created vhost directory and install Symfony with symfony cli.

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

How does the directory structure look after installation:

devilbox@php-7.2.29 in /shared/httpd/my-symfony $ tree -L 1
.
└── symfony

1 directory, 0 files

4. Symlink webroot ¶

Symlinking the actual webroot directory to htdocs is important. The web server expects every project’s document root to be in <vhost dir>/htdocs/. This is the path where it will serve the files. This is also the path where your frameworks entrypoint (usually index.php) should be found.

Some frameworks however provide its actual content in nested directories of unknown levels. This would be impossible to figure out by the web server, so you manually have to symlink it back to its expected path.

devilbox@php-7.2.29 in /shared/httpd/my-symfony $ ln -s symfony/public/ htdocs

How does the directory structure look after symlinking:

devilbox@php-7.2.29 in /shared/httpd/my-sw $ tree -L 1
.
├── symfony
└── htdocs -> symfony/public

2 directories, 0 files

As you can see from the above directory structure, htdocs is available in its expected path and points to the frameworks entrypoint.

Important

When using Docker Toolbox, you need to explicitly allow the usage of symlinks. See below for instructions:

Docker Toolbox and Symlinks

5. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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

6. Open your browser ¶

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

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup TYPO3¶

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

Important

Using composer requires the underlying file system to support symlinks. If you use Docker Toolbox you need to explicitly allow/enable this. See below for instructions:

Docker Toolbox and Symlinks

After completing the below listed steps, you will have a working TYPO3 setup ready to be served via http and https.

See also

Table of Contents

Overview
Walk through
Next steps

Overview ¶

The following configuration will be used:

Project name	VirtualHost directory	Database	TLD_SUFFIX	Project URL
my-typo	/shared/httpd/my-typo	my_typo	loc	http://my-typo.loc https://my-typo.loc

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

Walk through ¶

It will be ready in eight simple steps:

Enter the PHP container
Create a new VirtualHost directory
Install TYPO3 via composer
Symlink webroot directory
Setup DNS record
Create FIRST_INSTALL file
Open your browser
Step through guided web installation

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

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

See also

Official Wordpress Documentation

3. Install TYPO3 ¶

Navigate into your newly created vhost directory and install TYPO3 with composer.

devilbox@php-7.0.20 in /shared/httpd $ cd my-typo
devilbox@php-7.0.20 in /shared/httpd/my-typo $ composer create-project typo3/cms-base-distribution typo3

How does the directory structure look after installation:

devilbox@php-7.0.20 in /shared/httpd/my-typo $ tree -L 1
.
└── typo3

1 directory, 0 files

4. Symlink webroot ¶

Symlinking the actual webroot directory to htdocs is important. The web server expects every project’s document root to be in <vhost dir>/htdocs/. This is the path where it will serve the files. This is also the path where your frameworks entrypoint (usually index.php) should be found.

Some frameworks however provide its actual content in nested directories of unknown levels. This would be impossible to figure out by the web server, so you manually have to symlink it back to its expected path.

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

How does the directory structure look after symlinking:

devilbox@php-7.0.20 in /shared/httpd/my-typo $ tree -L 1
.
├── typo3
└── htdocs -> typo3/public

2 directories, 0 files

As you can see from the above directory structure, htdocs is available in its expected path and points to the frameworks entrypoint.

Important

When using Docker Toolbox, you need to explicitly allow the usage of symlinks. See below for instructions:

Docker Toolbox and Symlinks

5. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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-typo.loc

See also

6. Create `FIRST_INSTALL` file ¶

To continue installing via the guided web install, you need to create a file called FIRST_INSTALL in the document root.

devilbox@php-7.0.20 in /shared/httpd/my-typo $ touch htdocs/FIRST_INSTALL

7. Open your browser ¶

Open your browser at http://my-typo.loc or https://my-typo.loc.

8. Step through guided web installation ¶

Select database
- Connection: Manually configured MySWQL TCP/IP connection
- Username: root
- Password
- Host: mysql
- Port: 3306
Select database
- Create a new database: typo3
Create Administrative User / Specify Site Name
- Username: admin
- Password: choose a secure password
- Site name: My Typo
Installation complete
- Create empty starting page

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup WordPress¶

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

After completing the below listed steps, you will have a working WordPress setup ready to be served via http and https.

See also

Table of Contents

Overview
Walk through
Next steps

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 https://my-wp.loc

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

Walk through ¶

It will be ready in seven simple steps:

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

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

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

See also

Official Yii Documentation

3. Download WordPress via `git`¶

Navigate into your newly created vhost directory and install WordPress with 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

How does the directory structure look after installation:

devilbox@php-7.0.20 in /shared/httpd/my-wp $ tree -L 1
.
└── wordpress.git

1 directory, 0 files

4. Symlink webroot ¶

Symlinking the actual webroot directory to htdocs is important. The web server expects every project’s document root to be in <vhost dir>/htdocs/. This is the path where it will serve the files. This is also the path where your frameworks entrypoint (usually index.php) should be found.

Some frameworks however provide its actual content in nested directories of unknown levels. This would be impossible to figure out by the web server, so you manually have to symlink it back to its expected path.

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

How does the directory structure look after symlinking:

devilbox@php-7.0.20 in /shared/httpd/my-wp $ tree -L 1
.
├── wordpress.git
└── htdocs -> wordpress.git

2 directories, 0 files

As you can see from the above directory structure, htdocs is available in its expected path and points to the frameworks entrypoint.

Important

When using Docker Toolbox, you need to explicitly allow the usage of symlinks. See below for instructions:

Docker Toolbox and Symlinks

5. Add MySQL Database ¶

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

6. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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

7. Open your browser ¶

Open your browser at http://my-wp.loc or https://my-wp.loc and follow the installation steps.

(1/7) Choose your desired WordPress language

Wordpress installation: Choose language

(2/7) Read pre-installation information

Wordpress installation: Overview

(3/7) Setup database connection

Important

Choose 127.0.0.1 as the database host

Wordpress installation: Setup database

(4/7) Database setup post screen

Wordpress installation: Database setup finished

(5/7) Start WordPress installation

Wordpress installation: Installation

(6/7) Installation success view

Wordpress installation: Installation finished

(7/7) Login to Admin panel

Wordpress installation: Login

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup Yii¶

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

Important

Using composer requires the underlying file system to support symlinks. If you use Docker Toolbox you need to explicitly allow/enable this. See below for instructions:

Docker Toolbox and Symlinks

After completing the below listed steps, you will have a working Yii setup ready to be served via http and https.

See also

Table of Contents

Overview
Walk through
Next steps

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 https://my-yii.loc

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

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

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

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

See also

Official Zend Documentation

3. Install Yii2 via `composer`¶

Navigate into your newly created vhost directory and install Yii2 with 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

How does the directory structure look after installation:

devilbox@php-7.0.20 in /shared/httpd/my-yii $ tree -L 1
.
└── yii2-dev

1 directory, 0 files

4. Symlink webroot ¶

Symlinking the actual webroot directory to htdocs is important. The web server expects every project’s document root to be in <vhost dir>/htdocs/. This is the path where it will serve the files. This is also the path where your frameworks entrypoint (usually index.php) should be found.

Some frameworks however provide its actual content in nested directories of unknown levels. This would be impossible to figure out by the web server, so you manually have to symlink it back to its expected path.

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

How does the directory structure look after symlinking:

devilbox@php-7.0.20 in /shared/httpd/my-yii $ tree -L 1
.
├── yii2-dev
└── htdocs -> yii2-dev/web

2 directories, 0 files

As you can see from the above directory structure, htdocs is available in its expected path and points to the frameworks entrypoint.

Important

When using Docker Toolbox, you need to explicitly allow the usage of symlinks. See below for instructions:

Docker Toolbox and Symlinks

5. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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

6. Open your browser ¶

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

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup Zend¶

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

Important

Using composer requires the underlying file system to support symlinks. If you use Docker Toolbox you need to explicitly allow/enable this. See below for instructions:

Docker Toolbox and Symlinks

See also

Table of Contents

Overview
Walk through
Next steps

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 https://my-zend.loc

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

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

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

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

See also

3. Install Zend via `composer`¶

Navigate into your newly created vhost directory and install Zend with 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

How does the directory structure look after installation:

devilbox@php-7.0.20 in /shared/httpd/my-zend $ tree -L 1
.
└── zend

1 directory, 0 files

4. Symlink webroot ¶

Symlinking the actual webroot directory to htdocs is important. The web server expects every project’s document root to be in <vhost dir>/htdocs/. This is the path where it will serve the files. This is also the path where your frameworks entrypoint (usually index.php) should be found.

Some frameworks however provide its actual content in nested directories of unknown levels. This would be impossible to figure out by the web server, so you manually have to symlink it back to its expected path.

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

How does the directory structure look after symlinking:

devilbox@php-7.0.20 in /shared/httpd/my-zend $ tree -L 1
.
├── zend
└── htdocs -> zend/public

2 directories, 0 files

As you can see from the above directory structure, htdocs is available in its expected path and points to the frameworks entrypoint.

Important

When using Docker Toolbox, you need to explicitly allow the usage of symlinks. See below for instructions:

Docker Toolbox and Symlinks

5. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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

6. Open your browser ¶

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

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup other Frameworks¶

The setup instructions and frameworks shown in this section are only meant as an example and the list is in no way complete.

The Devilbox itself is a normal development stack and is capable of running any framework, CMS or custom written PHP software.

If you wish to see more install guides, open up an issue at Github: https://github.com/cytopia/devilbox/issues

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup reverse proxy NodeJS¶

This example will walk you through creating a NodeJS hello world application, which is started automatically on docker-compose up via pm2 , will be proxied to the web server and can be reached via valid HTTPS.

Note

It is also possible to attach a leight-weight NodeJS container to the Devilbox instead of running this in the PHP container. See here for details: Reverse Proxy for custom Docker

Table of Contents

Overview ¶

The following configuration will be used:

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

Additionally we will set the listening port of the NodeJS appliation to 4000 inside the PHP container.

We also want NodeJS running regardless of which PHP container will bestarted (global autostart).

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

Walk through ¶

It will be ready in nine simple steps:

Enter the PHP container
Create a new VirtualHost directory
Create NodeJS hello world application
Create virtual docroot directory
Add reverse proxy vhost-gen config files
Create autostart script
Setup DNS record
Restart the Devilbox
Visit http://my-node.loc in your browser

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

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

See also

3. Create NodeJS application ¶

# Navigate to your project directory
devilbox@php-7.0.20 in /shared/httpd $ cd my-node

# Create a directory which will hold the source code
devilbox@php-7.0.20 in /shared/httpd/my-node $ mkdir src

# Create the index.js file with your favourite editor
devilbox@php-7.0.20 in /shared/httpd/my-node/src $ vi index.js

index.js¶

// Load the http module to create an http server.
var http = require('http');

// Configure our HTTP server to respond with Hello World to all requests.
var server = http.createServer(function (request, response) {
  response.writeHead(200, {"Content-Type": "text/plain"});
  response.end("Hello World\n");
});

// Listen on port 4000
server.listen(4000);

4. Create virtual docroot directory ¶

Every project for the Devilbox requires a htdocs directory present inside the project dir. For a reverse proxy this is not of any use, but rather only for the Intranet vhost page to stop complaining about the missing htdocs directory. So that’s why this is only a virtual directory which will not hold any data.

# Navigate to your project directory
devilbox@php-7.0.20 in /shared/httpd $ cd my-node

# Create the docroot directory
devilbox@php-7.0.20 in /shared/httpd/my-node $ mkdir htdocs

See also

HTTPD_HTTP2_ENABLE

5. Add reverse proxy vhost-gen config files ¶

5.1 Create vhost-gen template directory ¶

Before we can copy the vhost-gen templates, we must create the .devilbox template directory inside the project directory.

# Navigate to your project directory
devilbox@php-7.0.20 in /shared/httpd $ cd my-node

# Create the .devilbox template directory
devilbox@php-7.0.20 in /shared/httpd/my-node $ mkdir .devilbox

See also

HTTPD_TEMPLATE_DIR

5.2 Copy vhost-gen templates ¶

Now we can copy and adjust the vhost-gen reverse proxy files for Apache 2.2, Apache 2.4 and Nginx.

The reverse vhost-gen templates are available in cfg/vhost-gen:

host> tree -L 1 cfg/vhost-gen/

cfg/vhost-gen/
├── apache22.yml-example-rproxy
├── apache22.yml-example-vhost
├── apache24.yml-example-rproxy
├── apache24.yml-example-vhost
├── nginx.yml-example-rproxy
├── nginx.yml-example-vhost
└── README.md

0 directories, 7 files

For this example we will copy all *-example-rproxy files into /shared/httpd/my-node/.devilbox to ensure this will work with all web servers.

host> cd /path/to/devilbox
host> cp cfg/vhost-gen/apache22.yml-example-rproxy data/www/my-node/.devilbox/apache22.yml
host> cp cfg/vhost-gen/apache24.yml-example-rproxy data/www/my-node/.devilbox/apache24.yml
host> cp cfg/vhost-gen/nginx.yml-example-rproxy data/www/my-node/.devilbox/nginx.yml

5.3 Adjust ports ¶

By default, all vhost-gen templates will forward requests to port 8000 into the PHP container. Our current example however uses port 4000, so we must change that accordingly for all three templates.

5.3.1 Adjust Apache 2.2 template ¶

Open the apache22.yml vhost-gen template in your project:

host> cd /path/to/devilbox
host> vi data/www/my-node/.devilbox/apache22.yml

Find the two lines with ProxyPass and ProxyPassReverse and change the port from 8000 to 4000

data/www/my-node/.devilbox/apache22.yml¶

# ... more lines above ... #

###
### Basic vHost skeleton
###
vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName   __VHOST_NAME__

      CustomLog  "__ACCESS_LOG__" combined
      ErrorLog   "__ERROR_LOG__"

      # Reverse Proxy definition (Ensure to adjust the port, currently '8000')
      ProxyRequests On
      ProxyPreserveHost On
      ProxyPass / http://php:4000/
      ProxyPassReverse / http://php:4000/

# ... more lines below ... #

5.3.2 Adjust Apache 2.4 template ¶

Open the apache24.yml vhost-gen template in your project:

host> cd /path/to/devilbox
host> vi data/www/my-node/.devilbox/apache24.yml

Find the two lines with ProxyPass and ProxyPassReverse and change the port from 8000 to 4000

data/www/my-node/.devilbox/apache24.yml¶

# ... more lines above ... #

###
### Basic vHost skeleton
###
vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName   __VHOST_NAME__

      CustomLog  "__ACCESS_LOG__" combined
      ErrorLog   "__ERROR_LOG__"

      # Reverse Proxy definition (Ensure to adjust the port, currently '8000')
      ProxyRequests On
      ProxyPreserveHost On
      ProxyPass / http://php:4000/
      ProxyPassReverse / http://php:4000/

# ... more lines below ... #

5.3.3 Adjust Nginx template ¶

Open the nginx.yml vhost-gen template in your project:

host> cd /path/to/devilbox
host> vi data/www/my-node/.devilbox/nginx.yml

Find the lines with proxy_pass and change the port from 8000 to 4000

data/www/my-node/.devilbox/nginx.yml¶

# ... more lines above ... #

###
### Basic vHost skeleton
###
vhost: |
  server {
      listen       __PORT____DEFAULT_VHOST__;
      server_name  __VHOST_NAME__;

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

      # Reverse Proxy definition (Ensure to adjust the port, currently '8000')
      location / {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_pass http://php:4000;
      }

# ... more lines below ... #

6. Create autostart script ¶

For NodeJS applications, the Devilbox already bundles an autostart template which you can use and simply just add the path of your NodeJS application. This template does nothing by default as its file name does not end by .sh. So let’s have a look at the template from autostart/run-node-js-projects.sh-example. The location where you will have to add your path is highlighted:

autostart/run-node-js-projects.sh-example¶

#!/usr/bin/env bash
#
# This is a generic example to startup your NodeJS projects with
# pm2 (https://github.com/Unitech/pm2)
#
# Important: As everything is run by the root user, you must explicitly direct the
#            commands to the devilbox user.
#



# Add the full paths of your Nodejs projects startup files into this array
# Each project separated by a newline and enclosed in double quotes. (No commas!)
# Paths are internal paths inside the PHP container.
NODE_PROJECTS=(
	#"/shared/httpd/my-rhost/js/index.js"
	#"/shared/httpd/my-node-hello-world/name/run.js"
	#"/shared/httpd/another-node-project/javascript/run.js"
)


# Check if any projects have been defined
if [ ${#NODE_PROJECTS[@]} -eq 0 ]; then
	echo "No projects defined. Exiting."
	exit 0
fi


# This loops over the paths, separates base directory and filename and will run it in the background
# as the user devilbox. There shouldn't be any need to change anything here.
for item in ${NODE_PROJECTS[*]}; do
	NODE_PATH="$( dirname "${item}" )"
	NODE_FILE="$( basename "${item}" )"

	if [ ! -d "${NODE_PATH}" ]; then
		>&2 echo "[Warning], skipping startup, directory does not exist: ${NODE_PATH}"
		continue;
	fi
	if [ ! -f "${NODE_PATH}/${NODE_FILE}" ]; then
		>&2 echo "[Warning], skipping startup, file does not exist: ${NODE_PATH}/${NODE_FILE}"
		continue;
	fi

	echo "su -c \"cd ${NODE_PATH}; pm2 start ${NODE_FILE}\" -l devilbox"
	su -c "cd ${NODE_PATH}; pm2 start ${NODE_FILE}" -l devilbox
done

So in order to proceed copy this file inside the autostart/ directory of the Devilbox git directory to a new file ending by .sh

host> cd /path/to/devilbox

# Navigate to the autostart directory
host> cd autostart

# Copy the template
host> cp run-node-js-projects.sh-example run-node-js-projects.sh

# Adjust the template and add your path:
host> vi run-node-js-projects.sh

autostart/run-node-js-projects.sh¶

# ... more lines above ... #

# Add the full paths of your Nodejs projects startup files into this array
# Each project separated by a newline and enclosed in double quotes. (No commas!)
# Paths are internal paths inside the PHP container.
NODE_PROJECTS=(
    "/shared/httpd/my-node/js/index.js"
)

# ... more lines below ... #

See also

Custom scripts per PHP version (individually for different PHP versions)
Custom scripts globally (equal for all PHP versions)
Autostarting NodeJS Apps

7. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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-node.loc

See also

8. Restart the Devilbox ¶

Now for those changes to take affect, you will have to restart the Devilbox.

host> cd /path/to/devilbox

# Stop the Devilbox
host> docker-compose down
host> docker-compose rm -f

# Start the Devilbox
host> docker-compose up -d php httpd bind

9. Open your browser ¶

All set now, you can visit http://my-node.loc or https://my-node.loc in your browser. The NodeJS application has been started up automatically and the reverse proxy will direct all requests to it.

Managing NodeJS ¶

If you have never worked with pm2 , I suggest to visit their website and get familiar with the available commands. A quick guide is below:

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

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

# List your running NodeJS apps
devilbox@php-7.0.20 in /shared/httpd $ pm2 list

┌──────────┬────┬─────────┬──────┬──────┬────────┬─────────┬────────┬─────┬───────────┬──────────┬──────────┐
│ App name │ id │ version │ mode │ pid  │ status │ restart │ uptime │ cpu │ mem       │ user     │ watching │
├──────────┼────┼─────────┼──────┼──────┼────────┼─────────┼────────┼─────┼───────────┼──────────┼──────────┤
│ index    │ 0  │ N/A     │ fork │ 1906 │ online │ 0       │ 42h    │ 0%  │ 39.7 MB   │ devilbox │ disabled │
└──────────┴────┴─────────┴──────┴──────┴────────┴─────────┴────────┴─────┴───────────┴──────────┴──────────┘

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup reverse proxy Sphinx docs¶

This example will walk you through creating a Sphinx documentation, which is started automatically on docker-compose up, will be proxied to the web server and can be reached via valid HTTPS.

Note

It is also possible to attach a leight-weight Python container to the Devilbox instead of running this in the PHP container. See here for details: Reverse Proxy for custom Docker

Table of Contents

Overview ¶

The following configuration will be used:

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

Additionally we will set the listening port of the Sphinx appliation to 4000 inside the PHP container.

We also want Sphinx running and autostarted only in the PHP 7.2 container (local autostart) and have all its required Python packages installed during docker-compose up.

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

Walk through ¶

It will be ready in nine simple steps:

Enter the PHP container
Create a new VirtualHost directory
Create basic Sphinx project
Create virtual docroot directory
Add reverse proxy vhost-gen config files
Create autostart script
Setup DNS record
Restart the Devilbox
Visit http://my-sphinx.loc in your browser

1. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

2. Create new vhost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

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

See also

3. Create basic Sphinx project ¶

# Navigate to your project directory
devilbox@php-7.0.20 in /shared/httpd $ cd my-sphinx

# Create a directory which will hold the documentation source code
devilbox@php-7.0.20 in /shared/httpd/my-sphinx $ mkdir doc

Create a basic Sphinx configuration file:

/shared/httpd/my-sphinx/doc/conf.py¶

source_suffix = '.rst'
master_doc = 'index'
html_theme = 'default'

exclude_patterns = [
    u'_build/*'
]

Create the table of contents file:

/shared/httpd/my-sphinx/doc/index.rst¶

.. :hidden:

*******
My Docs
*******

Description

.. toctree::
   :maxdepth: 2

   page1

Create the first page page1:

/shared/httpd/my-sphinx/doc/page1.rst¶

******
Page 1
******

Hello world

4. Create virtual docroot directory ¶

Every project for the Devilbox requires a htdocs directory present inside the project dir. For a reverse proxy this is not of any use, but rather only for the Intranet vhost page to stop complaining about the missing htdocs directory. So that’s why this is only a virtual directory which will not hold any data.

# Navigate to your project directory
devilbox@php-7.0.20 in /shared/httpd $ cd my-sphinx

# Create the docroot directory
devilbox@php-7.0.20 in /shared/httpd/my-sphinx $ mkdir htdocs

See also

HTTPD_HTTP2_ENABLE

5. Add reverse proxy vhost-gen config files ¶

5.1 Create vhost-gen template directory ¶

Before we can copy the vhost-gen templates, we must create the .devilbox template directory inside the project directory.

# Navigate to your project directory
devilbox@php-7.0.20 in /shared/httpd $ cd my-sphinx

# Create the .devilbox template directory
devilbox@php-7.0.20 in /shared/httpd/my-sphinx $ mkdir .devilbox

See also

HTTPD_TEMPLATE_DIR

5.2 Copy vhost-gen templates ¶

Now we can copy and adjust the vhost-gen reverse proxy files for Apache 2.2, Apache 2.4 and Nginx.

The reverse vhost-gen templates are available in cfg/vhost-gen:

host> tree -L 1 cfg/vhost-gen/

cfg/vhost-gen/
├── apache22.yml-example-rproxy
├── apache22.yml-example-vhost
├── apache24.yml-example-rproxy
├── apache24.yml-example-vhost
├── nginx.yml-example-rproxy
├── nginx.yml-example-vhost
└── README.md

0 directories, 7 files

For this example we will copy all *-example-rproxy files into /shared/httpd/my-sphinx/.devilbox to ensure this will work with all web servers.

host> cd /path/to/devilbox
host> cp cfg/vhost-gen/apache22.yml-example-rproxy data/www/my-sphinx/.devilbox/apache22.yml
host> cp cfg/vhost-gen/apache24.yml-example-rproxy data/www/my-sphinx/.devilbox/apache24.yml
host> cp cfg/vhost-gen/nginx.yml-example-rproxy data/www/my-sphinx/.devilbox/nginx.yml

5.3 Adjust ports ¶

By default, all vhost-gen templates will forward requests to port 8000 into the PHP container. Our current example however uses port 4000, so we must change that accordingly for all three templates.

5.3.1 Adjust Apache 2.2 template ¶

Open the apache22.yml vhost-gen template in your project:

host> cd /path/to/devilbox
host> vi data/www/my-sphinx/.devilbox/apache22.yml

Find the two lines with ProxyPass and ProxyPassReverse and change the port from 8000 to 4000

data/www/my-sphinx/.devilbox/apache22.yml¶

# ... more lines above ... #

###
### Basic vHost skeleton
###
vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName   __VHOST_NAME__

      CustomLog  "__ACCESS_LOG__" combined
      ErrorLog   "__ERROR_LOG__"

      # Reverse Proxy definition (Ensure to adjust the port, currently '8000')
      ProxyRequests On
      ProxyPreserveHost On
      ProxyPass / http://php:4000/
      ProxyPassReverse / http://php:4000/

# ... more lines below ... #

5.3.2 Adjust Apache 2.4 template ¶

Open the apache24.yml vhost-gen template in your project:

host> cd /path/to/devilbox
host> vi data/www/my-sphinx/.devilbox/apache24.yml

Find the two lines with ProxyPass and ProxyPassReverse and change the port from 8000 to 4000

data/www/my-sphinx/.devilbox/apache24.yml¶

# ... more lines above ... #

###
### Basic vHost skeleton
###
vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName   __VHOST_NAME__

      CustomLog  "__ACCESS_LOG__" combined
      ErrorLog   "__ERROR_LOG__"

      # Reverse Proxy definition (Ensure to adjust the port, currently '8000')
      ProxyRequests On
      ProxyPreserveHost On
      ProxyPass / http://php:4000/
      ProxyPassReverse / http://php:4000/

# ... more lines below ... #

5.3.3 Adjust Nginx template ¶

Open the nginx.yml vhost-gen template in your project:

host> cd /path/to/devilbox
host> vi data/www/my-sphinx/.devilbox/nginx.yml

Find the lines with proxy_pass and change the port from 8000 to 4000

data/www/my-sphinx/.devilbox/nginx.yml¶

# ... more lines above ... #

###
### Basic vHost skeleton
###
vhost: |
  server {
      listen       __PORT____DEFAULT_VHOST__;
      server_name  __VHOST_NAME__;

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

      # Reverse Proxy definition (Ensure to adjust the port, currently '8000')
      location / {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_pass http://php:4000;
      }

# ... more lines below ... #

6. Create autostart script ¶

Remember, we only wanted to have our Sphinx application run on the PHP 7.2 container, so we will create a autostart script only for that container.

Navigate to cfg/php-startup-7.2/ in the Devilbox git directory and create a new shell script ending by .sh

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

# Nagivate to startup directory for PHP 7.2 and create the script
host> cd cfg/php-startup-7.2/
host> vi my-sphinx.sh

cfg/php-startup-7.2/my-sphinx.sh¶

#!/usr/bin/env bash

# Install required Python modules as root user
pip install sphinx sphinx-autobuild

# Autostart Sphinx by devilbox user on Port 4000 and sent it to backgroun with '&'
sh -c "cd /shared/httpd/my-sphinx; sphinx-autobuild . _build/html -p 4000 -H 0.0.0.0" -l devilbox &

See also

Custom scripts per PHP version (individually for different PHP versions)
Custom scripts globally (equal for all PHP versions)
Autostarting NodeJS Apps

7. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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-sphinx.loc

See also

8. Restart the Devilbox ¶

Now for those changes to take affect, you will have to restart the Devilbox.

host> cd /path/to/devilbox

# Stop the Devilbox
host> docker-compose down
host> docker-compose rm -f

# Start the Devilbox
host> docker-compose up -d php httpd bind

9. Open your browser ¶

All set now, you can visit http://my-sphinx.loc or https://my-sphinx.loc in your browser. The Sphinx application has been started up automatically and the reverse proxy will direct all requests to it.

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Setup reverse proxy Python Flask¶

This example will walk you through adding a version specific Python Flask docker container, creating a simple Flask hello world application and have its requirements specified in requirements.txt automatically installed. Once setup, your application will be ready via docker-compose up, proxied to the web server and can be reached via valid HTTPS.

Note

This example is using an additional Docker image, so you are able to specify any Python version you like and even be able to add multiple Docker images with different versions.

Table of Contents

Overview ¶

The following configuration will be used:

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

Note

Inside the Devilbox PHP container, projects are always in /shared/httpd/.
On your host operating system, projects are by default in ./data/www/ inside the Devilbox git directory. This path can be changed via HOST_PATH_HTTPD_DATADIR.

The following Devilbox configuration is required:

Service	Implications
Webserver	Reverse proxy vhost-gen template need to be applied
Python Flask	Docker Compose override file must be applied.
`.env`	`FLASK_PROJECT` variable must be declared and set.
`.env`	`PYTHON_VERSION` variable can be declared and set.

Additionally we will set the listening port of the Flask appliation to 3000.

See also

For a detailed overview about the Compose file see: Enable and configure Python Flask

Walk through ¶

It will be ready in ten simple steps:

Configure Python Flask project name and versoin
Enter the PHP container
Create a new VirtualHost directory
Create Flask hello world application
Symlink virtual docroot directory
Add reverse proxy vhost-gen config files
Copy Python Flask compose file
Setup DNS record
Restart the Devilbox
Visit http://my-flask.loc in your browser

1. Configure Python Flask project name and version ¶

The Python Flask container will only serve a single project. In order for it to know where to find your project, you will have to add an environment variable (FLASK_PROJECT), telling it what the directory name of your project is.

Additionally you can define the Python version (PYTHON_VERSION) under which you want to run your Flask project.

See also

Available Python versions can be seen here: https://github.com/devilbox/docker-python-flask

Add the following variable to the very end of your .env file:

.env¶

FLASK_PROJECT=my-flask

#PYTHON_VERSION=2.7
#PYTHON_VERSION=3.5
#PYTHON_VERSION=3.6
#PYTHON_VERSION=3.7
PYTHON_VERSION=3.8

2. Enter the PHP container ¶

All work will be done inside the PHP container as it provides you with all required command line tools.

Navigate to the Devilbox git directory and execute shell.sh (or shell.bat on Windows) to enter the running PHP container.

host> ./shell.sh

See also

3. Create new VirtualHost directory ¶

The vhost directory defines the name under which your project will be available.
( <vhost dir>.TLD_SUFFIX will be the final URL ).

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

See also

docker-compose.override.yml

4. Create Flask hello world application ¶

4.1 Add your code ¶

# Navigate to your project directory
devilbox@php-7.0.20 in /shared/httpd $ cd my-flask

# Create a directory which will hold the source code
devilbox@php-7.0.20 in /shared/httpd/my-flask $ mkdir app

# Create the main.py file with your favourite editor
devilbox@php-7.0.20 in /shared/httpd/my-flask/app $ vi main.py

main.py¶

"""Flask example application."""
from flask import Flask

app = Flask(__name__)

@app.route("/")
def index():
    """Serve the default index page."""
    return "Hello World!"


if __name__ == "__main__":
    """Ensure Flask listens on all interfaces."""
    app.run(host='0.0.0.0')

4.2 Add dependencies ¶

You can optionally add a requirements.txt file which will be read during startup. The Python Flask container will then automatically install all Python libraries specified in that file.

# Navigate to your project directory
devilbox@php-7.0.20 in /shared/httpd $ cd my-flask

# Create and open the file with your favourite editor
devilbox@php-7.0.20 in /shared/httpd/my-flask $ vi requirements.txt

data/www/my-flask/requirements.txt¶

requests

5. Symlink virtual docroot directory ¶

# Navigate to your project directory
devilbox@php-7.0.20 in /shared/httpd $ cd my-flask

# Create the docroot directory
devilbox@php-7.0.20 in /shared/httpd/my-flask $ ln -s app htdocs

See also

HTTPD_HTTP2_ENABLE

6. Add reverse proxy vhost-gen config files ¶

6.1 Create vhost-gen template directory ¶

Before we can copy the vhost-gen templates, we must create the .devilbox template directory inside the project directory.

# Navigate to your project directory
devilbox@php-7.0.20 in /shared/httpd $ cd my-flask

# Create the .devilbox template directory
devilbox@php-7.0.20 in /shared/httpd/my-flask $ mkdir .devilbox

See also

HTTPD_TEMPLATE_DIR

6.2 Copy vhost-gen templates ¶

Now we can copy and adjust the vhost-gen reverse proxy files for Apache 2.2, Apache 2.4 and Nginx.

The reverse vhost-gen templates are available in cfg/vhost-gen:

host> tree -L 1 cfg/vhost-gen/

cfg/vhost-gen/
├── apache22.yml-example-rproxy
├── apache22.yml-example-vhost
├── apache24.yml-example-rproxy
├── apache24.yml-example-vhost
├── nginx.yml-example-rproxy
├── nginx.yml-example-vhost
└── README.md

0 directories, 7 files

For this example we will copy all *-example-rproxy files into data/www/my-flask/.devilbox/ (Inside container: /shared/httpd/my-flask/.devilbox) to ensure this will work with all web servers.

host> cd /path/to/devilbox
host> cp cfg/vhost-gen/apache22.yml-example-rproxy data/www/my-flask/.devilbox/apache22.yml
host> cp cfg/vhost-gen/apache24.yml-example-rproxy data/www/my-flask/.devilbox/apache24.yml
host> cp cfg/vhost-gen/nginx.yml-example-rproxy data/www/my-flask/.devilbox/nginx.yml

6.3 Adjust ports and backend ¶

By default, all vhost-gen templates will forward requests to port 8000 into the PHP container. Our current example however uses port 3000 and backend IP 172.16.238.250 (as defined in the Flask docker compose override file), so we must change that accordingly for all three templates.

6.3.1 Adjust Apache 2.2 template ¶

Open the apache22.yml vhost-gen template in your project:

host> cd /path/to/devilbox
host> vi data/www/my-flask/.devilbox/apache22.yml

Find the two lines with ProxyPass and ProxyPassReverse and change the port from 8000 to 3000 as well as the backend server from php to 172.16.238.250.

data/www/my-flask/.devilbox/apache22.yml¶

# ... more lines above ... #

###
### Basic vHost skeleton
###
vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName   __VHOST_NAME__

      CustomLog  "__ACCESS_LOG__" combined
      ErrorLog   "__ERROR_LOG__"

      # Reverse Proxy definition (Ensure to adjust the port, currently '8000')
      ProxyRequests On
      ProxyPreserveHost On
      ProxyPass / http://172.16.238.250:3000/
      ProxyPassReverse / http://172.16.238.250:3000/

# ... more lines below ... #

6.3.2 Adjust Apache 2.4 template ¶

Open the apache24.yml vhost-gen template in your project:

host> cd /path/to/devilbox
host> vi data/www/my-flask/.devilbox/apache24.yml

Find the two lines with ProxyPass and ProxyPassReverse and change the port from 8000 to 3000

data/www/my-flask/.devilbox/apache24.yml¶

# ... more lines above ... #

###
### Basic vHost skeleton
###
vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName   __VHOST_NAME__

      CustomLog  "__ACCESS_LOG__" combined
      ErrorLog   "__ERROR_LOG__"

      # Reverse Proxy definition (Ensure to adjust the port, currently '8000')
      ProxyRequests On
      ProxyPreserveHost On
      ProxyPass / http://172.16.238.250:3000/
      ProxyPassReverse / http://172.16.238.250:3000/

# ... more lines below ... #

6.3.3 Adjust Nginx template ¶

Open the nginx.yml vhost-gen template in your project:

host> cd /path/to/devilbox
host> vi data/www/my-flask/.devilbox/nginx.yml

Find the lines with proxy_pass and change the port from 8000 to 3000

data/www/my-flask/.devilbox/nginx.yml¶

# ... more lines above ... #

###
### Basic vHost skeleton
###
vhost: |
  server {
      listen       __PORT____DEFAULT_VHOST__;
      server_name  __VHOST_NAME__;

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

      # Reverse Proxy definition (Ensure to adjust the port, currently '8000')
      location / {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_pass http://172.16.238.250:3000;
      }

# ... more lines below ... #

7. Copy Python Flask compose file ¶

Python Flask comes with its own Docker container and can be added to the Devilbox stack via the docker-compose.override.yml file. A fully functional template already exists in the compose/ directory. All you will have to do is copy it over.

host> cd /path/to/devilbox
host> cp compose/docker-compose.override.yml-python-flask.yml docker-compose.override.yml

See also

8. DNS record ¶

If you have Auto DNS configured already, you can skip this section, because DNS entries will be available automatically by the bundled DNS server.

If you don’t 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-flask.loc

See also

9. Restart the Devilbox ¶

Now for those changes to take affect, you will have to restart the Devilbox.

host> cd /path/to/devilbox

# Stop the Devilbox
host> docker-compose down
host> docker-compose rm -f

# Start the Devilbox
host> docker-compose up -d php httpd bind flask1

10. Open your browser ¶

All set now, you can visit http://my-flask.loc or https://my-flask.loc in your browser. The Python Flask application has been started up automatically and the reverse proxy will direct all requests to it.

Next steps ¶

Once everything is installed and setup correctly, you might be interested in a few follow-up topics.

Use bundled batteries ¶

The Devilbox ships most common Web UIs accessible from the intranet.

See also

Enhance the Devilbox ¶

Go ahead and make the Devilbox more smoothly by setting up its core features.

See also

Add services ¶

In case your framework/CMS requires it, attach caching, queues, database or performance tools.

See also

Container tools ¶

Stay inside the container and use what’s available.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Syncronize container permissions¶

One main problem with a running Docker container is to synchronize the ownership of files in a mounted volume in order to preserve security (Not having to use chmod 0777 or root user).

This problem will be addressed below by using a PHP-FPM docker image as an example.

Unsyncronized permissions¶

Consider the following directory structure of a mounted volume. Your hosts computer uid/gid are 1000 which does not have a corresponding user/group within the container. Fortunately the tmp/ directory allows everybody to create new files in it, because its permissions are 0777.

                  [Host]                   |             [Container]
------------------------------------------------------------------------------------------
 $ ls -l                                   | $ ls -l
 -rw-r--r-- user group index.php           | -rw-r--r-- 1000 1000 index.php
 drwxrwxrwx user group tmp/                | drwxrwxrwx 1000 1000 tmp/

Your web application might now have created some temporary files (via the PHP-FPM process) inside the tmp/ directory:

                  [Host]                   |             [Container]
------------------------------------------------------------------------------------------
 $ ls -l tmp/                              | $ ls -l tmp/
 -rw-r--r-- 96 96 _tmp_cache01.php         | -rw-r--r-- www www _tmp_cache01.php
 -rw-r--r-- 96 96 _tmp_cache02.php         | -rw-r--r-- www www _tmp_cache01.php

On the Docker container side everything is still fine, but on your host computers side, those files now show a user id and group id of 96, which is in fact the uid/gid of the PHP-FPM process running inside the container. On the host side you have just lost write/delete access to those files and will now have to use sudo in order to delete/edit those files.

It gets even worse¶

Consider your had created the tmp/ directory on your host only with 0775 permissions:

                  [Host]                   |             [Container]
------------------------------------------------------------------------------------------
 $ ls -l                                   | $ ls -l
 -rw-r--r-- user group index.php           | -rw-r--r-- 1000 1000 index.php
 drwxrwxr-x user group tmp/                | drwxrwxr-x 1000 1000 tmp/

If your web application now wants to create some temporary files (via the PHP-FPM process) inside the tmp/ directory, it will fail due to lack of permissions.

The solution¶

To overcome this problem, it must be made sure that the PHP-FPM process inside the container runs under the same uid/gid as your local user that mouns the volumes and also wants to work on those files locally. However, you never know during Image build time what user id this would be. Therefore it must be something that can be changed during startup of the container.

This is achieved in the Devilbox’s containers by two environment variables that can be provided during startup in order to change the uid/gid of the PHP-FPM user prior starting up PHP-FPM process.

$ docker run -e NEW_UID=1000 -e NEW_GID=1000 -it devilbox/php-fpm:7.2-work
[INFO] Changing user 'devilbox' uid to: 1000
root $ usermod -u 1000 devilbox
[INFO] Changing group 'devilbox' gid to: 1000
root $ groupmod -g 1000 devilbox
[INFO] Starting PHP 7.2.0 (fpm-fcgi) (built: Oct 30 2017 12:05:19)

When NEW_UID and NEW_GID are provided to the startup command, the container will do a usermod and groupmod prior starting up in order to assign new uid/gid to the PHP-FPM user. When the PHP-FPM process finally starts up it actually runs with your local system user and making sure permissions will be in sync from now on.

Note

To tackle this on the PHP-FPM side is only half a solution to the problem. The same applies to a web server Docker container when you offer file uploads. They will be uploaded and created by the web servers uid/gid. Therefore the web server itself must also provide the same kind of solution.

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Available container¶

Note

Start the Devilbox: Find out how to start some or all container.

The following tables give 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.

Core container¶

These container are well integrated into the Devilbox intranet and are considered core container:

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

Additional container¶

Additional container that are not yet integrated into the Devilbox intranet are also available. Those container come via docker-compose.override.yml and must explicitly be enabled. They are disabled by default to prevent accidentally starting too many container and making your computer unresponsive.

Container	Name	Hostname	IP Address
PHP Community	php	php	172.16.238.10
Blackfire	blackfire	blackfire	172.16.238.200
MailHog	mailhog	mailhog	172.16.238.201
Ngrok	ngrok	ngrok	172.16.238.202
RabbitMQ	rabbit	rabbit	172.16.238.210
Solr	solr	solr	172.16.238.220
Varnish	varnish	varnish	172.16.238.230
HAProxy (SSL offloader for Varnish)	haproxy	haproxy	172.16.238.231
ELK: Elastic Search	elastic	elastic	172.16.238.240
ELK: Logstash	logstash	logstash	172.16.238.241
ELK: Kibana	kibana	kibana	172.16.238.242
Python Flask	flask1	flask1	172.16.238.250

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

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

The PHP container is your workhorse and these are your tools:

Binary	Tool
`ansible`	Ansible
various binaries	awesome-ci
`brew`	Linux brew
`codecept`	Codeception
`composer`	Composer
`dep`	Deployer
`drush`	Drush
`drupal`	Drupal Console
`eslint`	ESLint
`git`	Git
`git-flow`	Git flow
`gulp`	Gulp
`grunt`	Grunt
`jsonlint`	JSON lint
`laravel`	Laravel installer
`linkcheck`	linkcheck
`lumen`	Laravel Lumen
`mdl`	Markdown lint
`mdlint`	MD linter
`mongo*`	Various MongoDB client tools
`mysql*`	Various MySQL client tools
`mysqldump-secure`	mysqldump-secure
`ng`	Angular CLI
`node`	Node
`npm`	NPM
`pg*`	Various PostgreSQL client tools
`phalcon`	Phalcon DevTools
`php-cs-fixer`	PHP-CS-Fixer
`phpcs`	PHP CodeSniffer
`phpcbf`	PHP Code Beautifier and Fixer
`phpmd`	PHP Mess Detector
`phpunit`	PHPUnit
`photon`	Photon CMS cli
`pm2`	pm2
`redis*`	Various Redis client tools
`sass`	Sass
`scss-lint`	SCSS Lint
`ssh`	OpenSSH
`symfony`	Symfony installer
`tig`	Text-mode Interface for Git
`vue`	Standard Tooling for Vue.js Development
`webpack`	Webpack
`wp`	Wordpress CLI
`yamllint`	Yamllint
`yarn`	Yarn
`yq`	yq

Note

If you are in need of other tools, open up an issue at Github and ask for it, this can usually be implemented very quickly.

See also

If you ever feel those tools are out-dated, simply update your Docker images. Docker images are built every night to ensure latest tools and security patches: Update Docker images

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Troubleshooting¶

This section will contain common problems and how to resolve them. It will grow over time once there are more issues reported.

See also

How To
FAQ

Important

Update the Devilbox

Issues are constantly being fixed. Before attempting to spend too much time digging into your issue, make sure you are running the latest git changes and have pulled the latest Docker images.

Also keep in mind that configuration files might change, so ensure to diff the default ones against your currently active ones for added, removed or changed values.

Table of Contents

What to always do first
General
Performance
- Performance issues on Docker for Mac
DNS issues
- zone ‘localhost’: already exists previous definition
SSL issues
- unable to get local issuer certificate
Web server issues
PHP issues
- Fatal error: Cannot redeclare go()
Database issues
Docker Toolbox
- ln: creating symbolic link ‘./foo’: Read-only file system

What to always do first ¶

Before going into the issues below, always do the following

1. Ensure stopped container are removed

# Ensure everything is stopped
host> docker-compose stop
host> docker-compose kill
host> docker-compose rm -f

2. Ensure config is normalized

# Ensure .env file is normalized
host> cp env-example .env

3. Statup minimal

# Test everything with the minimal stack
host> docker-compose up php httpd bind

4. Run config checker

# Run the bash script in the Devilbox git directory
host> ./check-config.sh

General ¶

Sudden unexplained problems on Windows ¶

In case something stopped working for no reason, check out other Docker container. If you experience similar issues as well, check for any unattended Windows updates or updates to Docker itself. If those exist, try to revert them and see if that was the cause.

I heard many bug stories from fellow Windows users so far. A good contact point for that is the Docker forum itself: https://forums.docker.com/c/docker-desktop-for-windows

A few general things you should always do before attempting to open up issues are:

1. Used default settings from env-example

Try using the exact settings from env-example as variables might have been updated in git.
# Ensure everything is stopped
host> cp env-example .env

2. Clean, updated and minimal start

# Ensure everything is stopped
host> docker-compose stop
host> docker-compose kill
host> docker-compose rm -f

# Ensure everything is updated
host> docker-compose pull

# Start again
host> docker-compose up php httpd bind

3. Reset Docker credentials:

As it might sound strange, this fix might indeed solve a lot of problems on Windows. Go to your Docker settings and reset your credentials.

4. Shared volumes:

Ensure all your Devilbox data (Devilbox directory and project directory) are within the volumes that are shared by Docker. If not add those in the Docker settings.

No Space left on Device ¶

If on Docker for Mac you get an error during docker pull similar to the following one:

write /var/lib/docker/tmp/GetImageBlob220119603: no space left on device

It means the file where MacOS stores the docker images is full. The usual way is to delete unused images and volumes to free up space or increase this volumes size.

However, depending on the version of Docker some of the above suggestions may not work and you have to get support from the docker/for-mac GitHub repository or forum.

See also

Address already in use ¶

One of the Docker container wants to bind to a port on the host system which is already taken. Figure out what service is listening on your host system and shut it down or change the port of the affected service in the Devilbox .env file.

Some examples of common error messages:

Error starting userland proxy: Bind for 0.0.0.0:80: unexpected error (Failure EADDRINUSE)

Unable to finish Pulling as unauthorized: incorrect username or password ¶

This error might occur if you are already logged into a different Docker repository. To fix this error, sign out of your currently logged in repository and try again.

localhost or 127.0.0.1 not found ¶

If you are using Docker Toolbox, the Devilbox intranet is not available on localhost or 127.0.0.1, but rather on the IP address of the Docker Toolbox machine.

See also

Cannot connect to MySQL after restart

ERROR: Version in “./docker-compose.yml” is unsupported ¶

This simply means your Docker and/or Docker Compose versions are outdated.

See also

Prerequisites

Performance ¶

Performance issues on Docker for Mac ¶

By default Docker for Mac has performance issues on mounted directories with a lot of files inside. To overcome this issue you can apply different kinds of caching options to the mount points.

See also

DNS issues ¶

zone ‘localhost’: already exists previous definition ¶

bind_1 | /etc/bind/devilbox-wildcard_dns.localhost.conf:1:
zone 'localhost': already exists previous definition:
/etc/bind/named.conf.default-zones:10

This error occurs when using localhost as the TLD_SUFFIX.

See also

SSL issues ¶

unable to get local issuer certificate ¶

Errors occurred when trying to connect to www.example.com:
cURL error 77: error setting certificate verify locations: CAfile: certificate ./ca/cacert.pem CApath: /etc/ssl/certs

This issue might arise if you set TLD_SUFFIX to an official top level domain such as .com. What happens is that the bundled DNS server does a catch-all on the TLD and redirects all name resolution to the Devilbox’s PHP container IP address.

If you want to access https://www.example.com in that case, the request goes to the PHP container which does not have a valid SSL certificate for that domain.

Do not user official TLD’s for TLD_SUFFIX.

See also

Web server issues ¶

Warning: DocumentRoot [/var/www/default/htdocs/] does not exist ¶

This error is most likely to only occur on Docker for Windows and is just a result of not working volumes mounts.

403 forbidden ¶

This error might occur for the Devilbox intranet or custom created projects.

File and directory permissions ¶

On of the cause could be wrongly set file and directory permissions.

First ensure the cloned git directory is readable for users, groups and others.

For the Devilbox intranet, ensure the .devilbox/ directory is readable for users, groups and others. Also check files and directories within.

For projects, ensure an index.php or index.html exists and that all files and directories are readable for users, groups and others.

Shared volumes ¶

This might additionally occur on MacOS or Windows due to the Devilbox and/or its projects not being in the standard location of Docker Shared volumes.

Check your Docker settings to allow shared volumes for the path of the Devilbox and its projects.

504 Gateway timeout ¶

This error occurs when the upstream PHP-FPM server takes longer to execute a script, than the timeout value set in the web server for PHP-FPM to answer.

For that to fix one must increase the PHP-FPM/Proxy timeout settings in the .env file. HTTPD_BACKEND_TIMEOUT

See also

PHP issues ¶

Fatal error: Cannot redeclare go()¶

If you encounter this error, it is most likely that your current project declares the PHP function go() and that you have enabled the swoole module which also provides an implementation of that function.

To mitigate that issue, make sure that the swoole module is disabled in .env.

See also

Database issues ¶

SQLSTATE[HY000] [1130] Host ‘172.16.238.10’ is not allowed to connect to this MariaDB server ¶

See also

Cannot connect to MySQL after restart ¶

This error usually occurs when you import a MySQL dump including the mysql database itself, which will overwrite the user permissions and thus you won’t be able to connect anymore with the settings specified in .env.

Invalid bind mount spec ¶

This error might occure after changing the path of MySQL, PgSQL, Mongo or any other data directory.

When you change any paths inside .env that affect Docker mountpoints, the container need to be removed and re-created during the next startup. Removing the container is sufficient as they will always be created during run if they don’t exist.

In order to remove the container do the following:

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

# Remove the stopped container (IMPORTANT!)
# After the removal it will be re-created during next run
host> docker-compose rm -f

See also

Remove stopped container

[Warning] World-writable config file ‘/etc/mysql/docker-default.d/my.cnf’ is ignored ¶

This warning might occur when using Docker Toolbox and the Devilbox on Windows and trying to apply custom MySQL configuration files. This will also result in the configuration file not being source by the MySQL server.

To fix this issue, you will have to change the file permission of your custom configuration files to read-only by applying the following chmod command.

# Nagivate to devilbox git directory
host> cd path/to/devilbox

# Navigate to the MySQL config directory (e.g.: MySQL 5.5)
host> cd cfg/mysql-5.5

# Make cnf files read only
host> chmod 0444 *.cnf

See also

[MariaDB] Assertion failure when executing prepared statement with ? in IN list ¶

Some MariaDB versions are affected by MDEV-27937 bug, use a fixed version or set in_predicate_conversion_threshold variable to a higher value.

Docker Toolbox ¶

ln: creating symbolic link ‘./foo’: Read-only file system ¶

VirtualBox might not allow symlinks by default on other directories. This can however be fixed manually via.

# <DIR> is the VirtualBox shared directory
host> VBoxManage setextradata default VBoxInternal2/SharedFoldersEnableSymlinksCreate/<DIR> 1

See also

For detailed example see here:

Docker Toolbox on Windows: Symlinks

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

FAQ¶

Find common questions and answers here.

See also

Table of Contents

General
Configuration
Compatibility

General ¶

Are there any differences between native Docker and Docker Toolbox?¶

Yes, read Docker Toolbox and the Devilbox to find out more.

Why are mounted MySQL data directories separated by version?¶

This is just a pre-caution. Imagine they would link to the same datadir. You start the Devilbox with mysql 5.5, create a database and add some data. Now you decide to switch to mysql 5.7 and restart the devilbox. The newer mysql version will probably upgrade the data leaving it unable to start with older mysql versions.

Why are mounted PostgreSQL data directories separated by version?¶

See: Why are mounted MySQL data directories separated by version?

Why are mounted MongoDB data directories separated by version?¶

See: Why are mounted MySQL data directories separated by version?

Why do the user/group permissions of log/ or cfg/ directories show 1000?¶

Uid and Gid are set to 1000 by default. You can alter them to match the uid/gid of your current user. Open the .env file and change the sections NEW_UID and NEW_GID. When you start up the devilbox, the PHP container will use these values for its user.

See also

NEW_UID and NEW_GID

Can I not just comment out the service in the .env file?¶

No, don’t do this. This will lead to unexpected behaviour (different versions will be loaded). The .env file allows you to configure the devilbox, but not to start services selectively.

Are there any required services that must/will always be started?¶

Yes. http and php will automatically always be started (due to dependencies inside docker-compose.yml) if you specify them or not.

What PHP Modules are available?¶

The Devilbox is a development stack, so it is made sure that a lot of PHP modules are available out of the box in order to work with many different frameworks.

Available PHP modules can be seen at the PHP Docker image repository.

Configuration ¶

Can I change the MySQL root password?¶

Yes, you can change the password of the MySQL root user. If you do so, you must also set the new password in your .env file. See MYSQL_ROOT_PASSWORD for how to change this value.

Can I change php.ini?¶

Yes, php.ini directives can be changed for each PHP version separately. See php.ini

Can I change my.cnf?¶

Yes, my.cnf directives can be changed for each MySQL version separately. See my.cnf

Can I change the project virtual host domain `.loc`?¶

Yes, the .env variable TLD_SUFFIX can be changed to whatever domain or subdomain you want. See TLD_SUFFIX.

Warning

Be aware not to use dev or localhost. See TLD_SUFFIX for more details. Also do not use any official domain TLDs such as com, net, org, etc.

Can I just start PHP and MySQL instead of all container?¶

Yes, every Docker container is optional. The Devilbox allows for selective startup. See Start the Devilbox.

Do I always have to edit `/etc/hosts` for new projects?¶

You need a valid DNS entry for every project that points to the Httpd server. As those records don’t exists by default, you will have to create them. However, the Devilbox has a bundled DNS server that can automate this for you. The only thing you have to do for that to work is to add this DNS server’s IP address to your /etc/resolv.conf. See Setup Auto DNS for detailed instructions.

Compatibility ¶

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

How To¶

The How to section gathers information about various topics, that might need to be done at some point throughout the installation and configuration.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Add custom DNS server on Android¶

Adding custom DNS server on Android works out of the box for each connected Wi-Fi network separately. There is no need to install external Apps.

Table of Contents

Change DNS server in Android directly
Change DNS server with Third-Party App

Change DNS server in Android directly ¶

Navigate to Settings -> Wi-Fi
Press and hold on the Wi-Fi network you want to change
Choose Modify network

Android: Wi-Fi list
Scroll down and click on Advanced options

Android: Advanced options
Scroll down and click on DHCP

Android: Select DHCP options
Click on Static

Android: Select static DHCP options
Scroll down and change the DNS server IP for DNS 1 (the first DNS server in the list)

Android: Add custom DNS server

Change DNS server with Third-Party App ¶

If the above does not work for you or you just want another App that makes it even easier to change DNS settings, you can search the Playstore for many available DNS changer Apps. They also work on non-rooted Androids.

See also

DNS Changer

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Add custom DNS server on iPhone¶

Adding custom DNS server on iPhone works out of the box for each connected Wi-Fi network separately. There is no need to install external Apps.

Table of Contents

Change DNS server in iPhone directly
Change DNS server with Third-Party App

Change DNS server in iPhone directly ¶

Navigate to Settings -> Wi-Fi
Tap on your active Wi-Fi connection

iPhone: Wi-Fi list
Scroll down and tap on Configure DNS

iPhone: Wi-Fi list
Select Manual

iPhone: Wi-Fi list
Add your DNS server IP (ensure it is the first in the list)

iPhone: Wi-Fi list

Change DNS server with Third-Party App ¶

If the above does not work for you or you just want another App that makes it even easier to change DNS settings, you can search the AppStore for many available DNS changer Apps. They also work on non-rooted iPhones.

See also

DNS Override

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Add custom DNS server on Linux¶

On Linux the DNS settings can be controlled by various different methods. Two of them are via Network Manager and systemd-resolved. Choose on of the methods depending on your local setup.

Table of Contents

Assumption
Non permanent solution
Network Manager
systemd-resolved

Assumption ¶

This tutorial is using 127.0.0.1 as the DNS server IP address, as it is the method to setup Auto DNS for your local Devilbox.

Non permanent solution ¶

When you just want to try out to add a new DNS server without permanent settings, you should use this option.

Note

Non permanent means, the settings will be gone when your DHCP release will be renewed, reconnecting to the network, restarting the network service, logging out or rebooting your machine.

Open /etc/resolv.conf with root or sudo privileges with your favourite editor on your host operating sustem:
```
host> sudo vi /etc/resolv.conf
```

Add your new nameserver directive above all existing nameserver directives:

/etc/resolv.conf¶

# Generated by NetworkManager
search intranet
nameserver 127.0.0.1
nameserver 192.168.0.10

It will work instantly after saving the file

Network Manager ¶

(This is a permanent solution and needs to be reverted when you don’t need it anymore)

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 (127.0.0.1).

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
host> sudo service network-manager restart

# Or the systemd way
host> 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.

systemd-resolved ¶

(This is a permanent solution and needs to be reverted when you don’t need it anymore)

In case you are using systemd-resolved instead of NetworkManager, add the following line to the very beginning to /etc/resolv.conf.head:

/etc/resolv.conf.head¶

nameserver 127.0.0.1

Prevent NetworkManager from modifying /etc/resolv.conf and leave everything to systemd-resolved by adding the following line under the [main] section of /etc/NetworkManager/NetworkManager.conf

/etc/NetworkManager/NetworkManager.conf¶

dns=none

As a last step you will have to restart systemd-resolved.

host> sudo systemctl stop systemd-resolved
host> sudo systemctl start systemd-resolved

Once done, you can verify if the new DNS settings are effective:

host> systemd-resolve --status

See also

Archlinux Wiki: resolv.conf

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Add custom DNS server on MacOS¶

Table of Contents

Assumption
Network preferences

Assumption ¶

This tutorial is using 127.0.0.1 as the DNS server IP address, as it is the method to setup Auto DNS for your local Devilbox.

Network preferences ¶

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

MacOS: network settings

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Add custom DNS server on Windows¶

Table of Contents

Assumption
Network preferences

Assumption ¶

This tutorial is using 127.0.0.1 as the DNS server IP address, as it is the method to setup Auto DNS for your local Devilbox.

Network preferences ¶

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

Windows: network connections

Windows: ethernet properties

_images/win-internet-protocol-properties.png

Windows: internet protocol properties

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

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Add project hosts entry on Linux¶

On Linux, custom DNS entries can be added to the /etc/hosts and will take precedence over the same entries provided by any DNS server.

Table of Contents

Assumption
- Step by step

Assumption ¶

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`

Step by step ¶

When using Docker on Linux you can use 127.0.0.1 for the IP address.

Open /etc/hosts with root privileges or via sudo with your favorite editor
```
host> sudo vi /etc/hosts
```
Add DNS records for the above listed examples:
/etc/hosts¶
```
127.0.0.1  project-1.loc
127.0.0.1  www.project-1.loc
```

Safe the file and verify the DNS entries with the ping command

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

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Add project hosts entry on MacOS¶

On MacOS, custom DNS entries can be added to the /etc/hosts and will take precedence over the same entries provided by any DNS server.

Table of Contents

Assumption
- Docker for Mac
- Docker Toolbox

Assumption ¶

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`

Docker for Mac ¶

When using Docker for Mac you can use 127.0.0.1 for the IP address.

Open /etc/hosts with admistrative privileges or via sudo with your favorite editor
```
host> sudo vi /etc/hosts
```
Add DNS records for the above listed examples:
/etc/hosts¶
```
127.0.0.1  project-1.loc
127.0.0.1  www.project-1.loc
```

Safe the file and verify the DNS entries with the ping command

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

Docker Toolbox ¶

When using the Docker Toolbox, you cannot use 127.0.0.1 for DNS entries, but rather need to use the IP address of the Docker Toolbox machine instead.

See also

For this example we will assume the Docker Toolbox IP address is 192.168.99.100.

Open /etc/hosts with admistrative privileges or via sudo with your favorite editor
```
host> sudo vi /etc/hosts
```

Add DNS records for the above listed examples:

/etc/hosts¶

192.168.99.100  project-1.loc
192.168.99.100  www.project-1.loc

Safe the file and verify the DNS entries with the ping command

host> ping -c1 project-1.loc

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

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

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

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Add project hosts entry on Windows¶

On Windows, custom DNS entries can be added to the C:\Windows\System32\drivers\etc and will take precedence over the same entries provided by any DNS server.

Table of Contents

Assumption
- Docker for Windows
- Docker Toolbox

Assumption ¶

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`

Docker for Windows ¶

When using Docker for Windows you can use 127.0.0.1 for the IP address.

Open C:\Windows\System32\drivers\etc with admistrative privileges via notepad.exe or any other text editor.
Add DNS records for the above listed examples:
C:WindowsSystem32driversetc¶
```
127.0.0.1  project-1.loc
127.0.0.1  www.project-1.loc
```

Save the file and verify the DNS entries with the ping command

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

Docker Toolbox ¶

When using the Docker Toolbox, you cannot use 127.0.0.1 for DNS entries, but rather need to use the IP address of the Docker Toolbox machine instead.

See also

For this example we will assume the Docker Toolbox IP address is 192.168.99.100.

Open C:\Windows\System32\drivers\etc with admistrative privileges via notepad.exe or any other text editor.
Add DNS records for the above listed examples:
C:WindowsSystem32driversetc¶
```
192.168.99.100  project-1.loc
192.168.99.100  www.project-1.loc
```

Safe the file and verify the DNS entries with the ping command

host> ping -c1 project-1.loc

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

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

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

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Find your user id and group id on MacOS¶

Table of Contents

Docker for Mac vs Docker Toolbox
- Docker for Mac
- Docker Toolbox
Find uid and gid
- Find your user id (uid)
- Find your group id (gid)

Docker for Mac vs Docker Toolbox ¶

Docker for Mac ¶

On Docker for Mac (native Docker) you can open up any terminal you prefer, there are no other requirements.

Docker Toolbox ¶

On Docker Toolbox it is important that you open up a Docker environment prepared terminal window.

See also

Open a terminal on MacOS

Find uid and gid ¶

Open the correct terminal as described above and type the following commands:

Find your user id (`uid`)¶

host> id -u

Find your group id (`gid`)¶

host> id -g

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Find your user id and group id on Windows¶

Table of Contents

Docker for Windows
Docker Toolbox
- Find your user id (uid)
- Find your group id (gid)

Docker for Windows ¶

On Docker for Windows it is not necessary to change uid and gid in your .env file.

Note

Docker for Windows is internally using network shares (SMB) to mount Docker volumes. This does not require to syncronize file and directoriy permissions via uid and gid.

Docker Toolbox ¶

On Docker Toolbox it is important that you open up a Docker environment prepared terminal window.

See also

Open a terminal on Windows

Find your user id (`uid`)¶

Type the following command to retrieve the correct uid.

host> id -u

Find your group id (`gid`)¶

Type the following command to retrieve the correct gid.

host> id -g

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Find Docker and Docker Compose version¶

Open a terminal and type the following:

# Get Docker version
host> docker --version

# Get Docker Compose version
host> docker-compose --version

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Move backups to a different directory¶

No matter if your backups are already in a different location or if you want to move them out of the Devilbox git directory now, you can do that in a few simple steps.

Table of Contents

Move backups out of the Devilbox git directory

Move backups out of the Devilbox git directory ¶

All you have to do is to adjust the path of HOST_PATH_BACKUPDIR 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_BACKUPDIR

.env¶

HOST_PATH_HTTPD_DATADIR=/home/user/backups/devilbox/

That’s it, whenever you start up the Devilbox, /home/user/backups/devilbox/ will be mounted into the PHP container into /shared/backups/.

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Move projects to a different directory¶

No matter if your projects are already in a different location or if you want to move them out of the Devilbox git directory now, you can do that in a few simple steps.

Table of Contents

Projects in an absolute path
Projects adjacent to Devilbox directory

Projects in an absolute path ¶

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 do 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/.

Projects adjacent to Devilbox directory ¶

Consider the following directory setup:

|
+- devilbox/
|
+- projects/
   |
   + project1/
   | |
   | + htdocs/
   |
   + project2/
     |
     + htdocs/

Independently of where the Devilbox directory is located, you can achieve this structure via relative path settings.

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=../projects

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

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Host address alias on MacOS¶

In order for Xdebug to work on Docker for MacOS, the container needs a well known IP address for its Xdebug remote host. This is achieved by adding an alias to the loopback device.

Table of Contents

One-time alias
Boot persistent alias

One-time alias ¶

In order to create this alias for testing purposes, which does not survive reboots, you can issue the command manually with sudo or root privileges.

host> sudo ifconfig lo0 alias 10.254.254.254

Boot persistent alias ¶

If you want to have this alias persistent across reboot, you need to download and enable a plist file:

# Download the plist into the correct location
host> sudo curl -o \
        /Library/LaunchDaemons/org.devilbox.docker_10254_alias.plist \
        https://raw.githubusercontent.com/devilbox/xdebug/master/osx/org.devilbox.docker_10254_alias.plist

# Enable without reboot
host> sudo launchctl load /Library/LaunchDaemons/org.devilbox.docker_10254_alias.plist

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Docker Toolbox and the Devilbox¶

Docker Toolbox is a legacy solution to bring Docker to systems which don’t natively support Docker. This is achieved by starting a virtualized Linux instance (e.g.: inside VirtualBox) and have Docker run inside this machine.

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

However, there are a few stumbling blocks you need to pay attention to in order to use the Devilbox at its full potential.

See also

Docker Toolbox

Table of Contents

Devilbox listening address configuration
Find the Docker Toolbox IP address
Project DNS record pitfalls
Auto-DNS via port forwarding
- How does Auto-DNS work?
- How to fix it for Docker Toolbox
Mount shared folders
- MacOS
- Windows
  - Symlinks

Devilbox listening address configuration ¶

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 the virtual machine (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=

Important

The variable should exist, but there should not be any value after the equal sign.

See also

Stackoverflow: SSH into Docker machine

Find the Docker Toolbox IP address ¶

The Devilbox intranet will not be available under 127.0.0.1 or localhost as it does not run on your host operating system, but on a virtualized Linux machine which has a different IP address.

To find out the IP address on which Docker Toolbox is running you have to use the docker-machine command. Open a terminal and type the following:

host> docker-machine ip default
192.168.99.100

The above example outputs 192.168.99.100, but this might be different on your machine.

In this example I would then paste http://192.168.99.100 in the web browsers address bar to reach the Devilbox intranet.

See also

Project DNS record pitfalls ¶

When creating manual DNS records per project, you have to keep in mind that you cannot use 127.0.0.1 for the IP address part. You have to use the IP address of the Docker Toolbox virtual machine as was shown in the above example.

Assuming the Docker Toolbox IP address is: 192.168.99.100, you have to create DNS records as follows:

/etc/resolv.conf or C:\Windows\System32\drivers\etc¶

192.168.99.100 project.loc

See also

Auto-DNS via port forwarding ¶

In order to make Auto-DNS for projects work as it does for native Docker implementations you will have to do some prior configuration.

How does Auto-DNS work?¶

Auto-DNS is a catch-all DNS resolver for your chosen TLD_SUFFIX that will redirect any domain to 127.0.0.1. Unfortunately Docker Toolbox does not listen on that IP address.

How to fix it for Docker Toolbox ¶

To overcome this problem, you will have to create three port forwards on your host operating system from the Docker machine IP address for DNS (port 53), http (port 80) and https (port 443) to 127.0.0.1 on your host os.

Assuming the Docker Toolbox IP address is 192.168.99.100 the three port forwards must be as follows:

From IP	From port	To IP	To port
192.168.99.100	53	127.0.0.1	53
192.168.99.100	80	127.0.0.1	80
192.168.99.100	443	127.0.0.1	443

See also

Mount shared folders ¶

Docker Toolbox will automatically set up a shared directory between your host operating system and the virtual Linux machine. Only files and directories within this shared directory can be used to be mounted into Docker container. If you plan to mount files or directories outside of this default path you have to create a new shared directory as described below.

MacOS ¶

When you want to have your projects reside not somewhere in the /Users directory, ensure you have read, understood and applied the following:

“By default, Toolbox only has access to the /Users directory and mounts it into the VMs at /Users. If your project lives elsewhere or needs access to other directories on the host filesystem, you can add them.”

Windows ¶

When you want to have your projects reside not somewhere in the C:\Users directory, ensure you have read, understood and applied the following:

“By default, Toolbox only has access to the C:\Users directory and mounts it into the VMs at /c/Users. If your project lives elsewhere or needs access to other directories on the host filesystem, you can add them, using the VirtualBox UI.”

Symlinks ¶

VirtualBox might not allow symlinks by default on other directories. This can however be fixed manually. Let’s assume You’ve added a shared folder D:/ to VirtualBox on d, you will then need to manually allow symlinks via VboxManage command:

First check if symlinks are disabled

host> VboxManage getextradata default enumerate

Key: VBoxInternal2/SharedFoldersEnableSymlinksCreate/d, Value: 0

The Value: 0 indicates that symlinks are not allowed. To enable it, do the folllowing:

VBoxManage setextradata default VBoxInternal2/SharedFoldersEnableSymlinksCreate/d 1

Now check again

host> VboxManage getextradata default enumerate

Key: VBoxInternal2/SharedFoldersEnableSymlinksCreate/d, Value: 1

The Value: 1 now indicates that symlinks are allowed.

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Find Docker Toolbox IP address¶

Table of Contents

Get IP address
What to do with it

Get IP address ¶

Open an environment prepared Terminal
Enter the following command to get the IP address of the Docker Toolbox virtual machine:
```
host> docker-machine ip default

192.168.99.100
```

The above example outputs 192.168.99.100, but this might be a different IP address on your machine.

See also

What to do with it ¶

The Docker Toolbox IP address is the address where the Devilbox intranet as well as all of its projects will be available at.

Use it to access the intranet via your browser (http://192.168.99.100 in this example)
Use it for manual DNS entries

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

SSH into Docker Toolbox¶

Table of Contents

Requirements
Manual
Automated

Requirements ¶

You shell must have an SSH client (the ssh command or equivalent).

See also

Manual ¶

Before going to use the automated approach, you should understand how to fetch all required information via the docker-machine command.

Gather all information ¶

Get active Toolbox machine name
```
host> docker-machine active
default
```

Print all information

host> docker-machine -D ssh default
Host : localhost
Port : 51701
User : docker
Key : .docker\machine\machines\default\id_rsa

Gather specific information ¶

Get active Toolbox machine name
```
host> docker-machine active
default
```

Get SSH username (Using machine name default from above)

host> docker-machine inspect default --format={{.Driver.SSHUser}}
docker

Get SSH public key (Using machine name default from above)

host> docker-machine inspect default --format={{.Driver.SSHKeyPath}}
.docker\machine\machines\default\id_rsa

Get local SSH port (Using machine name default from above)

host> docker-machine inspect default --format={{.Driver.SSHPort}}
51701

Get Docker Toolbox IP address (Using machine name default from above)
```
host> docker-machine ip default
192.168.99.100
```

SSH into Docker Toolbox ¶

Now with the above gathered information you can ssh into Docker Toolbox in two different ways:

via local port-forwarded ssh port (automatically forwarded by Docker Toolbox)

host> ssh -i .docker\machine\machines\default\id_rsa -p 51701 docker@127.0.0.1

via Docker Toolbox IP address

host> ssh -i .docker\machine\machines\default\id_rsa docker@192.168.99.100

Automated ¶

Instead of typing all of the above manually each time, you can also create a small bash script to automate this.

Create a file ssh-docker.sh and add the following to it:

ssh-docker.sh¶

#!/bin/bash
docker_machine_name=$(docker-machine active)
docker_ssh_user=$(docker-machine inspect $docker_machine_name --format={{.Driver.SSHUser}})
docker_ssh_key=$(docker-machine inspect $docker_machine_name --format={{.Driver.SSHKeyPath}})
docker_ssh_port=$(docker-machine inspect $docker_machine_name --format={{.Driver.SSHPort}})

ssh -i $docker_ssh_key -p $docker_ssh_port $docker_ssh_user@localhost

Run it:
```
host> bash ssh-docker.sh
```

See also

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

SSH port-forward on Docker Toolbox from host¶

Note

This is a Local SSH port-forward (ssh -L)

Table of Contents

Requirements
Overview
- General command
- Command example
Examples
- Make host-based MySQL available on Docker Toolbox
- Make host-based PgSQL available on Docker Toolbox

Requirements ¶

You host operating system must have an SSH server installed, up and running.

See also

Overview ¶

This is a local SSH port-forward (ssh -L). In other words, the Docker Toolbox machine will make a port locally available from somewhere else. Therefore the process must be initiated on the Docker Toolbox machine.

General command ¶

The following represents the general structure of a local ssh port-forward:

ssh -L <DockerToolbox_Port>:<HostOS_SRV_IP>:<HostOS_SRV_Port> <HostOS_SSH_USER>@<HostOS_SSH_IP>

`<DockerToolbox_Port>`	The port on the Docker Toolbox machine the service should be made available
`<HostOS_SRV_IP>`	The IP address on the host os, where the service is currently listening
`<HostOS_SRV_PORT>`	The port on the host os, where the service is bound to
`<HostOS_SSH_USER>`	The username of the host os SSH server for the connection
`<HostOS_SSH_IP>`	The IP address of the host at which the SSH server is reachable

Command example ¶

Making 127.0.0.1:10000 from host os available on 0.0.0.0:8080 on Docker Toolbox machine:

ssh -L 8080:127.0.0.1:10000 user@172.16.0.1

`8080`	Docker Toolbox should make the port available on itself on this port
`127.0.0.1`	The service currently listens on that IP address on the host os
`10000`	The service is currently bound to that port on the host os
`user`	The username of the host os SSH server for the connection
`172.16.0.1`	The IP address of the host at which the SSH server is reachable

Examples ¶

For this example we assume the following information:

Docker Toolbox IP address is 192.168.99.100
Host os IP address where SSH server is listening is 172.16.0.1
Host SSH username is user

Make host-based MySQL available on Docker Toolbox ¶

Gather the IP address on your host os where the SSH server is listening
SSH into the Docker Toolbox machine
Forward: 127.0.0.1:3306 from host os to 0.0.0.0:3306 on Docker Toolbox
```
toolbox> ssh -L 3306:127.0.0.1:3306 user@172.16.0.1
```

Make host-based PgSQL available on Docker Toolbox ¶

Gather the IP address on your host os where the SSH server is listening
SSH into the Docker Toolbox machine
Forward: 127.0.0.1:5432 from host os to 0.0.0.0:5432 on Docker Toolbox
```
toolbox> ssh -L 5432:127.0.0.1:5432 user@172.16.0.1
```

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

SSH port-forward on host to Docker Toolbox¶

Note

This is a Remote SSH port-forward (ssh -R)

Table of Contents

Requirements
Overview
- General command
- Command example
Examples
- Make host-based MySQL available on Docker Toolbox
- Make host-based PgSQL available on Docker Toolbox

Requirements ¶

You shell must have an SSH client (the ssh command or equivalent).

See also

Overview ¶

This is a remote SSH port-forward (ssh -R). In other words, the host os will make the port remotely availabl on the Docker Toolbox machine. Therefore the process must be initiated on the host os.

General command ¶

The following represents the general structure of a remote ssh port-forward:

ssh -R <DockerToolbox_Port>:<HostOS_SRV_IP>:<HostOS_SRV_Port> <DockerToolbox_SSH_USER>@<DockerToolbox_SSH_IP>

`<DockerToolbox_Port>`	The port on the Docker Toolbox machine the service should be made available
`<HostOS_SRV_IP>`	The IP address on the host os, where the service is currently listening
`<HostOS_SRV_PORT>`	The port on the host os, where the service is bound to
`<DockerToolbox_SSH_USER>`	The username of the host os SSH server for the connection
`<DockerToolbox_SSH_IP>`	The IP address of the host at which the SSH server is reachable

Command example ¶

Making 127.0.0.1:10000 from host os available on 0.0.0.0:8080 on Docker Toolbox machine:

ssh -R 8080:127.0.0.1:10000 docker@192.168.99.100

`8080`	Docker Toolbox should make the port available on itself on this port
`127.0.0.1`	The service currently listens on that IP address on the host os
`10000`	The service is currently bound to that port on the host os
`docker`	The username of the Docker Toolbox SSH server for the connection
`192.168.99.100`	The IP address of the Docker Toolbox at which the SSH server is reachable

Examples ¶

For this example we assume the following information:

Docker Toolbox IP address is 192.168.99.100
Docker Toolbox SSH username is docker

Make host-based MySQL available on Docker Toolbox ¶

Open a terminal on your host os
Forward: 127.0.0.1:3306 from host os to 0.0.0.0:3306 on Docker Toolbox
```
toolbox> ssh -R 3306:127.0.0.1:3306 docker@192.168.99.100
```

Make host-based PgSQL available on Docker Toolbox ¶

Open a terminal on your host os
Forward: 127.0.0.1:5432 from host os to 0.0.0.0:5432 on Docker Toolbox
```
toolbox> ssh -R 5432:127.0.0.1:5432 docker@192.168.99.100
```

Attention

You can now run different PHP versions per project: Release v3.0.0-beta-0.1

Open a terminal on MacOS¶

See also