Understanding domain groups, vhosts and subdomains

With MageStack, there are different levels used within the directory structure to be used for different purposes. We refer to these as domain groups, vhosts and subdomains

For example, a typical path to a LIVE directory would be,

|-------| |-----------|---|
| | |
domain group | |
vhost |

Domain group

A domain group is the wrapper for all of the vhosts (virtual hosts) within it. It runs as an isolated PHP process and an isolated Nginx process - with its own independent log settings and its own thresholds.

A vhost within a domain group cannot see any files outside of its domain group, the highest-level directory it can traverse up to is the domain group directory itself and no higher.

Domain groups are used to completely isolate a website from another, they cannot access each others files, they have their own PHP processes and their own resource limits.

You can find a full guide on how to create and manage the domain groups on your stack

Examples of use

  • Agency reseller hosting, to separate different client Magento stores from each other and control the resources of each
  • To isolate different websites completely from each other
  • To isolate staging/development/live stores from each other, so that they cannot access each others codebase (at all)

Virtual host (vhost)

A virtual host (vhost) is used as a wrapper for the domain itself, it can be the top-level domain, or a sub-level of a top-level domain.

Virtual hosts have their own configurable Nginx rewrite and configuration files, the configuration files used for that top-level domain is shared amongst all of its subdomains.

Virtual hosts do not have to be a top-level domain (eg. example.com), they can also be a sub-level domain of that (eg. dev.example.com). This is useful when you need a separate Nginx configuration file for a subdomain from that of the top-level domain - without the need to use conditional statements. There is no limit to the depth of a virtual host domain (eg. my.test.dev.example.com).

Virtual hosts can access other virtual hosts' directory contents (within the same domain group).

You can find a full guide on how to create and manage the vhosts on your stack

Once a virtual host has been created, you can use relative symlinks to point to another virtualhost for the whole virtual host, Nginx configuration files, or just a subdomain within it.

Examples of use

  • Multi-store Magento installations that require their own directory roots per domain, but still share common files/directories
  • Used when a dedicated IP or SSL certificate is a requirement
  • To allow easier Nginx configuration of subdomains (by making a subdomain a vhost instead)
  • Development/staging websites that need to share resources with another website, that may need to be password protected, or have their own Nginx configuration file


A subdomain is merely a subfolder of a top-level domain, they are created on the fly and require no server-side changes for them to take effect. You can merely create a new directory and it will work instantly.

Subdomains will inherit the Nginx rewrite and configuration rules from the top-level domain. If you need to make specific rules for a subdomain, you can either use conditional statements for the $host or separate the subdomain into a virtual host instead.

! Subdomains can be created on-the-fly simply by creating the directory

You can use relative symlinks (Eg. ln -s http media) to point subdomains to different locations.

Examples of use

  • Creating quick subdomains of a domain without requiring Nginx reload
  • Development/staging websites that need to share resources with another website