Skip to content

Templates

Jump to bottom
omgslinux edited this page Mar 6, 2025 · 4 revisions

What is a template?

The project intends to support different types of vhost or websites, depending on the app that is hosted. Many web apps have specific configuration issues due to specific needs or features, so a specific definition for that type of host is needed.

When this situation is identified, arises the need for a custom template for that vhost type.

Where are templates stored?

Templates are stored in the _templates/ dir, with the pattern vhosttype_template.inc

How do I use a template?

Well, you have to do nothing with a template, because it contains the customized data for the vhost. What you do need to use is the example file for your vhost type. Also, you may need to check the contents of some conf files.

What is an example file and how do I use it?

Example files have the same pattern as templates, but instead, they are stored in _examples/ directory, with the pattern vhosttype_example.inc. Each example file has the basic data, common to all examples, and specific data linked to the vhost type. The examples files have bash rules, so make sure you fill data according to bash rules. Also, check the corresponding template page in this wiki to find info about the specific variables, in case of doubt.

What are the common variables?

Let's take a look at the proxy template:

  VHOST_TYPE="proxy"
  SERVER="example" # Vhost used name
  SUFFIX="example.org" # Suffix to add to ${SERVER} to have a FQDN
  DOCROOT="/var/www/vhosts/${SERVER}" # The vhost document root
  HTTP_PORT="80" # Port for http request
  HTTP_REDIRECT="1" # Set any value to force redirect http to https
  HTTPS_PORT="443" # Port for https
  SSL_CERTIFICATE="/etc/letsencrypt/live/${SERVER}.${SUFFIX}/fullchain.pem"
  SSL_CERTIFICATE_KEY="/etc/letsencrypt/live/${SERVER}.${SUFFIX}/privkey.pem"
  SSL_CLIENT_CERTIFICATE="/etc/ssl/private/CA.pem"
  SSL_VERIFY_CLIENT="optional"

As starting point, remember that any variable defined in any example or template file, can have a default value if defined in defaults.inc file.

  • The VHOST_TYPE variable comes with the template and must remain untouched
  • The SERVER variable is the non-FQDN name for the vhost
  • The SUFFIX variable should contain the domain suffix. Usually, you can define a common SUFFIX in defaults.inc and comment in the vhost file. If not the case, the SUFFIX defined at vhost level, overwrites the default value.
  • The DOCROOT variable specifies the document root for the vhost.
  • The HTTP_PORT variable defines the port for http requests.
  • The HTTPS_PORT variable defines the port for https requests.
  • The HTTP_REDIRECT variable, if defined, creates a block so every http request to $HTTP_PORT is redirected to https and $HTTPS_PORT
  • The SSL_CERTIFICATE, if not unset, is the key for creating a https block. It defaults to the letsencrypt directory.
  • The SSL_CERTIFICATE_KEY is just the private key of the SSL_CERTIFICATE variable
  • The SSL_CLIENT_CERTIFICATE enables client verification. It should contain the full path to the CA certificate, with the verification type defined in SSL_VERIFY_CLIENT.
  • Not included in the examples, you can define an EXTRA_BLOCK variable in your vhost definition for adding extra settings. That block will be added at the bottom of the generated config file.
  • There's an extra variable, WELLKNOWN_DIR, whose purpose is, if defined, to indicate the .well-known/acme-challenge directory for letsencrypt to manage certificates. This directory must exist and have proper write permissions for certbot to work.

What is a conf file?

Some templates need extra management for nginx. In this case, you just have to verify, after creating the vhost, that the files located in /etc/nginx/conf.d have the proper settings. This can be the php-fpm related configuration for php websites, or any other. Take a look at the specific template page for instructions about its conf files.

Supported templates

Can I contribute?

Sure! As long as you identify a missing template or find a bug in an existing template, you can create an issue with the details. In the case of a new template, please try to provide all the necessary info to help to create it. Of course, if you feel you can do it yourself, you can provide the template file and the example file in a PR.

Clone this wiki locally