Virtual host templates

Table of Contents

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 and are absolutely identical to what is shipped inside each Devilbox web server Docker container.

host> tree -L 1 cfg/vhost-gen/

cfg/vhost-gen/
├── apache22.yml-example
├── apache24.yml-example
├── nginx.yml-example
└── README.md

0 directories, 4 files

Note

Also note that nginx stable and nginx mainline share the same template as their configuration syntax is identical.

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.

Templates

Apache 2.2 template

apache22.yml
---

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


###
### Basic vHost skeleton
###
vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName   __VHOST_NAME__

      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
    </Directory>

  # Reverse Proxy (-r)
  rproxy: |
    # Define the vhost to reverse proxy
    ProxyRequests off
    ProxyPass __LOCATION__ __PROXY_PROTO://__PROXY_ADDR__:__PROXY_PORT__
    ProxyHTMLURLMap __PROXY_PROTO://__PROXY_ADDR__:__PROXY_PORT__ __LOCATION__
    <location __LOCATION__>
        ProxyPassReverse /
        SetOutputFilter  proxy-html
        ProxyHTMLURLMap  /      __LOCATION__
        ProxyHTMLURLMap  __LOCATION__  __LOCATION__
        RequestHeader    unset  Accept-Encoding
    </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__">
    __XDOMAIN_REQ__
    </Location>
    <Directory "__PATH____ALIAS__">
        Order allow,deny
        Allow from all
    </Directory>

  deny: |
    # Deny Definition
    <FilesMatch "__REGEX__">
        Order allow,deny
        Deny from all
    </FilesMatch>

  server_status: |
    # Status Page
    <Location __REGEX__>
        SetHandler server-status
        Order allow,deny
        Allow from all
    </Location>

  xdomain_request: |
    # Allow cross domain request from these hosts
    SetEnvIf Origin "__REGEX__" AccessControlAllowOrigin=$0
    Header add Access-Control-Allow-Origin %{AccessControlAllowOrigin}e env=AccessControlAllowOrigin
    Header always set Access-Control-Allow-Methods "POST, GET, OPTIONS, DELETE, PUT"
    Header always set Access-Control-Max-Age "0"
    Header always set Access-Control-Allow-Headers "x-requested-with, Content-Type, origin, authorization, accept, client-security-token"
    # 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
---

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


###
### Basic vHost skeleton
###
vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName   __VHOST_NAME__

      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)
  rproxy: |
    # Define the vhost to reverse proxy
    ProxyRequests off
    ProxyPass __LOCATION__ __PROXY_PROTO://__PROXY_ADDR__:__PROXY_PORT__
    ProxyHTMLURLMap __PROXY_PROTO://__PROXY_ADDR__:__PROXY_PORT__ __LOCATION__
    <location __LOCATION__>
        ProxyPassReverse /
        SetOutputFilter  proxy-html
        ProxyHTMLURLMap  /      __LOCATION__
        ProxyHTMLURLMap  __LOCATION__  __LOCATION__
        RequestHeader    unset  Accept-Encoding
    </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__">
    __XDOMAIN_REQ__
    </Location>
    <Directory "__PATH____ALIAS__">
        Order allow,deny
        Allow from all
        Require all granted
    </Directory>

  deny: |
    # Deny Definition
    <FilesMatch "__REGEX__">
        Order allow,deny
        Deny from all
    </FilesMatch>

  server_status: |
    # Status Page
    <Location __REGEX__>
        SetHandler server-status
        Order allow,deny
        Allow from all
        Require all granted
    </Location>

  xdomain_request: |
    # Allow cross domain request from these hosts
    SetEnvIf Origin "__REGEX__" AccessControlAllowOrigin=$0
    Header add Access-Control-Allow-Origin %{AccessControlAllowOrigin}e env=AccessControlAllowOrigin
    Header always set Access-Control-Allow-Methods "POST, GET, OPTIONS, DELETE, PUT"
    Header always set Access-Control-Max-Age "0"
    Header always set Access-Control-Allow-Headers "x-requested-with, Content-Type, origin, authorization, accept, client-security-token"
    # 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
---

# 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____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)
  rproxy: |
    # Define the vhost to reverse proxy
    location __LOCATION__ {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        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
    if ( $http_origin ~* (__REGEX__) ) {
        add_header "Access-Control-Allow-Origin" "$http_origin";
        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
        add_header 'Access-Control-Allow-Headers' 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Content-Range,Range';
        add_header 'Access-Control-Expose-Headers' 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Content-Range,Range';
        add_header 'Access-Control-Max-Age' 0;
        return 200;
    }