Creating new templates for Nginx/Apache in HestiaCP

HestiaCP is an open-source server management panel that lets you configure different applications on your server. When you add a new website in HestiaCP, you need to configure a template for Nginx and another for Apache. These templates define the configuration that will be loaded for the website, and different templates are available for each service.

For example, the following templates are available for Nginx:

• caching: Nginx template with caching configured.
• default: Default template for Nginx.
• hosting: Template similar to caching but with symbolic links disabled.

Sometimes you may need a configuration that differs from the default. For example, to configure a CMS plugin or a technology such as Laravel, Symfony or NodeJS.

For your website to work correctly in HestiaCP, you will need to create a new template and add the changes required for it to work properly.

Below, we explain how to create new templates, configure them and apply them to your website.

Creating a new template

To create a new template, you need to connect to the server via SSH, as this cannot be done from the HestiaCP interface. Once you have accessed your server, go to the following path, where all the templates are located:

cd /usr/local/hestia/data/templates/web

Here you will find the following templates:

• Apache2: All templates for the web server.
• Nginx: All templates for the web proxy.
• Awstats: Templates for web statistics.
• PHP-FPM: Templates for selecting the PHP version.
• suspend: Template used when you suspend a domain.
• skel: Documents for public_html and HTTP errors.

If you need to create a new template for Nginx, we recommend making a copy of the templates default.tpl and default.stpl. The .tpl template will be used for HTTP and the .stpl template for HTTPS.

For example, if you want to make an Nginx template for a website using NodeJS, you can create the following templates:

cp /usr/local/hestia/data/templates/web/nginx/default.tpl /usr/local/hestia/data/templates/web/nginx/nodejs.tpl
cp /usr/local/hestia/data/templates/web/nginx/default.stpl /usr/local/hestia/data/templates/web/nginx/nodejs.stpl

The final result will look like this:

root@hestiacp:/usr/local/hestia/data/templates/web/nginx# ls -lat
total 56
drwxr-xr-x 3 root root 4096 Sep 16 10:15 .
-rw-r--r-- 1 root root 1505 Sep 16 10:15 nodejs.stpl
-rw-r--r-- 1 root root 1264 Sep 16 10:15 nodejs.tpl

If you need to create a different template, create it with any name you like:

cp /usr/local/hestia/data/templates/web/nginx/default.tpl /usr/local/hestia/data/templates/web/nginx/[NOMBRE_PLANTILLA].tpl
cp /usr/local/hestia/data/templates/web/nginx/default.stpl /usr/local/hestia/data/templates/web/nginx/[NOMBRE_PLANTILLA].stpl

Now, if you go to HestiaCP, you will see that it already appears in the list:

If, for example, you need to make a template for Apache, the process is the same:

cp /usr/local/hestia/data/templates/web/apache2/default.tpl /usr/local/hestia/data/templates/web/apache2/[NOMBRE_PLANTILLA].tpl
cp /usr/local/hestia/data/templates/web/apache2/default.stpl /usr/local/hestia/data/templates/web/apache2/[NOMBRE_PLANTILLA].stpl

Configuring your template

The next step is to adapt the Nginx/Apache configuration for your template. First, however, bear in mind that these templates use variables that you need to understand and take into account when applying them in your configuration.

For example, to specify the directory where a website is located in Nginx, use the root parameter as follows:

root %home%/%user%/web/%domain%/public_html;

Here, %home% corresponds to /home, %user% corresponds to the user who owns the website, and %domain% to the domain. In the configuration found at /home/zagur/conf/web/miweb.com/nginx.conf, this will appear as follows if the user is admin and the domain is dominio.com:

root /home/admin/web/dominio.com/public_html;

The template you create must therefore contain these types of variables so that it can be used for other websites, regardless of the domain or the user configuring it. You can find more information about all the available variables in the official HestiaCP documentation.

If, on the other hand, a CMS asks you to add extra configuration to Nginx/Apache, you will need to adapt the code it provides to work in HestiaCP. For example, the Smush plugin asks you to add the following configuration snippet to configure webp images:

location ~* "wp-content\/(uploads\/)(.*.(?:png|jpe?g))" {
  add_header Vary Accept;
  set $image_path $2;
  if (-f "/home/admin/web/dominio.com/public_html/wp-content/smush-webp/disable_smush_webp") {
    break;
  }
  if ($http_accept !~* "webp") {
    break;
  }
  try_files /wp-content/smush-webp/$image_path.webp $uri =404;
}

You will notice that there is an absolute path for the plugin. For this path to work across all domains, you will need to configure it as follows:

location ~* "wp-content\/(uploads\/)(.*.(?:png|jpe?g))" {
  add_header Vary Accept;
  set $image_path $2;
  if (-f "%home%/%user%/web/%domain%/public_html/wp-content/smush-webp/disable_smush_webp") {
    break;
  }
  if ($http_accept !~* "webp") {
    break;
  }
  try_files /wp-content/smush-webp/$image_path.webp $uri =404;
}

Add this to the template you created earlier. The final result will look like this:

#=========================================================================#
# Default Web Domain Template #
# DO NOT MODIFY THIS FILE! CHANGES WILL BE LOST WHEN REBUILDING DOMAINS #
# https://docs.hestiacp.com/admin_docs/web.html#how-do-web-templates-work #
#=========================================================================#

server {
  listen %ip%:%proxy_port%;
  server_name %domain_idn% %alias_idn%;

  include %home%/%user%/conf/web/%domain%/nginx.forcessl.conf*;

  location / {
    proxy_pass http://%ip%:%web_port%;
    location ~* ^.+\.(%proxy_extensions%)$ {
    root %docroot%;
    access_log /var/log/%web_system%/domains/%domain%.log combined;
    access_log /var/log/%web_system%/domains/%domain%.bytes bytes;
    expires max;
    try_files $uri @fallback;
    }
  }

  location /error/ {
    alias %home%/%user%/web/%domain%/document_errors/;
  }

  location @fallback {
    proxy_pass http://%ip%:%web_port%;
  }

  location ~ /\.(?!well-known\/|file) {
    deny all; 
    return 404;
  }

  location ~* "wp-content\/(uploads\/)(.*.(?:png|jpe?g))" { 
    add_header Vary Accept; 
    set $image_path $2;
    if (-f "%home%/%user%/web/%domain%/public_html/wp-content/smush-webp/disable_smush_webp") {
      break; 
    } 
    if ($http_accept !~* "webp") { 
      break; 
    } 
    try_files /wp-content/smush-webp/$image_path.webp $uri =404; 
  }

  include %home%/%user%/conf/web/%domain%/nginx.conf_*;
}

Remember that you will also need to configure the .stpl file for HTTPS. It should be similar, but must take the SSL variables into account. You can find much more information about this in the official HestiaCP documentation.