# Formas de instalar

Una página por sistema operativo, cuatro maneras de poner el binario en marcha, y para qué sirve cada una.

Source: https://jmrplens.github.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](/ghchronicle/es/install/linux/): Un tar.gz, /usr/local/bin y una unidad de systemd blindada.

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

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

## Conseguir el binario

- **Go**

  ```sh
  go install github.com/jmrplens/ghchronicle/cmd/ghchronicle@latest
  ```

  Necesita una cadena de herramientas de Go, y compila desde fuente la
  etiqueta más reciente.

- **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_1.0.0_linux_amd64.tar.gz
  sudo install -m 755 ghchronicle /usr/local/bin/
  ```

- **Contenedor**

  ```sh
  docker run -v $PWD/config.yaml:/config.yaml:ro -e GITHUB_TOKEN \
    ghcr.io/jmrplens/ghchronicle -config /config.yaml
  ```

  Distroless, estático y corriendo como uid 65532.

- **Action**

  ```yaml
  - uses: jmrplens/ghchronicle@v1
    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](/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](/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](/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](/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.
> Es lo que evita que el recorrido completo de estrellas y el relleno año por
> año del calendario de contribuciones vuelvan a ocurrir en cada ejecución.