Documentación Roots

Includes Nginx

La configuración Nginx site generada por Trellis está diseñada para trabajar con un amplio rango de instalaciones de WordPress, aunque los sites puede que requieran cierta customización. Por ejemplo, puedes utilizar rewrites personalizados para redirigir URLs antiguas, o puede hacer un proxy de algunos requests a otro servidor. Para ello, se pueden crear archivos Nginx include personalizados o utilizar child templates para extender las plantillas Nginx conf de Trellis.

archivos include

Puedes colocar las customizaciones Nginx en plantillas Ansible/Jinja2, haciendo pleno uso de variables y lógica. Guarde los archivos de plantilla en un nuevo directorio nginx-includes en la carpeta trellis/ del proyecto (por ej. a la misma altura que el playbook server.yml). Si quisieras llamar a este directorio de otra manera, por ej: otro-nombre, debes definir nginx_includes_templates_path: otro-nombre en group_vars/all/main.yml.

Trellis hará un recuento en la carpeta nginx-includes y creará una plantilla para de cualquier archivo terminado en *.conf.j2 al directorio /etc/nginx/includes.d/ en el servidor remoto, preservando la estructura del subdirectorio. Si se quiere editar, agregar o borrar un archivo Nginx include, debe editarse en la máquina local y ejecutar nuevamente el playbook. Consejo: Añada --tags nginx-includes al comando para ejecutar únicamente la parte relevante del playbook.

Predeterminado

Por defecto en Trellis, una Nginx conf de un sitio de WordPress incluirá cualquier archivo nginx-includes encontrado en el subdirectorio nombrado luego del sitio. Para ilustrarlo, supongamos que tenemos dos sitios manejados por Trellis, definido en wordpress_sites de la siguiente forma:

wordpress_sites:
  site1: ...
  site2: ...

Puedes organizar las plantillas nginx-includes en los siguientes subdirectorios:

trellis/
  nginx-includes/
    site1/
      rewrites.conf.j2
      proxy.conf.j2
    site2/
      rewrites.conf.j2

Puedes tener un directorio "all", que puede aplicar conf a todos los sitios:

trellis/
  nginx-includes/
    all/
      rewrites.conf.j2

La estructura de arriba será re-escrita en el servidor remoto de la siguiente manera:

/
  etc/
    nginx/
      includes.d/
        site1/
          rewrites.conf
          proxy.conf
        site2/
          rewrites.conf

Para recorrer explicitamente el ejemplo, considere solamente la key del sitio site1 en el listado wordpress_sites. El correspondiente directorio nginx-includes/site1/ contiene dos confs que re-escribirán en la carpeta del servidor remoto /etc/nginx/includes.d/site1/. La configuración Nginx primaria para el site1 tendrá una declaración include includes.d/site1/*.conf;, incluyendo rewrites.conf y proxy.conf.

Esta directiva include está ubicada dentro del block server primario, justo antes del block location. Explore la sección Child templates debajo para más opciones si esta configuración predeterminada no satisface sus necesidades.

Tenga en cuenta que esta directiva include por sitio predeterminada no revisará subdirectorios dentro de includes.d/site1. Por lo tanto si crea una plantilla en nginx-includes/site1/somedir/*.conf.j2, serán escritas en la carpeta remota includes.d/site1/somedir/*.conf pero no serán contempladas por defecto. Revise la sección Child templates para ver cómo incluir configuraciones de este tipo.

Limpieza de archivos

Trellis eliminará en la carpeta remota includes.d, de forma predeterminada, cualquier archivo que no contenga la correspondiente plantilla en la carpeta nginx-includes local. Si quisieras dejar todos los archivos conf en el remoto, puedes deshabilitar la limpieza de archivos definiendo nginx_includes_d_cleanup: false en group_vars/all/main.yml.

Directorio de plantillas obsoleto

La implementación original de includes Nginx en Trellis requería que los archivos de plantillas de ubiquen en roles/wordpress-setup/templates/includes.d. Ese directorio se encuentra obsoleto y no funcionará con la versión 1.0 de Trellis. Por favor mueva las plantillas a un directorio nginx-includes en la raíz del proyecto. Es preferible almacenar plantillas creadas por el usuario fuera de los archivos core de Trellis.

La configuración original de Trellis fue posible gracias al aporte de @chriszarate en #242.

Child templates

Puedes utilizar child templates para sobreescribir cualquier block en las dos plantillas Nginx conf.

Crea tu propio child theme siguiendo las instrucciones en Jinja template inheritance y la guía debajo.

Consejo: Añada --tags nginx-includes al comando para ejecutar únicamente la parte relevante del playbook.

Informe un child template

Deberás informar a Trellis acerca del child template que creaste.

nginx_conf

Utilice la variable nginx_conf para designar el child template para nginx.conf.j2. Dado que esta plantilla se aplica a todos los sitios, sería apropiado definir las variables en el archivo group_vars/<environment>/main.yml (incluyendo group_vars/all/main.yml).

nginx_conf: nginx-includes/nginx.conf.child

El ejemplo de arriba designa un child template en la ruta nginx-includes en tu máquina local (por ej. la ruta predeterminada para la variable nginx_includes_templates_path; vea archivos include en la sección superior). Puedes elegir otra ruta y asignarle el nombre a la plantilla y extensión de archivo que desees. Al utilizar la ruta nginx-includes, sin embargo, evite utizar un nombre de archivo que coincida con el patrón *.conf.j2 requerido para archivos los include mencionados arriba.

nginx_wordpress_site_conf

Utilice la variable nginx_wordpress_site_conf para designar el child templare para wordpress-site.conf.j2, que se utiliza para cada uno de sus sitios. Para designar un child template global para todos tus sitios, puede definir la variable en un archivo group_vars/<environment>/main.yml.

nginx_wordpress_site_conf: nginx-includes/wordpress-site.conf.child

Puedes designar un child template por sitio definiendo la variable en group_vars/<environment>/wordpress_sites.yml.

wordpress_sites:
  example.com:
    ...
    nginx_wordpress_site_conf: nginx-includes/example.com.conf.child
    ...

Crear un child template

Crea tu propio child template en las rutas que designaste en las variables nginx_conf y nginx_wordpress_site_conf descritas arriba. Los Child templates deben incluir dos elementos:

  • una declaración {% extends 'base_template' %}
  • uno o más bloques {% block block_name %}

Ejemplo de child template - simple

Aquí encontramos un ejemplo de child template que reemplaza el bloque http_begin en la plantilla base nginx.conf.j2.

{% extends 'roles/nginx/templates/nginx.conf.j2' %}

{% block http_begin -%}
  server_names_hash_bucket_size 128;
  server_names_hash_max_size 512;
{% endblock %}

La ruta para la plantilla base - referenciada en la declaración extends - debe ser relativa al playbook server.yml (ej., relativa al directorio raíz de Trellis).

Ejemplo de child template - complejo

El primero bloque en el ejemplo del child template de abajo aumenta el contenido del bloque fastcgi_basic proveniente de la plantilla base wordpress-site.conf.j2. Inserta ###, que representa el bloque de contenido original de la plantilla base, y luego agrega un extra fastcgi_param. El segundo bloque en el ejemplo reescribe el bloque redirects_https, omitiendo el condicional ssl_enabled y agregando una nueva directiva listen 8080.

{% extends 'roles/wordpress-setup/templates/wordpress-site.conf.j2' %}

    {% block fastcgi_basic -%}
    {{ super() }}
    fastcgi_param HTTPS on;
    {%- endblock %}

{% block redirects_https %}
# Redirect to https
server {
  listen 80;
  listen 8080;
  server_name {{ site_hosts | join(' ') }}{% if item.value.multisite.subdomains | default(false) %} *.{{ site_hosts_canonical | join(' *.') }}{% endif %};

  {{ self.acme_challenge() -}}

  location / {
    return 301 https://$host$request_uri;
  }
}

{% endblock -%}

Notarás que estos bloques utilizan indentación y control de los espacios en blanco (ej., -%}) paralelo a la contraparte en la plantilla base wordpress-site.conf.j2. Esto permitirá un adecuado formato del archivo de plantilla conf en el servidor.

Plantillas de sitios

Puedes utilizar plantillas de sitios para añadir nuevas confs de sitios a Nginx, además de la confs standard de WordPress. Existen además plantillas Ansible/Jinja2, donde se puede hacer pleno uso de variables y lógica.

Cree las plantillas de sitios siguiendo las instrucciones de abajo.

Consejo: Añada --tags nginx-includes al comando para ejecutar únicamente la parte relevante del playbook.

Predeterminado

Una conf site Nginx "no-default" viene incluida por defecto en Trellis. El propósito es bajar requests a nombres de servidores desconocidos, previniendo ataques al header del host y otros problemas potenciales.

La variable nginx_sites_confs contiene la lista de confs a ser escritas en la carpeta sites-available del server.

El valor predeterminado solo registra el sitio preterminado (cuya plantilla se encuentra en roles/nginx/templates/no-default.conf.j2).

nginx_sites_confs:
  - src: no-default.conf.j2

Cada entrada a esta variable contiene además un parámetro enabled, que puede ser omitido, y cuyo valor predeterminado es true.

Controla si el conf se encuentra vínculado con la carpeta del servidor sites-enabled y, por lo tanto, activada.

El valor predeterminado de arriba equivale a:

nginx_sites_confs:
  - src: no-default.conf.j2
    enabled: true

Sin embargo, puede que quieras agregar otros sitios para propósitos específicos.

Designa una plantilla de sitio

Necesitarás informar Trellis de las plantillas de sitios que creaste.

nginx_sites_confs

Utilice la variable nginx_sites_confs que para designar la nueva plantilla de sitio. Dado que esta plantilla aplica a todos los entornos, sería apropiado definir la variable en un archivo group_vars/<environment>/main.yml (incluyendo group_vars/all/main.yml).

Recuerde mantenter el sitio predeterminado por razones de seguridad, excepto que tenga una razón específica para sobreescribirlo.

nginx_sites_confs:
  - src: no-default.conf.j2
  - src: nginx-includes/example.conf.site.j2

El ejemplo de arriba designa una plantilla de sitio en la ruta nginx-includes en tu máquina local (ej., la ruta predeterminada para la variable nginx_includes_templates_path; vea la sección archivos include arriba). Puedes elegit diferentes rutas y asignar a la plantilla cualquier nombre o extensión que desees. Cuando utilice la ruta nginx-includes, sin embargo, evite utilizar nombres de archivos que coincidan con el patrón *.conf.j2 requerido para los archivos include descritos arriba.

Cree una plantilla de sitio

Cree sus plantillas de sitio en las rutas que designo en la variable nginx_sites_confs descrita arriba. Las plantillas deden comenzar con una declaración # para indicar que el archivo es manejado por ansible.

Ejemplo de plantilla

Aquí hay un ejemplo de plantilla de sitio que aloja la página predeterminada de nginx, escuchando en el puerto no estándar 8080 example.com.

# {{ ansible_managed }}

server {
  listen 8080;
  server_name example.com;

  root /var/www/html;
  index index.html index.htm index.nginx-debian.html;

  location / {
    # First attempt to serve request as file, then
    # as directory, then fall back to displaying a 404.
    try_files $uri $uri/ =404;
  }
}

Limpieza de archivo

Por defecto, Trellis removerá del directorio site-enabled cualquier link a un archivo site conf que tenga el atributo enabled definido como false. No hay limpieza de los confs en sites-available, solo son silenciados cuando son deshabilitados.

Este ejemplo muestra la suma del template de sitio superior, mientras se desactiva el sitio predeterminado de Trellis.

nginx_sites_confs:
  - src: no-default.conf.j2
    enabled: false
  - src: nginx-includes/example.conf.site.j2

← Passwords →