Estamos inmersos en un proyecto en el que estamos haciendo uso de diferentes tecnologías entre ellas Hugo para la gestión de las páginas estáticas y nos hemos encontrado con algunos problemas a la hora de manejar diferentes entornos de despliegue. En esta entrada explicaremos cómo resolver este problema

En el caso que nos ocupa debíamos tener tres entornos definidos para el despliegue de nuestra web:

• Desarrollo: mientras que estamos desarrollando el sitio web
• Testing: el entorno de pruebas donde queremos ver si todo está bien
• Producción: el entorno final de puesta en producción del sitio web

Además en nuestro caso queríamos que el despliegue se hiciera en base a las pipelines de Gitlab CI/CD.

Lo primero cabe destacar que la propia Gitlab nos provee de diferentes plantillas cuando estamos creando un proyecto nuevo, entre ellas está la de Hugo. En la que directamente nos clona un repositorio con la configuración base de CI/CD para realizar los despliegues en las GitLab Pages, que luego veremos que no nos sirve para mucho.

Es decir, nos genera un fichero .gitlab-ci.yml que nos sirve de base para las pipelines de Gitlab.

Veamos un poco lo que nos genera:

# All available Hugo versions are listed here: https://gitlab.com/pages/hugo/container_registry
image: registry.gitlab.com/pages/hugo:latest #imagen docker con el cli de hugo

variables:
  GIT_SUBMODULE_STRATEGY: recursive

test: #step de prueba de hugo
  script: # ejecuta el script de hugo para probar que va todo bien
  - hugo 
  except:
  - master # no se ejecuta en master

pages: # step de subida a las gitlab pages de lo generado por hugo
  script: # Script para generar las páginas de hugo
  - hugo
  artifacts: # guarda los ficheros generador en public para luego subirlas
    paths:
    - public
  only: # sólo lo hace en la rama master
  - master

Como podemos ver hasta aquí es impecable salvo que la plantilla de Gitlab por defecto no funciona correctamente y tuvimos que borrar todos los fichero del repositorio menos el mencionado .gitlab-ci.yml y crear el proyecto desde cero.

Instalación de Hugo

Evidentemente si queremos usar Hugo deberemos realizar la instalación del comando si es que queremos crear nuevos proyectos en local y probar el sitio antes de subirlo.

Empecemos con la instalación desde la guía oficial, en el caso de una Ubuntu 20.04 tiene una versión muy antigua si lo instalamos desde paquetes deb así que debemos tirar de snap:

snap install hugo --channel=extended

Creación del sitio

Una vez instalado ya podremos crear nuestro proyecto con el comando:

hugo new site nombre_proyecto

Esto nos creará una carpeta con ese nombre y nos meteremos en ella de la manera habitual:

cd nombre_proyecto

Arranque en desarrollo

Si todo ha ido bien deberemos poder arrancar el servidor de desarrollo con el comando:

hugo serve

Esto nos debería habilitar la URL http://localhost:1313/ con la plantilla de prueba con la que viene o la que te indique cuando ejecutas el hugo serve.

Ya irá siendo hora de crear el repositorio git dentro de la carpeta del proyecto con el comando:

git init

Por supuesto, no te olvides meter el fichero .gitlab-ci.yml en el directorio del proyecto y añadirlo a git:

git add .gitlab-ci.yml

Y hacer el correspondiente commit con git:

git commit -m 'primer commit'

Subida al repositorio Gitlab

Y ya podrías subir al repositorio gitlab de la manera habitual con tu comando favorito. Nosotros usamos normalmente GitKraken para estos menesteres, sino siempre pruebes usar el comando de git:

git remote add nombre_remoto git@servidor_remoto/ruta/repo.git

Y haciendo después un push de la rama master por ejemplo con git:

git push origin master

Si es que has llamado a tu repositorio remoto origin claro 😉

Pipelines en Gitlab

Como habremos subido nuestro código incluyendo el fichero .gitlab-ci.yml deberíamos ver en la sección CI/CD -> Pipelines deberíamos ver una nueva pipeline que debería intentar ejecutar el comando hugo y subirlo automáticamente a la Gitlab Pages si hemos hecho todo de manera correcta. Y deberíamos ver algo similar a esto:

Si luego, estando logueados en Gitlab, en el repositorio, nos vamos a la sección Settings->Gitlab Pages deberíamos poder ver la dirección donde se supone que nos ha desplegado el sitio de Hugo que debería ser similar a https://tuusuario.gitlab.io/repositorio_hugo/

Problemas de resolución de URL’s en Hugo

Y aquí es donde empezamos con los problemas con los diferentes entornos y el uso de las url’s absolutas y relativas de los recursos de nuestro sitio.

Lo más normal que nos va a pasar es que al entrar a la url de Gitlab Pages los css no se carguen y esa preciosa página que has visto usando el hugo serve no se ve ni de lejos igual de bonita que en desarrollo.

¿Qué ha pasado?

Resumiendo la url base que usa hugo en desarrollo no es la misma que la que estamos usando en nuestro entorno de “testing” que son las Gitlab Pages ya que en local usa por defecto normalmente “/” y en testing debería estar usando “/nombre_repositorio”

Usando Plantillas (Themes) de Hugo

No queremos pasar la ocasión de comentaros un par de plantillas que nos han gustado para un par de usos concretos:

• hugo-landing-page: esta la estamos usando, oh sorpresa, para definir la landing page del proyecto.
• digitalgarden: que estamos usando para presentar el white paper del proyecto.

En ambos casos hemos tenido que copiar el repositorio en una carpeta dentro de /themes para tenerlas disponibles.

Para después cambiar el fichero config.toml para indicar que plantilla es la que queremos usar, por ejemplo:

theme = "digitalgarden"

Carpeta config para manejar los entornos en Hugo

El caso es que volviendo al tema que nos ocupa, seguimos con el problema de que debemos definir diferentes valores dependiendo del entorno para las mismas configuraciones en nuestros proyectos Hugo. Vayamos por partes.

Lo primero que debemos hacer es crear una estructura de carpetas que nos debería permitir gestionar diferentes ficheros config.toml dendiendo del entorno:

• config
  • _default
    • config.toml
  • development
    • config.toml
  • testing
    • config.toml
  • production
    • config.toml

Lo primero que debemos hacer es mover nuestro fichero config.toml de nuestra carpeta principal del proyecto a la carpeta /config/_default

Esto nos permitirá mantener la misma configuración que teníamos hasta ahora. Vuelve a arrancar el hugo serve para comprobar que no ha cambiado nada.

Ahora es cuando deberemos ir haciendo las modificaciones de las variables que queremos cambiar dependiendo del entorno.

En nuestro caso de momento bastará cambiar la variable baseURL y adaptarla a los diferentes entornos:

• Corta la línea del _default/config.toml que define el baseURL
• Pégala en el development/config.toml que sólo debería inicialmente contener esta línea
• Verás que el fichero anterior debería tener: baseURL = "/"
• En el fichero testing/config.toml, recuerda que es como hemos llamado al entorno de despliegue de Gitlab Pages, mete lo siguiente: baseURL = "/nombre_repositorio"
• No me seas…. y cambia el nombre_repositorio por el nombre de tu repositorio

Con este cambio habremos configurado dos baseURL diferentes dependiendo del entorno, pero cómo comprobamos que todo esto va como debe. Ya sabes por donde vamos, ejecutando comandos.

En el fichero production/config.toml tendrás que hacer lo propio con el baseURL.

Comprobación de la configuración de los entornos

Empecemos por comprobar el entorno de desarrollo:

hugo config -e development | grep baseurl

En este caso deberíamos ver una salida similar a la siguiente:

baseurl: "/"

En porqué no la salida no es baseURL, no preguntes, son cosas de Hugo.

Ahora vamos a comprobar que el entorno de testing está configurado de manera correcta:

hugo config -e testing | grep baseurl

Y nos debería de salir, creo que lo vas pillando:

baseurl: "/turepo"

Comprueba también la configuración de producción

Comprobación de las plantillas de Hugo

Si pensabas que habíamos terminado ya es que tienes mucha fe en los creadores de plantillas de Hugo. En concreto estas dos no nos terminaron de funcionar a la primera por lo que tuvimos que hacer diferentes cambios en los ficheros de los layouts. En concreto en el fichero head.html, o donde encuentres el código del head, en el caso de la plantilla digitalgarden está en la carpeta /themes/digitalgarden/layouts/partial. Veamos lo que debemos de poner:

<base href="{{ .Site.BaseURL }}">
<link rel="stylesheet" href="/css/main.css" />

Fíjate en el {{ .Site.BaseURL}} que corresponderá con el parámetro baseURL que hemos introducido en los ficheros de configuración de cada entorno.

Probando en desarrollo

Son muchos cambios pero la cosa ya está encarrilada, prueba ahora si con el:

hugo serve

Comprueba si se cargan correctamente los URL’s que has cambiado en los layouts.

Poniendo en marcha Testing

Ya sólo nos queda probar en testing, es decir en Gitlab Pages. Para ello sólo deberemos hacer un cambio más en el fichero .gitlab-ci.yml para indicar que debe subir a las Gitlab Pages la configuración de testing cambiando la línea de llamada a hugo en caso de la rama master:

pages:
  script:
  - hugo -e testing
  artifacts:
    paths:
    - public
  only:
  - master

Con este -e testing lo que le estamos diciendo es que debe usar a parte del _default/config.toml el fichero testing/config.toml donde hemos cambiado el baseURL

Guarda todos los cambios en el siguiente commit de git y sube los cambios al repositorio de gitlab.

Comprueba que se ejecuta correctamente la pipeline.

Y accede a la ruta de tu Gitlab Page asignada a ese repositorio y ya deberías ver tus estilos y demás recursos por su URL correcta.