There are only four things you can configure on your host computer.
#### 1.1 The devilbox `.env` file
All docker-compose configuration is done inside the `.env` file which simply defines key-value variables parsed to `docker-compose.yml`.
First thing to do after cloning this repository is creating this file from the `env-example`:
```shell
$ cp env-example .env
```
When you update the devilbox git directory, you should always check if `env-example` introduces new configuration options. You can do that by comparing the `env-example` file with your current `.env` file.
```shell
$ vimdiff env-example .env
```
You can get more information here:
> [What is the `.env` file?](https://docs.docker.com/compose/env-file/)
#### 1.2 The devilbox `cfg/` directory
Inside the devilbox root directory you will find a foder called `cfg/`. This will contain subdirectories in the form of `<SERVICE>-<VERSION>`. Those folders will be mounted into the appropriate location into the respective docker container in order to overwrite service configuration.
Currently only MySQL/MariaDB and PHP/HHVM overrides are supported.
The folder structure looks like this:
```
cfg/
hhvm-latest/
mariadb-10.0/
mariadb-10.1/
mariadb-10.2/
mariadb-10.3/
mariadb-5.5/
mysql-5.5/
mysql-5.6/
mysql-5.7/
mysql-8.0/
php-fpm-5.4/
php-fpm-5.5/
php-fpm-5.6/
php-fpm-7.0/
php-fpm-7.1/
php-fpm-7.2/
```
Each of the folders will contain an example file in the following format:
```
devilbox-custom.<ext>-example
```
Only files which have the correct file extensions will be read, all others such as `*.<ext>-example` will be ignored.
* Valid PHP config extension: `.ini`
* Valid MySQL config extension: `.cnf`
#### 1.3 The operating system `hosts` file
On Linux and OSX your hosts file is located at `/etc/hosts` on Windows it will be at `C:\Windows\System32\drivers\etc`. Use this file to setup custom DNS entries if you are not using Auto-DNS.
Read up on it below at `/etc/hosts` or `Auto-DNS` section.
#### 1.4 The operating system `resolv.conf` file
This file is used to add the devilbox DNS server for Auto-DNS.
Read up on it below at `/etc/hosts` or `Auto-DNS` section.
This is the base path that will be prepended to all mount paths specified in `.env`.
You will usually not need to change this value..
#### 2.3 Host computer listening address
| `.env` file variable name | Default | Note |
|---------------------------|---------|------|
| LOCAL_LISTEN_ADDRESS | `127.0.0.1:` | Address for every service to listen on the Docker host.<br/>Pay attention to the **`:`** after the IP address |
This determines the Host address your webserver and all other daemons should listen on.
In case it is not `127.0.0.1` (because you are using a VirtualBox Docker setup) change it to the IP address of the VirtualBox host. Otherwise you will not need to change this value.
1. When you remove it completely, it will listen on all interfaces.
2. When you use specific address, you must add a **`:`** at the end.
You can for example change it to `0.0.0.0:` or make it empty in order to listen on all interfaces. This enables it for other people inside your network to access the devilbox. Or you can even install the devilbox on a different computer and access it remotely.
| TLD_SUFFIX | `loc` | Domain suffix for all your project. Can also be a subdomain such `work.loc` |
Each project will be served by `http://<project-folder>.<TLD_SUFFIX>`. If you want to change the default `loc` domain suffix to something else such as local, adjust this variable. Here are a few examples:
| Project Folder | TLD_SUFFIX | URL |
|----------------|------------|-----|
| my-cake | loc | http://my-cake.loc |
| my-cake | local | http://my-cake.local |
| my-cake | dev | http://my-cake.dev |
| my-cake | work.loc | http://my-cake.work.loc |
| test | foo | http://test.foo |
| project1 | bar | http://project1.bar |
The above examples should make it clear enough.
#### 3.2 Project path
| `.env` file variable name | Default | Note |
|---------------------------|---------|------|
| HOST_PATH_HTTPD_DATADIR | `./data/www` | Can be absolute or relative path. A relative path starts inside the devilbox git directory. |
This is the file system path on your host computer which will hold the Project Folders.
| TIMEZONE | `Europe/Berlin`| Set timezone of the Docker container |
Use this variable to control the timezone of the container.
**Note:** This currently only works on the devilbox self-provided container:
* DNS
* MySQL/MariaDB
* PHP/HHVM
* Apache/Nginx
The official container do not support this setting.
##### 4.1.1 User id
| `.env` file variable name | Default | Note |
|---------------------------|---------|------|
| NEW_UID | `1000`| Change the Docker containers user id (uid) |
This setting is used to change the user id of the PHP/HHVM container to the one you specify. As you will work insisde the PHP/HHVM container, you will have to set it to the same user id of your Host computers user id. It will make sure that files created inside the container have the same access permissions as outside the container.
To find out your user id, type the following on your Host system:
```shell
$ id
```
**Note:** If your Host computers user id and the containers user id do not match, files will have different access rights inside and outside which might result in permission errors like `access denied`. So make sure to set this value.
**Note:** Files created by the webserver such as uploads, tmp and cache files are still created by the webservers user id and you will probably have to `chmod` them. This issues will be addressed shortly and you will also be able to change the uid/gid of the webserver in the next devilbox release.
##### 4.1.2 Group id
| `.env` file variable name | Default | Note |
|---------------------------|---------|------|
| NEW_GID | `1000`| Change the Docker containers group id (gid) |
This setting is used to change the group id of the PHP/HHVM container to the one you specify. As you will work insisde the PHP/HHVM container, you will have to set it to the same group id of your Host computers group id. It will make sure that files created inside the container have the same access permissions as outside the container.
To find out your group id, type the following on your Host system:
```shell
$ id
```
**Note:** If your Host computers group id and the containers group id do not match, files will have different access rights inside and outside which might result in permission errors like `access denied`. So make sure to set this value.
**Note:** Files created by the webserver such as uploads, tmp and cache files are still created by the webservers group id and you will probably have to `chmod` them. This issues will be addressed shortly and you will also be able to change the uid/gid of the webserver in the next devilbox release.
| PHP_SERVER | `php-fpm-7.0`| Change the PHP Docker container |
1. Open the `.env` file in your favorite editor
2. Find the `PHP_SERVER=` block
You can choose between different PHP versions and HHVM.
**Important:** Keep in mind that if you have a custom php.ini config at `./cfg/php-*/`, it is only effective for one version. Custom php configurations are separted per version.
| PHP_XDEBUG_ENABLE | `1` | Enable Xdebug for PHP |
| PHP_XDEBUG_REMOTE_PORT | `9000` | PHP Xdebugs remote port - where your editor/IDE is receiving Xdebug data |
| PHP_XDEBUG_REMOTE_HOST | `192.168.0.215` | PHP Xdebugs remote IP address - where your editor/IDE is listening for Xdebug connections (Make sure to change this to the IP of your Docker Host |
Xdebug is turned on by default and also using the official Xdebug default port. The only thing you will have to adjust is the Xdebug remote host address so that your editor/IDE can actually receive Xdebug data.
`php.ini` settings can be configured for each PHP/HHVM version separately. Container-based configuration is done inside the `./cfg/` directory.
```shell
$ ls -l ./cfg/ | grep -E 'php|hhvm'
drwxrwxr-x 2 cytopia 4096 Jun 21 08:47 hhvm-latest/
drwxrwxr-x 2 cytopia 4096 Jun 21 08:43 php-fpm-5.4/
drwxrwxr-x 2 cytopia 4096 Jun 21 08:43 php-fpm-5.5/
drwxrwxr-x 2 cytopia 4096 Jun 21 08:43 php-fpm-5.6/
drwxrwxr-x 2 cytopia 4096 Jun 21 08:44 php-fpm-7.0/
drwxrwxr-x 2 cytopia 4096 Jun 21 08:44 php-fpm-7.1/
drwxrwxr-x 2 cytopia 4096 Jun 21 08:44 php-fpm-7.2/
```
Each of the above folders will hold an example configuration file named `devilbox-custom.ini-example` which shows some example settings but will **not have** any effect yet. Only files ending by **`.ini`** will be sourced and applied, so you must copy it (or create a new file) to something that ends by `*.ini`.
In order to edit settings for PHP 5.6, go into that folder, copy the example file and adjust ist:
HHVM can just be configured as all other PHP versions. However it has a special option to change between **PHP-5.6** mode and **PHP-7** mode. This example is addressed in `cfg/hhvm-latest/devilbox.ini-example`.
```shell
$ cat cfg/hhvm-latest/devilbox.ini-example
```
```ini
; Use PHP 5.6 or PHP 7 mode for HHVM
; PHP 5.6 Mode
;hhvm.php7.all = 0
; PHP 7 Mode (default)
;hhvm.php7.all = 1
```
By default, HHVM is using **PHP-7** mode, you can change this setting to **PHP-5.6** by enabling `hhvm.php7.all = 0`.
**Note:** You must then also copy the file to something that ends by `*.ini`.
| HTTPD_SERVER | `nginx-stable`| Change the Httpd Docker container |
1. Open the `.env` file in your favorite editor
2. Find the `HTTPD_SERVER=` block
You can choose between Apache and Nginx in different version. All of them are configured to work the same, there is nothing to worry about when changing them.
| MYSQL_SERVER | `mariadb-10.1`| Change the MySQL Docker container |
1. Open the `.env` file in your favorite editor
2. Find the `MYSQL_SERVER=` block
**Important:** Each version has a different data directory. This is a security precautions. Imagine you startup MySQL 5.5 for the first time. New databases will be created. Now you startup MySQL 8. All existing databases would be upgraded to work flawlessly with MySQL 8, however this is not downwards compatible. So by startup up MySQL 5.5 again, it would say the database is corrupt.
| MYSQL_ROOT_PASSWORD | `` | Root user password for MySQL |
If you start a MySQL container for the first time, it will setup MySQL itself with the 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.
> The general query log is a general record of what mysqld is doing. The server writes information to this log when clients connect or disconnect, and it logs each SQL statement received from clients. The general query log can be very useful when you suspect an error in a client and want to know exactly what the client sent to mysqld.
This logging behavior is turned on by default in order to provide all information during development. Set it to `0` to turn it off.
| HOST_PORT_MYSQL | `3306`| Host computer listening port for the MySQL server (MySQL or MariaDB) |
By default the MySQL server will listen on port 3306 (on your Host computer). You can change this to any other port (in case port 3306 is already taken).
If you also want to change the listening address (default: 127.0.0.1) to something else, see above or search this document for `LOCAL_LISTEN_ADDRESS`.
| HOST_PATH_MYSQL_DATADIR | `./data/mysql` | Can be absolute or relative path. A relative path starts inside the devilbox git directory. |
This is the file system path on your host computer which will hold the MySQL data.
**Note:** A sub directory will be created inside this path for each MySQL version. This separation is there to make sure that higher versions do not upgrade the database irrevocably. (e.g.: MySQL 8.0 can read data from MySQL 5.5, but not the other way round).
The automatic folder structure will look something like this:
`my.cnf` settings can be configured for each MySQL/MariaDB version separately. Container-based configuration is done inside the `./cfg/` directory.
```shell
$ ls -l ./cfg/ | grep -E 'mysql|maria'
drwxrwxr-x 2 cytopia 4096 Jun 1 08:44 mariadb-10.0/
drwxrwxr-x 2 cytopia 4096 Jun 1 08:44 mariadb-10.1/
drwxrwxr-x 2 cytopia 4096 Jun 1 08:44 mariadb-10.2/
drwxrwxr-x 2 cytopia 4096 Jun 1 08:44 mariadb-10.3/
drwxrwxr-x 2 cytopia 4096 Jun 13 13:18 mysql-5.5/
drwxrwxr-x 2 cytopia 4096 Jun 1 08:44 mysql-5.6/
drwxrwxr-x 2 cytopia 4096 Jun 1 08:44 mysql-5.7/
drwxrwxr-x 2 cytopia 4096 Jun 1 08:44 mysql-8.0/
```
Each of the above folders will hold an example configuration file named `devilbox-custom.cnf-example` which shows some example settings but will **not have** any effect yet. Only files ending by **`.cnf`** will be sourced and applied, so you must copy it (or create a new file) to something that ends by `*.cnf`.
In order to edit settings for MySQL 5.5, go into that folder, copy the example file and adjust ist:
**Important:** Each version has a different data directory. This is a security precautions. Imagine you startup PostgreSQL 9.1 for the first time. New databases will be created. Now you startup PostgreSQL 9.6. All existing databases would be upgraded to work flawlessly with PostgreSQL 9.6, however this is not downwards compatible. So by startup up PostgreSQL 9.1 again, it would say the database is corrupt.
| PGSQL_ROOT_USER | `postgres` | Root username for PostgreSQL |
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.
| PGSQL_ROOT_PASSWORD | `` | Root user password for PostgreSQL |
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.
| HOST_PORT_PGSQL | `5432`| Host computer listening port for the PostgreSQL server |
By default the PostgreSQL server will listen on port 5432 (on your Host computer). You can change this to any other port (in case port 5432 is already taken).
If you also want to change the listening address (default: 127.0.0.1) to something else, see above or search this document for `LOCAL_LISTEN_ADDRESS`.
This is the file system path on your host computer which will hold the PostgreSQL data.
**Note:** A sub directory will be created inside this path for each PostgreSQL version. This separation is there to make sure that higher versions do not upgrade the database irrevocably. (e.g.: PostgreSQL 9.6 can read data from PostgreSQL 9.1, but maybe not the other way round).
The automatic folder structure will look something like this:
| HOST_PORT_REDIS | `6379`| Host computer listening port for the Redis server |
By default the Redis server will listen on port 6379 (on your Host computer). You can change this to any other port (in case port 6379 is already taken).
If you also want to change the listening address (default: 127.0.0.1) to something else, see above or search this document for `LOCAL_LISTEN_ADDRESS`.
| HOST_PORT_MEMCD | `11211`| Host computer listening port for the Memcached server |
By default the Memcached server will listen on port 11211 (on your Host computer). You can change this to any other port (in case port 11211 is already taken).
If you also want to change the listening address (default: 127.0.0.1) to something else, see above or search this document for `LOCAL_LISTEN_ADDRESS`.
**Important:** Each version has a different data directory. This is a security precautions. Imagine you startup MongoDB 2.8 for the first time. New databases will be created. Now you startup MongoDB 3.5. All existing databases would be upgraded to work flawlessly with MongoDB 3.5, however this is not downwards compatible. So by startup up MongoDB 2.8 again, it would say the database is corrupt.
| HOST_PORT_MONGO | `27017`| Host computer listening port for the MongoDB server |
By default the Memcached server will listen on port 27017 (on your Host computer). You can change this to any other port (in case port 27017 is already taken).
If you also want to change the listening address (default: 127.0.0.1) to something else, see above or search this document for `LOCAL_LISTEN_ADDRESS`.
This is the file system path on your host computer which will hold the MongoDB data.
**Note:** A sub directory will be created inside this path for each MongoDB version. This separation is there to make sure that higher versions do not upgrade the database irrevocably. (e.g.: MongoDB 3.5 can read data from MongoDB 2.8, but maybe not the other way round).
The automatic folder structure will look something like this:
| BIND_DNS_RESOLVER | `8.8.8.8,8.8.4.4` | Comma separated list of IP addresses of DNS servers. By default using Google's DNS server as they are pretty fast. |
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.
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.
| HOST_PORT_BIND | `1053`| Host computer listening port for the Bind DNS server |
By default the Bind DNS server will listen on port 1053 (on your Host computer). You can change this to any other port (in case port 1053 is already taken)
If you also want to change the listening address (default: 127.0.0.1) to something else, see above or search this document for `LOCAL_LISTEN_ADDRESS`.
| DNS_CHECK_TIMEOUT | `1` | DNS timeout in seconds for unresolvable Domains |
`TLD_SUFFIX` domains are checked if they are set in the host computer /etc/hosts or available via attached DNS server. Timeout is done on vhosts.php (intranet) via ajax calls. In order to keep performance, set this to a low value. DNS checks might not succeed in time on slow machines. If DNS is valid, but timeout is expired, set this to a higher value.
`DNS_CHECK_TIMEOUT` value is how many seconds to time out.
