Ansible DIINF

Variables clave, estructura esperada y recomendaciones para adaptar el playbook a tu proyecto.

Estructura

Asegúrate de tener la siguiente estructura dentro de tu carpeta de despliegue:

/{directorio_principal_de_despliegue}/
├── docker-compose.yml
├── .env
├── ansible/
│   ├── inventory/
│   ├── playbooks/
│   └── roles/

Playbook a usar

Este entorno local usa el playbook:

ansible/playbooks/deploy_diinf.yml

Configurar playbook

Modo de despliegue

Opción 1:

Usa imágenes Docker ya construidas y publicadas, por ejemplo desde Docker Hub. Este modo es recomendado ya que es más rápido y se puede usar en conjunto con un workflow de CI.

clone_repos: false

¿No tienes CI configurado? Aprende a subir tu aplicación a Docker Hub con el workflow Docker Build and Push.

Opción 2:

Clona los repositorios directamente desde GitHub y construye las imágenes Docker en la máquina virtual. Este modo es útil para cuando quieres hacer despliegues directamente desde el código.

clone_repos: true

Uso de archivo .env en Docker Compose

Si utilizas un archivo .env para la ejecución del docker compose, entonces en la sección Configuración básica del proyecto debe estar lo siguiente:

use_env_file: true

Recuerda que debes crear el archivo .env previamente y de forma manual antes de la ejecución del playbook.

De lo contrario, debes asignar la variable así:

use_env_file: false

Si no utilizas un archivo .env para tu docker-compose, el playbook generará automáticamente un .env vacío. Esto no afecta el funcionamiento de tu aplicación y previene posibles errores.

Añadir servicios

Dirígete a la sección Configuración de servicios del playbook.

Para añadir un nuevo servicio, edita la lista services agregando un bloque como el siguiente:

services:
  - name: "nuevo_servicio"
    type: "api"
    image: "usuario/nuevo-servicio"
    tag: "latest"
    port: 3001
    api_prefix: "nuevo-servicio"

Si estás utilizando clone_repos: true, no debes incluir los parámetros image ni tag, ya que el despliegue se realizará clonando directamente los repositorios y no utilizando imágenes desde Docker Hub.

Para añadir el frontend en services, debes añadir frontend_prefix y cambiar el campo type:

- name: "client"
  type: "frontend"
  port: 3000
  frontend_prefix: "/"

El campo frontend_prefix se utiliza para definir la ruta base en Nginx donde se expondrá este frontend. Por ejemplo, si frontend_prefix está definido como /, el frontend será accesible directamente en la raíz del dominio (https://midominio.com/).

En este entorno, si tienes múltiples frontends no es posible exponerlos directamente por puertos personalizados (como :3000, :8080, :9090, etc.) hacia el exterior, incluso si estos puertos han sido abiertos en el firewall. Por esta razón, se recomienda utilizar múltiples dominios con rutas diferenciadas a través de Nginx.

Para activar esto se debe definir la sección nginx_sites en el playbook:

# CONFIGURACIÓN DE NGINX (MULTI-DOMINIO)
# ---------------------   
# Activar configuración multi-dominio
nginx_multi_site: true

# Definición de dominios y servicios por dominio
    nginx_sites:
      - server_name: "felucia.diinf.usach.cl"
        services:
          - name: "backend"
          - name: "frontend1"

      - server_name: "interaction-dashboard.diinf.usach.cl"
        services:
          - name: "backend"
          - name: "frontend2"

Cada servicio en nginx_sites.services debe tener su configuración correspondiente dentro de services.

Si seleccionaste como modo de despliegue la opción para clonar repositorios (clone_repos: true), también debes añadir la siguiente sección service_repos. De lo contrario, puedes omitir este paso.

service_repos:
  - name: "nuevo-servicio"
    url: "https://github.com/mi-organizacion/app.git"
    branch: "main"
    service: "nuevo_servicio"

El campo service en service_repos debe coincidir exactamente con el campo name en la sección services. Este es el enlace que permite a Ansible saber qué repositorio corresponde a qué servicio.

Nginx y rutas

El parámetrouse_trailing_slash define si Nginx debe agregar una barra / al final de las rutas configuradas con proxy_pass.

Opción 1:

use_trailing_slash: true

Cuando el valor es true, Nginx agregará una barra al final del proxy_pass. Esto genera rutas como:

proxy_pass http://localhost:3000/; 

Por defecto este parámetro es true, incluso cuando no sea definido.

Opción 2:

use_trailing_slash: false

Cuando el valor es false, Nginx no agregará una barra al final:

proxy_pass http://localhost:3000;

Esto puede ser necesario si estás trabajando con APIs que manejan rutas de forma estricta (por ejemplo, /api/users es diferente a /api/users/), o si tu backend espera rutas sin barra final.

Importante

Si detectas problemas con rutas internas, redirecciones inesperadas o errores en la comunicación de servicios, prueba cambiar este valor y vuelve a probar tu aplicación.

Nginx y certificación

Dirígete a la sección Configuración de Nginx.

Para el despliegue en el DIINF, debes utilizar el dominio de la VM, modificando server_name con el nombre que corresponda.

# Nombre del servidor
server_name: "felucia.diinf.usach.cl"

Al utilizar un dominio, se debe activar el uso de SSL para obtener los certificados necesarios para el protocolo HTTPS. Debes activar la variable enable_ssl e ingresar tu email en admin_email.

enable_ssl: true
admin_email: "[e-mail]"
# Si usas el modo multi dominio, elimina o comenta estas líneas:
ssl_cert_path: "/etc/letsencrypt/live/{{ server_name }}/fullchain.pem"
ssl_key_path: "/etc/letsencrypt/live/{{ server_name }}/privkey.pem"

Esta plantilla está preparada para usar Certbot (Let's Encrypt) por defecto, mediante el rol ssl. Sin embargo, si prefieres usar otra tecnología (por ejemplo: certificados manuales, ZeroSSL u otro método), puedes adaptar fácilmente el rol o hacer que las rutas ssl_cert_path y ssl_key_path apunten a archivos reales.

La configuración está completa. Ahora, asegúrate de volver a las instrucciones para revisar cómo ejecutar correctamente el playbook y finalizar el despliegue.