devilbox/docker-nginx-mainline
This image is based on the official Nginx Docker image and extends it with the ability to have virtual hosts created automatically, as well as adding SSL certificates when creating new directories. For that to work, it integrates two tools that will take care about the whole process: watcherd and vhost-gen.
From a users perspective, you mount your local project directory into the container under /shared/httpd
. Any directory then created in your local project directory wil spawn a new virtual host by the same name. Additional settings such as custom server names, PHP-FPM or even different Apache templates per project are supported as well.
Docker Hub | Upstream Project |
---|---|
![]() |
Apache 2.2 | Apache 2.4 | Nginx stable | Nginx mainline
- Automated virtual hosts can be enabled by providing
-e MASS_VHOST_ENABLE=1
. - You should mount a local project directory into the Docker under
/shared/httpd
(-v /local/path:/shared/httpd
). - You can optionally specify a global server name suffix via e.g.:
-e MASS_VHOST_TLD=.loc
- You can optionally specify a global subdirectory from which the virtual host will servve the documents via e.g.:
-e MASS_VHOST_DOCROOT=www
- Allow the Docker to expose its port via
-p 80:80
. - Have DNS names point to the IP address the container runs on (e.g. via
/etc/hosts
)
With the above described settings, whenever you create a local directory under your projects dir
such as /local/path/mydir
, there will be a new virtual host created by the same name
http://mydir
. You can also specify a global suffix for the vhost names via
-e MASS_VHOST_TLD=.loc
, afterwards your above created vhost would be reachable via
http://mydir.loc
.
Just to give you a few examples:
Assumption: /local/path
is mounted to /shared/httpd
Directory | MASS_VHOST_DOCROOT |
MASS_VHOST_TLD |
Serving from (*) | Via |
---|---|---|---|---|
work1/ | htdocs/ | /local/path/work1/htdocs | http://work1 | |
work1/ | www/ | /local/path/work1/www | http://work1 | |
work1/ | htdocs/ | .loc | /local/path/work1/htdocs | http://work1.loc |
work1/ | www/ | .loc | /local/path/work1/www | http://work1.loc |
(*) This refers to the directory on your host computer
Assumption: /tmp
is mounted to /shared/httpd
Directory | MASS_VHOST_DOCROOT |
MASS_VHOST_TLD |
Serving from (*) | Via |
---|---|---|---|---|
api/ | htdocs/ | /tmp/api/htdocs | http://api | |
api/ | www/ | /tmp/api/www | http://api | |
api/ | htdocs/ | .test.com | /tmp/api/htdocs | http://api.test.com |
api/ | www/ | .test.com | /tmp/api/www | http://api.test.com |
(*) This refers to the directory on your host computer
You would start it as follows:
docker run -it \
-p 80:80 \
-e MASS_VHOST_ENABLE=1 \
-e MASS_VHOST_DOCROOT=www \
-e MASS_VHOST_TLD=.loc \
-v /local/path:/shared/httpd \
devilbox/nginx-mainline
Each virtual host is generated from templates by vhost-gen. As vhost-gen
is really flexible and allows combining multiple templates, you can copy and alter an existing template and then place it in a subdirectory of your project folder. The subdirectory is specified by MASS_VHOST_TPL
.
Assumption: /local/path
is mounted to /shared/httpd
Directory | MASS_VHOST_TPL |
Templates are then read from (*) |
---|---|---|
work1/ | cfg/ | /local/path/work1/cfg/ |
api/ | cfg/ | /local/path/api/cfg/ |
work1/ | conf/ | /local/path/work1/conf/ |
api/ | conf/ | /local/path/api/conf/ |
(*) This refers to the directory on your host computer
The default virtual host can also be overwritten with a custom template. Use MAIN_VHOST_TPL
variable in order to set the subdirectory to look for template files.
PHP-FPM is not included inside this Docker container, but can be enabled to contact a remote PHP-FPM server. To do so, you must enable it and at least specify the remote PHP-FPM server address (hostname or IP address). Additionally you must mount the data dir under the same path into the PHP-FPM docker container as it is mounted into the web server.
Note: When PHP-FPM is enabled, it is enabled for the default virtual host as well as for all other automatically created mass virtual hosts.
If you only want to server you custom projects and don't need the default virtual host, you can disable it by -e MAIN_VHOST_ENABLE=0
.
This Docker container adds a lot of injectables in order to customize it to your needs. See the table below for a detailed description.
PHP_FPM_SERVER_ADDR
is required when enabling PHP FPM.
Variable | Type | Default | Description |
---|---|---|---|
DEBUG_ENTRYPOINT | int | 0 |
Show settings and shell commands executed during startup. Values: 0 : Off1 : Show settings2 : Show settings and commands |
DEBUG_RUNTIME | bool | 0 |
Be verbose during runtime. Value: 0 or 1 |
DOCKER_LOGS | bool | 0 |
When set to 1 will redirect error and access logs to Docker logs (stderr and stdout ) instead of file inside container.Value: 0 or 1 |
TIMEZONE | string | UTC |
Set docker OS timezone. (Example: Europe/Berlin ) |
NEW_UID | int | 101 |
Assign the default Nginx user a new UID. This is useful if you you mount your document root and want to match the file permissions to the one of your local user. Set it to your host users uid (see id for your uid). |
NEW_GID | int | 101 |
This is useful if you you mount your document root and want to match the file permissions to the one of your local user group. Set it to your host user groups gid (see id for your gid). |
PHP_FPM_ENABLE | bool | 0 |
Enable PHP-FPM for the default vhost and the mass virtual hosts. |
PHP_FPM_SERVER_ADDR | string | `` | IP address or hostname of remote PHP-FPM server. Required when enabling PHP. |
PHP_FPM_SERVER_PORT | int | 9000 |
Port of remote PHP-FPM server |
PHP_FPM_TIMEOUT | int | 180 |
Timeout in seconds to upstream PHP-FPM server |
Variable | Type | Default | Description |
---|---|---|---|
MAIN_VHOST_ENABLE | bool | 1 |
By default there is a standard (catch-all) vhost configured to accept requests served from /var/www/default/htdocs . If you want to disable it, set the value to 0 .Note:The htdocs dir name can be changed with MAIN_VHOST_DOCROOT . See below. |
MAIN_VHOST_SSL_TYPE | string | plain |
|
MAIN_VHOST_SSL_GEN | bool | 0 |
0 : Do not generate an ssl certificate1 : Generate self-signed certificate automatically |
MAIN_VHOST_SSL_CN | string | localhost |
Comma separated list of CN names for SSL certificate generation (The domain names by which you want to reach the default server) |
MAIN_VHOST_DOCROOT | string | htdocs |
This is the directory name appended to /var/www/default/ from which the default virtual host will serve its files.Default: /var/www/default/htdocs Example: MAIN_VHOST_DOCROOT=www Doc root: /var/www/default/www |
MAIN_VHOST_TPL | string | cfg |
Directory within th default vhost base path (/var/www/default ) to look for templates to overwrite virtual host settings. See vhost-gen for available template files.Resulting default path: /var/www/default/cfg |
MAIN_VHOST_STATUS_ENABLE | bool | 0 |
Enable httpd status page. |
MAIN_VHOST_STATUS_ALIAS | string | /httpd-status |
Set the alias under which the httpd server should serve its status page. |
Variable | Type | Default | Description |
---|---|---|---|
MASS_VHOST_ENABLE | bool | 0 |
You can enable mass virtual hosts by setting this value to 1 . Mass virtual hosts will be created for each directory present in /shared/httpd by the same name including a top-level domain suffix (which could also be a domain+tld). See MASS_VHOST_TLD for how to set it. |
MASS_VHOST_SSL_TYPE | string | plain |
|
MASS_VHOST_SSL_GEN | bool | 0 |
0 : Do not generate an ssl certificate1 : Generate self-signed certificate automatically |
MASS_VHOST_TLD | string | .loc |
This string will be appended to the server name (which is built by its directory name) for mass virtual hosts and together build the final domain. Default: <project>.loc Example: Path: /shared/httpd/temp MASS_VHOST_TLD=.lan Server name: temp.lan Example: Path: /shared/httpd/api MASS_VHOST_TLD=.example.com Server name: api.example.com |
MASS_VHOST_DOCROOT | string | htdocs |
This is a subdirectory within your project dir under each project from which the web server will serve its files./shared/httpd/<project>/$MASS_VHOST_DOCROOT/ Default: /shared/httpd/<project>/htdocs/ |
MASS_VHOST_TPL | string | cfg |
Directory within your new virtual host to look for templates to overwrite virtual host settings. See vhost-gen for available template files./shared/httpd/<project>/$MASS_VHOST_TPL/ Resulting default path: /shared/httpd/<project>/cfg/ |
Docker | Description |
---|---|
/etc/httpd-custom.d | Mount this directory to add outside configuration files (*.conf ) to Nginx |
/var/www/default | Nginx default virtual host base path (contains by default htdocs/ and cfg/ |
/shared/httpd | Nginx mass virtual host root directory |
/etc/vhost-gen.d | vhost-gen directory for custom templates. Copy and customize nginx.yml into this mounted directory for global vhost customizations |
Docker | Description |
---|---|
80 | HTTP listening Port |
443 | HTTPS listening Port |
Mount your local directort ~/my-host-www
into the docker and server those files.
Note: Files will be server from ~/my-host-www/htdocs
.
$ docker run -d -p 80:80 -v ~/my-host-www:/var/www/default -t devilbox/nginx-mainline
Note, for this to work, the ~/my-host-www
dir must be mounted into the Nginx Docker as well as into the php-fpm docker.
You can also attach other PHP-FPM version: PHP-FPM 5.4, PHP-FPM 5.5, PHP-FPM 5.6, PHP-FPM 7.0, PHP-FPM 7.1, PHP-FPM 7.2 or HHVM.
Each PHP-FPM docker also has the option to enable Xdebug and more, see their respective Readme files for futher settings.
# Start the PHP-FPM docker, mounting the same diectory
$ docker run -d -p 9000 -v ~/my-host-www:/var/www/default --name php cytopia/php-fpm-5.6
# Start the Nginx Docker, linking it to the PHP-FPM docker
$ docker run -d \
-p 80:80 \
-v ~/my-host-www:/var/www/default \
-e PHP_FPM_ENABLE=1 \
-e PHP_FPM_SERVER_ADDR=php \
-e PHP_FPM_SERVER_PORT=9000 \
--link php \
-t devilbox/nginx-mainline
Same as above, but also add a MySQL docker and link it into Nginx.
# Start the MySQL docker
$ docker run -d \
-p 3306:3306 \
-e MYSQL_ROOT_PASSWORD=my-secret-pw \
--name mysql \
-t cytopia/mysql-5.5
# Start the PHP-FPM docker, mounting the same diectory.
# Also make sure to
# forward the remote MySQL port 3306 to 127.0.0.1:3306 within the
# PHP-FPM docker in order to be able to use `127.0.0.1` for mysql
# connections from within the php docker.
$ docker run -d \
-p 9000:9000 \
-v ~/my-host-www:/var/www/default \
-e FORWARD_PORTS_TO_LOCALHOST=3306:mysql:3306 \
--name php \
cytopia/php-fpm-5.6
# Start the Nginx Docker, linking it to the PHP-FPM docker
$ docker run -d \
-p 80:80 \
-v ~/my-host-www:/var/www/default \
-e PHP_FPM_ENABLE=1 \
-e PHP_FPM_SERVER_ADDR=php \
-e PHP_FPM_SERVER_PORT=9000 \
--link php \
--link mysql \
-t devilbox/nginx-mainline
Have a look at the devilbox for a fully-customizable docker-compose variant.
It offers pre-configured mass virtual hosts and an intranet.
It allows any of the following combinations:
- PHP 5.4, PHP 5.5, PHP 5.6, PHP 7.0, PHP 7.1 and HHVM
- MySQL 5.5, MySQL 5.6, MySQL 5.7, MariaDB 5 and MariaDB 10
- Apache 2.2, Apache 2.4, Nginx stable and Nginx mainline
- And more to come...
nginx version: nginx/1.15.5