devilbox/docs/vhost-gen/example-add-subdomains.rst

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

local

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	com	http://my-test.com
www.my-test	com	http://www.my-test.com
t2.www.my-test	com	http://t2.www.my-test.com

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
env_tld_suffix	loc
env_httpd_docroot_dir	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:

• http://my-test.loc
• http://api.my-test.loc
• http://www.my-test.loc

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

customize_specific_virtual_host Ensure you have read and understand how to customize your virtual host with vhost-gen. env_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: custom_vhost_apply_vhost_gen_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:

• work_inside_the_php_container
• available_tools

Prerequisite

Let's assume the following settings.

Variable	Value
Devilbox path	/home/user/devilbox
env_httpd_template_dir	.devilbox
env_httpd_datadir	./data/www
env_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 templates/vhost-gen/* ./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: getting_started_create_your_first_project_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).

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 another ServerName directive:

vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName   __VHOST_NAME__
      ServerName   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 tutorial_adding_sub_domains_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: getting_started_create_your_first_project_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).

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 another ServerName directive which does catch-all:

vhost: |
  <VirtualHost __DEFAULT_VHOST__:__PORT__>
      ServerName   __VHOST_NAME__
      ServerName   *.__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 tutorial_adding_sub_domains_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: tutorial_adding_sub_domains_apache_22

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

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:

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 tutorial_adding_sub_domains_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: getting_started_create_your_first_project_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).

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:

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 tutorial_adding_sub_domains_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:

1. Restart the Devilbox
2. 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

1. Template files are copied from templates/vhost-gen/* to your project template dir (as specified in .env via HTTPD_TEMPLATE_DIR)
2. Ensure the vhost-gen yaml files are valid (No tab characters)
3. 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