# Formas de instalar

Formas de instalar ghchronicle: una página por sistema operativo, cinco maneras de poner el binario en marcha, y para qué sirve cada una.

Source: https://docs.jmrp.io/ghchronicle/es/install/

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.

- [Linux](https://docs.jmrp.io/ghchronicle/es/install/linux/): Un tar.gz, /usr/local/bin y una unidad de systemd blindada.

- [macOS](https://docs.jmrp.io/ghchronicle/es/install/macos/): El archivo darwin, el atributo de cuarentena y un agente o demonio de launchd.

- [Windows](https://docs.jmrp.io/ghchronicle/es/install/windows/): Un zip, PowerShell y cmd, una tarea programada y lo que de verdad cambia allí.

## Conseguir el binario

- **Script**

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

  En Windows, desde PowerShell:

  ```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](https://github.com/jmrplens/ghchronicle/releases). Se
  compilan archivos para Linux, macOS y Windows, en amd64 y arm64, y se
  publican como `tar.gz` (`zip` en Windows).

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

- **Go**

  ```sh
  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**

  ```sh
  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](https://docs.jmrp.io/ghchronicle/es/install/docker/#qué-tiene-que-ser-escribible).

- **Action**

  ```yaml
  - 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.

- [systemd](https://docs.jmrp.io/ghchronicle/es/install/systemd/): Un 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.

- [Docker](https://docs.jmrp.io/ghchronicle/es/install/docker/): Lo mismo en un contenedor. Monta un volumen escribible para el fichero de estado y para cualquier destino de fichero.

- [GitHub Actions](https://docs.jmrp.io/ghchronicle/es/install/actions/): Sin 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](https://docs.jmrp.io/ghchronicle/es/install/systemd/#cron-en-vez-de-un-servicio): `-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](https://docs.jmrp.io/ghchronicle/es/install/upgrading/).