Formas de instalar

Un único binario estático sin dependencias en tiempo de ejecución. Cómo llega a la máquina es la única decisión, y se deriva de dónde quieras que corra.

Tu sistema, de la descarga al servicio

Las releases llevan binarios para Linux, macOS y Windows, en amd64 y arm64. Las tres páginas de abajo son el mismo recorrido para cada sistema, hasta el final: qué archivo, cómo comprobarlo, dónde va el binario, cómo ejecutarlo una vez y cómo dejarlo corriendo cuando termines de mirarlo.

LinuxUn tar.gz, /usr/local/bin y una unidad de systemd blindada.

macOSEl archivo darwin, el atributo de cuarentena y un agente o demonio de launchd.

WindowsUn zip, PowerShell y cmd, una tarea programada y lo que de verdad cambia allí.

Conseguir el binario

Script

curl -fsSL https://raw.githubusercontent.com/jmrplens/ghchronicle/main/install.sh | bash

En Windows, desde PowerShell:

irm https://raw.githubusercontent.com/jmrplens/ghchronicle/main/install.ps1 | iex

Cualquiera de las dos deduce la plataforma, coge la release más nueva y se niega a instalar nada cuya suma de verificación no sea la que publicó la release.

Release

Coge el archivo de tu plataforma en la página de releases. Se compilan archivos para Linux, macOS y Windows, en amd64 y arm64, y se publican como tar.gz (zip en Windows).

tar -xzf ghchronicle_2.6.5_linux_amd64.tar.gz
sudo install -m 755 ghchronicle /usr/local/bin/

Go

go install github.com/jmrplens/ghchronicle/v2/cmd/ghchronicle@latest

Necesita una cadena de herramientas de Go, y compila desde fuente la etiqueta más reciente. El /v2 es parte de la ruta: sin él, Go se queda con la 1.0.0, la última versión cuya ruta de módulo acepta, y no avisa.

Contenedor

docker run -v $PWD/config.yaml:/config.yaml:ro \
  -v ghchronicle-state:/var/lib/ghchronicle -e GITHUB_TOKEN \
  ghcr.io/jmrplens/ghchronicle -config /config.yaml

Distroless, estático y corriendo como uid 65532. Con state_file dentro de /var/lib/ghchronicle el volumen guarda el estado, y es de ese usuario desde el principio, porque lo es el directorio propio de la imagen: qué tiene que ser escribible.

Action

- uses: jmrplens/ghchronicle@v2
  with:
    token: ${{ secrets.GHCHRONICLE_TOKEN }}
    mode: once
    config: .github/ghchronicle.yaml

Una Action compuesta que descarga un binario de release, así que el runner no necesita cadena de herramientas de Go.

Elegir dónde corre

El colector envía por push a todos los almacenes que soporta, así que no hace falta que sea alcanzable desde ningún sitio. Necesita alcanzar GitHub y alcanzar sus bases de datos. Esa es la única restricción, y es lo que hace viables las cuatro opciones. Tres de las cuatro quieren una máquina propia: systemd, Docker y cron. GitHub Actions es la que no. Las páginas por sistema de arriba son donde vive el planificador, uno por sistema: systemd o cron en Linux, launchd en macOS y una tarea programada en Windows.

systemdUn servicio permanente en una máquina propia. La opción por omisión: el fichero de estado persiste, el horario es el de la propia herramienta y la unidad se puede blindar a fondo.

DockerLo mismo en un contenedor. Monta un volumen escribible para el fichero de estado y para cualquier destino de fichero.

GitHub ActionsSin máquina propia. Va bien para la tarjeta y para una pasada programada; el fichero de estado no sobrevive entre ejecuciones salvo que lo guardes en caché.

cron`-once` ejecuta una pasada y termina, que es todo lo que necesita un planificador. Deja el fichero de estado en una ruta persistente.

Los tres modos de ejecución

Orden	Hace
ghchronicle -config config.yaml	Corre indefinidamente, cada familia con su cadencia
ghchronicle -config config.yaml -once	Una pasada y termina
ghchronicle -config config.yaml -backfill	Recorre cada superficie hasta el final, esperando al límite de peticiones

Más dos que no escriben nada: -list imprime los repositorios en alcance, y -card ... -card-only dibuja el SVG sin tocar una base de datos.

El fichero de estado es lo único que debe persistir

Corra como corra, deja state_file en una ruta que sobreviva a un reinicio, en un directorio en el que el colector pueda escribir, porque el fichero de caché y el registro de escrituras viven a su lado. Sin él cada ejecución recoge todas las familias diga lo que diga su cadencia, y vuelve a recorrer la lista de estrellas, el historial entero de estrellas y las pull requests en coautoría.

Actualizar

Una versión nueva se instala encima de la anterior como se instaló esa, y la configuración y el estado pasan tal cual. Cómo son las primeras horas tras ella, de la 2.5.x a la 2.6.x y a la 2.6.1, está en actualizar.