# Deploys

Trellis ofrece tiempo cero de caida de WordPress en forma predeterminada con poca configuración.

# Configuración

Primero, debes tener al menos un Sitio de WordPress configurado en tu servidor provisionado y funcionando de acuerdo a la configuración del servidor remoto.

Para deploys, además se necesitan otros settings:

• repo (requerido) - URL de git del proyecto WordPress basado en Bedrock (en formato SSH: git@github.com:roots/bedrock.git)
• repo_subtree_path (opcional) - ruta relativa al directorio Bedrock/WP en tu repositorio, si no es la raíz (por ej. site en roots-example-project)
• branch (opcional) - el branch de git desde donde se hará el deploy (predeterminado: master)

Estas variables deben ser agregadas a su correspondiente sitio en group_vars/<environment>/wordpress_sites.yml como ha sido detallado en los documentos.

A esta altura, también deberas generar salts y keys y guardarlos en tu archivo vault.yml.

# Realizando un Deploy

Realiza un deploy con un comando único: ./bin/deploy.sh <environment> <domain>

deploy.sh es un simple comando Bash que ejecuta el ansible-playbook actual que puede ser dificil de recordar para escribir.

El comando actual se verá de la siguiente forma: ansible-playbook deploy.yml -e "site=<domain> env=<environment>".

Este comando puede ser utilizado siempre, ya que puede tomar distintas opciones de ansible-playbook.

Trellis on instala automáticamente WordPress en el servidor remoto. Suele ser normal, y es lo esperado, ver la pantalla de instalación de WordPress la primera vez que realizas un deploy. De ti depende si quieres importar una base de datos existente o prefieres una instalación desde cero.

# Fujo predeterminado

Por default, los deploys de Trellis están configurados para sitios basados en Bedrock y se encargan de todo. Los siguientes hooks pueden ser utilizados para una configuración más avanzada.

# Hooks

Los deploys de Trellis tienen la opción de configurar lo que sucede en cada proceso de deploy atomizados. Un deploy recorre las siguientes etapas:

1. initialize - crea la estructura de directorios del sitio (o revisa que existe)
2. update - clona el repositorio git en el servidor remoto
3. prepare - prepare los archivos/directorios en la nueva ruta de release (tal como mover el subtree dle repo si existiera)
4. build - arma el nuevo release tras copiar templates, archivos y carpetas
5. share - crea los symlinks de los archivos/carpetas del nuevo release
6. finalize - culmina el deploy actualizando el symlink current (deploy atomizado)

Cada etapa tiene el hook before y after. Los hooks son variables que puedes definir a través de una lista de archivos de tareas que se pueden incluir y ejecutar cuando el hook es llamado.

Las variables de hook disponibles son las siguientes:

• deploy_before
• deploy_initialize_before
• deploy_initialize_after
• deploy_update_before
• deploy_update_after
• deploy_prepare_before
• deploy_prepare_after
• deploy_build_before
• deploy_build_after
• deploy_share_before
• deploy_share_after
• deploy_finalize_before
• deploy_finalize_after
• deploy_after

# Hooks predeterminados

Trellis define y utiliza tres hooks en forma predeterminada:

• deploy_build_after ejecuta composer install.
• deploy_finalize_before revisa la instalación de WordPress.
• deploy_finalize_after actualiza las configuraciones de WordPress settings y recarga php-fpm.

Los hooks de deploy predeterminados se definen en roles/deploy/defaults/main.yml:

deploy_build_before:
  - '{{ playbook_dir }}/deploy-hooks/build-before.yml'

deploy_build_after:
  - '{{ playbook_dir }}/roles/deploy/hooks/build-after.yml'
  # - "{{ playbook_dir }}/deploy-hooks/sites/{{ site }}-build-after.yml"

deploy_finalize_before:
  - '{{ playbook_dir }}/roles/deploy/hooks/finalize-before.yml'

deploy_finalize_after:
  - '{{ playbook_dir }}/roles/deploy/hooks/finalize-after.yml'

La definición deploy_build_before y la siguiente ruta debajo deploy_build-after ofrecen ejemplos para utilizar hooks en tareas personalizadas, como se describe debajo.

# Tareas personalizadas

Para utilizar un hook de deploy, defina o sobreescriba la variable del hook en algún lugar del directorio group_vars, como por ejemplo en group_vars/all/main.yml. Si piensas definir muchos hooks puede ser una buena idea agruparlos en un archivo llamado, por ej., group_vars/all/deploy-hooks.yml.

Cada variable de hook de deploy es una lista de archivos de tareas que serán incluidos y ejecutados cuando el hook es llamado. Sugerimos mantener los archivos de tareas de hooks en una carpeta de nivel superior deploy-hooks. Aquí tenemos algunos ejemplos de variables de hooks:

# Definiendo un hook que Trellis no utiliza en forma predeterminada
deploy_before:
  - '{{ playbook_dir }}/deploy-hooks/deploy-before.yml'

# Sobreescribiendo un hook que Trellis utiliza en forma predeterminada
deploy_build_after:
  - '{{ playbook_dir }}/roles/deploy/hooks/build-after.yml'
  - '{{ playbook_dir }}/deploy-hooks/build-after.yml'
  - '{{ playbook_dir }}/deploy-hooks/sites/{{ site }}-build-after.yml'

El segundo ejemplo muestra como sobreescribir el deploy_build_after hook que Trellis utiliza en forma predefinida. El primero archivo llamado en esta lista de hooks es roles/deploy/hooks/build-after.yml, que es el archivo de tarea que Trellis generalmente ejecuta. Si omites un archivo de hook predeterminado al sobreescribir la variable de hook, el archivo predeterminado de tarea no se ejecutará.

El segundo archivo include en el ejemplo superior deploy_build_after, deploy-hooks/build-after.yml, es un ejemplo de cómo agregar una tarea personalizada que correraá en todos los deploys, sin importar el sitio sobre el que se quiera realizar un deploy. El tercer include file, deploy-hooks/sites/-build-after.yml, demuestra como se puede utilizar una variable para incluir un archivo basado en el nombre del sitio sobre el que se quiere realizar el deploy. Por ej. example.com-build-after.yml.

# Keys SSH

Antes de poder realizar un deploy de un sitio a un servidor remoto, nuestras keys SSH deben estar funcionando. Trellis utiliza SSH forwarding para que nuestro servidor remoto tenga que generar un SSH key y deba ser agregada a Github/Bitbucket.

El proceso funciona de la siguiente manera: local machine -> SSH a través de Ansible -> remote server -> Git clone -> remote Git repository

Vea la documentación sobre Keys SSH para entender como agregar las Keys SSH al usuario web, quien es el usuario con el que Trellis realiza el deploy.

# Ejemplo

Aquí un ejemplo de toda la configuración necesaria para hacer un deploy a un sitio y como se verían los comandos.

Configuración:

# group_vars/production/wordpress_sites.yml

wordpress_sites:
  mysite.com:
    site_hosts:
      - canonical: mysite.com
    local_path: ../site
    repo: git@github.com:me/mysite.git
    repo_subtree_path: site
    multisite:
      enabled: false
    ssl:
      enabled: false
    cache:
      enabled: false

Comando de deploy:

./bin/deploy.sh production mysite.com

Alternativamente:

ansible-playbook deploy.yml -e "site=mysite.com env=production"

# Rollbacks

Para hacer un rollback del deploy, ejecute ansible-playbook rollback.yml -e "site=<domain> env=<environment>" . Puedes especificar manualmente una release diferente utilizando --extra-vars='release=12345678901234' .

# Haciendo deploys a otros hosts

Trellis puede hacer un deploy a otros hosts que soportan SSH, Composer, y WP-CLI, como también actualizar la path de la raiz del usuario web.

• Haciendo un deploy a Kinsta con Trellis