DEV Community: Sylvain Lesage

Using webhooks to update a self-hosted Jekyll blog

Sylvain Lesage — Mon, 26 Aug 2019 14:38:16 +0000

I host the blog of a community project on my personal server. It's a static website generated with Jekyll, and the contents are versionned in a git repository.

In this blog post, I explain how I made the blog automatically update on every new commit. It's the same idea as Github Pages, but for self-hosting.

TL;DR

create a script to clone the git repository, then build and deploy the website
publish a webhooks endpoint on the server
configure the GitHub repository to send a webhook on every new commit

Deploy script

The website is hosted on a Debian server, and the files are served from the /var/www/atlas.tecnologia.bo/ directory. To update it from command line, first install the Jekyll requirements, then create and launch the bash script:

$ /opt/deploy_atlas.tecnologia.bo.sh

that contains:

#!/usr/bin/env bash

# Clone git repository
rm -rf /tmp/atlas.tecnologia.bo
git clone https://github.com/RipeAtlasBolivia/atlas.tecnologia.bo.git /tmp/atlas.tecnologia.bo

# Generate blog
cd /tmp/atlas.tecnologia.bo
bundle install
bundle exec jekyll build --source /tmp/atlas.tecnologia.bo/ --destination /var/www/atlas.tecnologia.bo/

# Clean
rm -rf /tmp/atlas.tecnologia.bo

Webhook daemon

Instead of manually launching the script, let a webhook daemon do the job every time it receives an HTTP request on an endpoint.

First install the webhook package:

$ sudo apt install webhook

Verify the service is running:

$ sudo service webhook status
● webhook.service - Small server for creating HTTP endpoints (hooks)
   Loaded: loaded (/etc/systemd/system/webhook.service; enabled; vendor preset: enabled)
   Active: active (running) since Mon 2019-08-12 08:25:24 UTC; 2 weeks 0 days ago
     Docs: https://github.com/adnanh/webhook/
 Main PID: 419 (webhook)
    Tasks: 6 (limit: 4697)
   Memory: 4.8M
   CGroup: /system.slice/webhook.service
           └─419 /usr/bin/webhook -verbose -hooks /etc/webhook.conf

We configure the webhook daemon, creating the file /etc/webhook.conf with the following content (see the webhook documentation for more details):

[
  {
    "id": "atlas",
    "execute-command": "/opt/deploy_atlas.tecnologia.bo.sh",
    "command-working-directory": "/tmp/",
    "trigger-rule": {
      "match": {
        "type": "payload-hash-sha1",
        "secret": "xxxxxxxxx",
        "parameter": {
          "source": "header",
          "name": "X-Hub-Signature"
        }
      }
    }
  }
]

This creates a new hook called atlas, that will be triggered when a GET or POST request is received on http://localhost:9000/hooks/atlas. When triggered, it will check that a valid X-Hub-Signature HTTP header has been provided, and then launch the /opt/deploy_atlas.tecnologia.bo.sh script from the /tmp working directory.

Try it:

compute the X-Hub-Signature corresponding to the xxxxxxxxx secret

$ echo -n "" | openssl sha1 -hmac "xxxxxxxxx"
(stdin)= d46d87941e6f285be78ff0f1c8ea32620577b9ef

request the endpoint:

$ curl -X POST -H "X-Hub-Signature: sha1=d46d87941e6f285be78ff0f1c8ea32620577b9ef" -v http://localhost:9000/hooks/atlas
...
> POST /hooks/atlas HTTP/1.1
> Host: localhost:9000
> User-Agent: curl/7.64.0
> Accept: */*
> X-Hub-Signature: sha1=d46d87941e6f285be78ff0f1c8ea32620577b9ef
>
< HTTP/1.1 200 OK
< Date: Mon, 26 Aug 2019 13:45:09 GMT
< Content-Length: 0
<

check the logs:

$ grep webhook /var/log/syslog
Aug 26 14:06:40 webhook[10552]: [webhook] 2019/08/26 14:06:40 Started POST /hooks/atlas
Aug 26 14:06:40 webhook[10552]: [webhook] 2019/08/26 14:06:40 [d2ae30] incoming HTTP request from [::1]:58800
Aug 26 14:06:40 webhook[10552]: [webhook] 2019/08/26 14:06:40 [d2ae30] atlas got matched
Aug 26 14:06:40 webhook[10552]: [webhook] 2019/08/26 14:06:40 [d2ae30] atlas hook triggered successfully
Aug 26 14:06:40 webhook[10552]: [webhook] 2019/08/26 14:06:40 Completed 200 OK in 670.302µs
Aug 26 14:06:40 webhook[10552]: [webhook] 2019/08/26 14:06:40 [d2ae30] executing /opt/deploy_atlas.tecnologia.bo.sh (/opt/deploy_atlas.tecnologia.bo.sh) with arguments ["/opt/deploy_atlas.tecnologia.bo.sh"] and environment [] using /tmp/ as cwd
Aug 26 14:06:46 webhook[10552]: [webhook] 2019/08/26 14:06:46 [d2ae30] command output: Cloning into '/tmp/atlas.tecnologia.bo'...
...
Aug 26 14:06:46 webhook[10552]: Bundle complete! 4 Gemfile dependencies, 24 gems now installed.
Aug 26 14:06:46 webhook[10552]: Use `bundle info [gemname]` to see where a bundled gem is installed.
Aug 26 14:06:46 webhook[10552]: Configuration file: /tmp/atlas.tecnologia.bo/_config.yml
Aug 26 14:06:46 webhook[10552]:             Source: /tmp/atlas.tecnologia.bo/
Aug 26 14:06:46 webhook[10552]:        Destination: /var/www/atlas.tecnologia.bo/
Aug 26 14:06:46 webhook[10552]:  Incremental build: disabled. Enable with --incremental
Aug 26 14:06:46 webhook[10552]:       Generating...
Aug 26 14:06:46 webhook[10552]:        Jekyll Feed: Generating feed for posts
Aug 26 14:06:46 webhook[10552]:                     done in 0.45 seconds.
Aug 26 14:06:46 webhook[10552]:  Auto-regeneration: disabled. Use --watch to enable.
Aug 26 14:06:46 webhook[10552]: [webhook] 2019/08/26 14:06:46 [d2ae30] finished handling atlas

Note: the 200 HTTP code only means the hook has been found for the atlas identifier and the X-Hub-Signature is valid. It says nothing about the deploy script success or failure.

In order to publish the endpoint from a Apache webserver, configure a reverse proxy in your Apache configuration:

ProxyPass /webhook/ http://localhost:9000/hooks/
ProxyPassReverse /webhook/ http://localhost:9000/hooks/

GitHub configuration

Finally, in order to trigger a webhook on every new push, go to the GitHub project settings, then "Webhooks", and create a new webhook with the following parameters:

Payload URL: https://mydomain/webhook/atlas
Content type: application/json
Secret: xxxxxxxxx
Which events would you like to trigger this webhook?: Just the push event.

Alternative configuration with GitLab

If your git repository is hosted on a GitLab instance, you must change the headers check in the /etc/webhook.conf file:

[
  {
    "id": "atlas",
    "execute-command": "/opt/deploy_atlas.tecnologia.bo.sh",
    "command-working-directory": "/tmp/",
    "trigger-rule": {
      "match": {
        "type": "value",
        "value": "xxxxxxxxx",
        "parameter": {
          "source": "header",
          "name": "X-Gitlab-Token"
        }
      }
    }
  }
]

Note: the X-Gitlab-Token header provided in the request will contain the value xxxxxxxxx, not its HMAC as it occurs with GitHub. So, to simulate the request, adapt the curl command to:

$ curl -X POST -H "X-Gitlab-Token: xxxxxxxxx" -v http://localhost:9000/hooks/atlas

Then, the GitLab project configuration is similar to GitHub: go to the project "Settings", "Integrations", and add a webhook with:

URL: https://mydomain/webhook/atlas
Secret Token: xxxxxxxxx
Trigger: [x] Push events

References

Administrar un dominio con EU.org y Knot

Sylvain Lesage — Sun, 02 Sep 2018 22:34:00 +0000

Este artículo es una traducción de Obtenir et gérer un nom de domaine (gratuit)
avec Knot et EU.org, de Emmanuel Bourguin.

Nombre de dominio, DNS, zona, ¿de qué hablamos?

Para proveer servicios en Internet, es generalmente necesario poseer un nombre de dominio.

En efecto, si las maquinas comunican entre ellas identificándose por sus direcciones IP, nosotrxs, humanxs, nos acordamos más fácilmente de un nombre que de una sucesión de cifras. Además, un nombre de dominio que sirve como identificador, que se traduce en una dirección IP, da más flexibilidad. Cuando se cambia la dirección IP de la maquina que alberga un servicio, el nombre de dominio puede seguir siendo el mismo, así el cambio es transparente para lxs usuarixs del servicio.

Hay que establecer un mecanismo para realizar la correspondencia entre un nombre y una dirección IP (u otros tipos de valores). La operación se llama « resolución de un nombre de dominio ». Una correspondencia entre una entrada y un valor, es el rol de una base de datos. En nuestro caso, esta base de datos es mundial, repartida y sin centro. La tarea de llenar esta base de datos es de cada uno de los dueños de nombres de dominio: cada unx es responsable de sus « zonas ». Lo han entendido: esta base de datos mundial se llama el DNS, y funciona gracias a los servidores DNS.

El papel de los servidores es simplemente responder a consultas, y existen dos tipos de servidores DNS, que se diferencian por la forma que tienen de obtener la información de resolución:

1 − Los servidores puestos a disposición por tu proveedor de acceso a Internet, que van a resolver las consultas DNS para ti, son llamados comúnmente « resolvers ». Si el servidor no conocer la respuesta, entonces la va a solicitar a otros servidores que la conocen, a veces en varias etapas por lo que los llamamos servidores « recursivos ». También se los llama servidores de « caché », porque no conocen las respuestas, pero una vez que las obtienen, las guardan un cierto tiempo en su memoria. Si estos servidores mienten en la respuesta que proveen, los llamamos « DNS mentirosos », lo que es el caso ahora para los servidores de resolución de los grandes proveedores de acceso a Internet en Francia, principalmente por razones políticas.

2 − Si el servidor conoce la respuesta sin tener que preguntar a otro, es porque es el servidor encargado de proveer las respuestas para este dominio en particular. En este caso, se dice que el servidor « hace autoridad » sobre la zona DNS que provee. Entonces, para asegurar la administración de tu nombre de dominio, habrá que implementar uno (o varios) servidor DNS que haga autoridad.

Para eso, nada difícil, Knot DNS, software originario de República Checa, que vamos a utilizar, está disponible con Unix, y un Raspberry Pi es ampliamente suficiente en términos de recursos para hacerlo funcionar.

Consideraciones sobre el hecho de pagar para un nombre de dominio

Se sobreentiende desde años que hay que pagar para obtener un nombre de dominio, para un tiempo limitado. Así que nunca somos dueñxs del nombre de dominio, más bien somos inquilinxs. Aunque esta idea de pagar para un nombre de dominio es ampliamente difundida, no es correcta. Para ser más precisxs, es muy común tener que pagar para nombres de dominio de dos componentes, como algo.com, otracosa.net, lutte-ouvriere.org o potamochère.fr. Pero un nombre de dominio también puede contener más de dos componentes, por ejemplo edgard.fdn.fr es un nombre de dominio tanto como google.be.

Así que la asociación French Data Network provee a sus suscriptores un nombre de dominio en .fdn.fr, dos de mis hijos gozan de uno de estos dominios, sin haber pagado nada, solamente tuve que llamar al camarada-presidente.

Cuando estaba suscrito al proveedor de acceso Nerim, tenía a mi disposición el nombre de dominio emmanuel.bourguin.pck.nerim.net que apuntaba
a mi IP pública, sin costos adicional. Netlib.re que está alojado en la infraestructura del proveedor de acceso a Internet asociativo Alsace Réseau Neutre también te permite tener un nombre de dominio gratuito.

OjO. El servicio FreeNom que pretende de manera errónea ser el primero y único proveedor de nombres de dominio gratuitos, no te considera como titular de los dominios que te proveen, sino como simple usuarix, como se puede leer en sus CGU, con la ausencia de garantías que implica.

EU.org también provee nombres de dominio gratuitos. Esta iniciativa fue tomada en reacción a la política de precios exorbitantes instaurada en un momento de la Historia donde se volvía vital adquirir nombres de dominio. Si en 2016 los precios han bajado para llegar a ser razonables, algunos siguen siendo vergonzosos (en el momento de la primera redacción de este artículo: 40 euros por año para un .black, o un .lgbt, ¡3.000 euros! para un .auto). Además, la idea de pagar para poder nombrarse es... curiosa. Al
contrario de un registrar clásico/comercial, EU.org no administrará la zona DNS asociada al nombre de dominio proveído. De eso se encargarán los servidores que vamos a instalar.

Instalación de Knot DNS

En una consola, bajo Debian:

sudo apt-get -y install knot

Configuración de Knot DNS

Empezamos por la edición del archivo de configuración principal de Knot:

sudo nano /etc/knot/knot.conf

En la sección « zone » definimos una nueva zona, que corresponde a nuestro nombre de dominio, aquí « exemple.eu.org ». El archivo de configuración correspondiente será llamado « exemple.eu.org.zone ».

  - domain: exemple.eu.org
    file: "exemple.eu.org.zone"

Ahora vamos a crear y editar el archivo de zona, en /var/lib/knot/:

sudo touch /var/lib/knot/exemple.eu.org.zone
sudo nano /var/lib/knot/exemple.eu.org.zone

Colocaremos el contenido siguiente:

@                          10800   IN  SOA     exemple.eu.org. e.fdn.fr.  (
                             2018040301    ;  Numero
                             28800        ;  Refresh
                             14400        ;  Retry
                             3600000      ;  Expire
                             86400 )      ;  Minimum

                             IN 3600   NS  ns.exemple.eu.org.
exemple.eu.org.     IN 3600   A    93.184.216.34
exemple.eu.org.     IN 3600   AAAA    2606:2800:220:1:248:1893:25c8:1946

Ten cuidado en adaptar tu archivo de zona a tu propio nombre de dominio. También tomar en cuenta que los "punto y coma" finales son obligatorios.

En la primera línea, luego de tu nombre de dominio, tienes que colocar tu dirección de correo electrónico, remplazando el @ por un punto. Por convención, se considera que el primer punto corresponde a @, por eso si tu dirección es algo como juan.carlos@exemple.eu.org, tienes que colocar juan\.carlos.

Los diferentes valores numéricos son tiempos expresados en segundos. La explicación en detalle sale del marco de este artículo. Los más importantes son el número de serie, « 2016121300 » en el ejemplo, que tendrás que incrementar cada vez que actualizas tu archivo de zona. Una astucia clásica consiste en colocar la fecha del día, de esta forma evitas que el número se decremente, lo que tendría consecuencias complicadas.

El otro valor importante es el TTL, que se ve en las dos últimas líneas. Es una indicación de la duración de validez de la información enviada por tu servidor. Aquí es de 3.600 segundos, o sea una hora. Significa que los servidores de resolución DNS de los proveedores de acceso a Internet considerarán que la respuesta « 92.93.169.42 » a la pregunta « ¿cuál es la dirección IP asociada al nombre de dominio exemple.eu.org? » es valida una hora, y luego volverán a preguntar. Si algún día tienes que cambiar la IP asociada a tu nombre de dominio, piensa en bajar primero este TTL para que el corte de servicio sea el menor posible. Luego vuelve a subir el valor para evitar que tu servidor reciba demasiadas consultas inútiles.

Reinicio y verificación

Una vez realizada la configuración, reiniciamos Knot con el comando:

sudo service knot restart

Luego podemos verificar en los logs que todo funciona como esperado:

sudo service knot status

Tenemos la confirmación que la sintaxis del archivo de configuración era correcta. Una vez eso hecho, piensa en abrir el puerto 53 en TCP y UDP en las opciones NAT de tu router, y a redirigirlo hacia la maquina sobra la cual Knot está corriendo.

Inscripción en EU.org

Primero, asegúrate de haber leído atentamente las condiciones generales de EU.org así que las reglas adicionales para los subdominios directos.

Luego, puedes ir a la página de registro, llenar el formulario de creación de cuenta y validar tu correo electrónico para activarla.

Creación de un nombre de dominio

Ahora, solo te queda crear tu nombre de dominio.

Coloca el nombre completo del dominio en el primer campo, en este caso exemple.eu.org. Los siguientes campos, para la identificación en el registro whois están pre-llenados. Puedes elegir de conservarlos privados, en este caso solamente EU.org tendrá acceso a ellos.

En el campo « Name1 » colocar ns.TUDOMINIO.eu.org, en este caso « ns.exemple.eu.org ». Y luego en el campo « IP1» la dirección IP de la maquina dónde funciona Knot (es el momento de asegurarte que abriste el puerto 53 en tu router).

Una vez hecho, el sistema de EU.org procederá a las verificaciones y si todo está correcto, tu solicitud será enviada a las personas que administran EU.org.

En este momento, todavía el nombre de dominio no ha sido creado. Se puede verificar con el comando siguiente:

host exemple.eu.org

que devuelve el error « NXDOMAIN » (Non-eXistent Domain).

Luego de que EU.org haya aceptado tu solicitud, recibirás un correo de notificación:

Ahora sí, luego de algunos minutos, o hasta algunas horas, el nombre de dominio llega a existir.

Epilogo (temporal)

Listo, ya tienes tu nombre de dominio gracias a Knot y EU.org. Nota que si bien el servicio es gratuito para ti, no deja de tener un costo. Así que si tienes la posibilidad, considera realizar una pequeña donación a EU.org.

Este tutorial ha sido escrito en la óptica de « auto-alojamiento ». Según las buenas prácticas, deberías tener por lo menos dos servidores que hagan autoridad sobre tu nombre de dominio, si fuera posible lo más lejos posible a nivel geográfico, y alojados en dos sistemas autónomos diferentes, con el fin de minimizar los riesgos de interrupción de servicio si una de las maquinas dejará de estar disponible.

En el marco del auto-alojamiento donde tu sitio y tu servidor de correo personal están en tu casa, detrás de una línea ADSL o de fibra, esta precaución es exagerada. Si tu conexión se corta, no sirve de nada que el servidor de nombres de dominio siga funcionando, ya que de todas formas tu sitio será inaccesible.

Entonces, toma este tutorial como lo que es: un ejemplo quick & dirty para una persona particular que se auto-aloja y quiere disponer de un nombre de dominio sin mayores costos, no como un artículo de referencia sobre DNS.

Este artículo será seguido por una segunda parte, que explicará que tener redundancia sí puede ser útil en algunos casos, y cómo añadir esta redundancia.