Gitlab ofrece una solución basada en web para administrar proyectos de codificación, lo que facilita el seguimiento y la resolución de errores y otros problemas con el proyecto…
Introducción
Compartir el conocimiento y las lecciones aprendidas, se vuelven fundamentales para el trabajo colaborativo y los equipos de alto rendimiento.
En esta entrada, voy a compartirles cómo usar Gitlab Pages y Docusaurus para poder armar y mantener un sitio que nos de la facilidad de gestionar la documentación para nuestros equipo.
Gitlab Pages + Docusaurus
Gitlab ofrece una solución basada en web para administrar proyectos de codificación, lo que facilita el seguimiento y la resolución de errores y otros problemas con el proyecto, proporciona información y wikis sobre la función y el uso del proyecto, y una serie de otros beneficios.
¿Qué es gitlab pages?
Es una herramienta que nos permite mantener cualquier sitio web personal o comercial usando cualquier generador de sitios estáticos (SSG) o HTML simple. Se puede crear sitios web para sus proyectos, grupos o cuentas de usuario y aloja los sitios en su propia instancia de GitLab o en GitLab.com de forma gratuita.
Funcionamiento de gitlab pages
Para usar GitLab Pages, debe crear un proyecto en GitLab para cargar los archivos de su sitio web. Estos proyectos pueden ser públicos, internos o privados.
GitLab siempre implementa el sitio web desde una carpeta muy específica llamada public en su repositorio. Cuando crea un nuevo proyecto en GitLab, un repositorio está disponible automáticamente.
Para implementar el sitio, GitLab usa su herramienta incorporada llamada GitLab CI / CD para construirlo y publicarlo en el servidor de GitLab Pages. La secuencia de scripts que GitLab CI / CD ejecuta para realizar esta tarea se crea a partir de un archivo denominado .gitlab-ci.yml, que se puede crear y modificar a voluntad. Un job llamado pages en el archivo de configuración hará que GitLab sepa que está implementando un sitio web de GitLab Pages.
¿Qué es Docusaurus?
Docusaurus es un proyecto para construir, implementar y mantener la documentación web de herramientas de código abierto, el mismo permite utilizar el lenguaje Markdown para escribir la documentación que luego será publicada como un sitio web html, de igual manera, la herramienta permite extender y personalizar el diseño de nuestro sitio web de documentación con el uso de React.
¿Cómo hacer la implementación de Gitlab?
En esta oportunidad vamos a usar gitlab pages para alojar nuestro sitio web estático construido en docusaurus. Para este escenario se van a usar dos nuevas instancias con centos 7 desde cero.
Primero, hay que instalar GitLab CE en CentOS 7. Luego, actualizar la instancia e instalar y configurar dependencias.
sudo yum updatesudo yum install curl policycoreutils openssh-server openssh-clientssudo systemctl enable sshdsudo systemctl start sshdsudo yum install postfix
sudo yum install gitsudo systemctl enable postfixsudo systemctl start postfixsudo firewall-cmd --permanent --add-service=httpsudo systemctl reload firewall
Luego, agregar el servidor de paquetes de GitLab:
curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.rpm.sh | sudo bashFinalmente, instalar gitlab:
sudo yum install gitlab-ceUna vez completada la instalación, debemos configurar la url para nuestro Gitlab, para hacerlo debemos configurar el archivo “gitlab.rb”, que se encuentra en la ruta /etc/gitlab/
Dentro del archivo buscaremos el parámetro: external_url ‘http://gitlab.example.com' y lo cambiaremos al nombre de nuestro host o IP, y esa va a ser la dirección del Gitlab:
vim /etc/gitlab/gitlab.rbexternal_url 'https://example.semperti.local/'
Por defecto gitlab no tiene la opción de “pages” dicha opción hay que habilitarla para que nos cree el dominio y dirección de nuestro sitio web estático. Para ello nuevamente hay que editar el archivo /etc/gitlab/gitlab.rb
Buscamos el parámetro: #pages_external_url “http://pages.example.com/" y lo desmarcamos, quedaria asi:
pages_external_url "http://pages.example.com/Luego de haber editado y guardado el archivo hay que ejecutar:
sudo gitlab-ctl reconfigureAhora debe configurar el usuario root desde su navegador y cambiar su contraseña. Para hacer esto, simplemente navegue hasta el nombre de host o la dirección IP de su instancia desde su navegador web. Por ejemplo: http://example.semperti.local/
Se le redirigirá a una página donde se le pedirá que introduzca una nueva contraseña.
Ingrese la contraseña deseada y haga clic en ‘Cambiar su contraseña’.
Después de cambiar la contraseña, se le dirigirá a la página de inicio de sesión.
El nombre de usuario predeterminado es root. Debería poder iniciar sesión con la contraseña que he establecido anteriormente.
Se recomienda cambiar el nombre de usuario de la cuenta predeterminada de root a otro.
Una vez realizado esto, ya estará Gitlab instalado y listo.
Creación del proyecto:
Crearemos un repositorio en donde se va a alojar Docusaurus, le agregaremos nuestra clave ssh y clonamos el repositorio de ejemplo.
Agregamos Nuestra clave ssh:
Una vez creado el repositorio y agregada la clave ssh clonamos el repositorio de ejemplo que nos da docusaurus:
git clone https://gitlab.com/pages/docusaurus.gitCopiamos todos los archivos que se encuentran a nuestro repositorio, luego crearemos un archivo .gitlab-ci.yml el cual va reconocer el runner para desplegar el sitio web (más tarde explicaré que es el runner)
Asi debe quedar el .gitlab-ci.yml:
pages:script:- cd website- yarn install- yarn build- mv ./build/docusaurus ../publicartifacts:paths:- publiconly:- master
Finalmente hacemos git add, commit y push.
Gitlab runner
Gitlab Runner es el proyecto de código abierto que se utiliza para ejecutar sus trabajos y enviar los resultados a GitLab y se utiliza junto con Gitlab CI/CD y se encarga de construir y desplegar las aplicaciones identificadas. Se pueden ejecutar en cualquier sistema operativo (Windows, MacOS, Linux) y también sobre contenedores. El concepto es similar a los slaves de jenkins, donde la ejecución de los jobs se desliga en un servicio por fuera de Gitlab.
¿Cómo hacer la implementación de Gitlab runner?
Al igual que con Gitlab, vamos a usar un CentOS 7 para la instalación de Gitlab runner. Vamos a preparar en la otra instancia instalando gitlab runner, yarn y node.js para el funcionamiento de docusaurus.
Primero, añadimos los repositorios e instalamos el paquete:
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh | sudo bash
sudo yum install gitlab-runnercurl --silent --location https://rpm.nodesource.com/setup_10.x | sudo bash -sudo yum install nodejscurl --silent --location https://dl.yarnpkg.com/rpm/yarn.repo | sudo tee /etc/yum.repos.d/yarn.reposudo rpm --import https://dl.yarnpkg.com/rpm/pubkey.gpgsudo yum install yarn
Ahora nos vamos a dirigir en la configuración del repositorio que hemos creado en los parámetro CI/CD → corredores:
Nos va a figurar la url y un token para registrar nuestro runner:
Con esa información, ejecutamos los siguientes comandos:
sudo gitlab-runner register
Allí, tendremos que colocar, la url de nuestro repositorio, token y un tags y el ejecutor en este caso escogemos shell:
sudo gitlab-runner registerRuntime platform arch=amd64 os=linux pid=18202 revision=738bbe5a version=13.3.1Running in system-mode.Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com/):http://example.semperti.local/Please enter the gitlab-ci token for this runner:uWZTBMkc7dL5Cxgsnhd3Please enter the gitlab-ci description for this runner:[semperti-d-010.semperti.local]: newPlease enter the gitlab-ci tags for this runner (comma separated):docusaurusRegistering runner... succeeded runner=uWZTBMkcPlease enter the executor: docker-ssh+machine, custom, docker-ssh, shell, docker+machine, kubernetes, docker, parallels, ssh, virtualbox:shellRunner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!
Luego ejecutamos:
sudo gitlab-runner verifySi nos fijamos en los runner lo tenemos registrado y listo para usar:
Como últimos pasos, editaremos el archivo que que tiene la configuración de docusaurus.
Editaremos el archivo: /docusaurus/website/siteConfig.js configurando los parámetros:
url: 'http://example.semperti.local', // Your website URLbaseUrl: '/docusaurus/', // Base URL for your project */
Colocaremos la url en donde está instalado el gitlab y en baseUrl colocaremos el nombre del repositorio.
Con Todo esto listo nos dirigimos al CI/CD y ejecutaremos el runner:
La primera ejecución puede tardar unos minutos, una vez finalizado nos dirigimos a la opción de “pages”, que habilitamos anteriormente:
Con esto, listo! Tenemos nuestro sitio web estático alojado en gitlab, ¡podemos hacer cambios y mantenerlo con Gitlab pages! :)
Yherar Angulo, aficionado usuario de Linux 🤘, enfocado en las herramientas y mejores prácticas que se están usando en la cultura DevOps, fascinado con las tecnologías de contenedores y aquellas relacionadas a infraestructura como código. Encantado con el cine y los buenos libros. Como hobby, jugar videojuegos.
