# Linux

The whole path on Linux: the right archive, the signature, the PATH, a service, and building it yourself.

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

One static binary, `CGO_ENABLED=0`, so there is no C library to install and no
distribution to match. A release archive and a `PATH` entry is the whole
install; everything below that is about doing it deliberately.

## The one-line install

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

It works out the architecture, takes the newest release, checks the archive
against the checksum that release published, and puts the binary in
`/usr/local/bin` when that is writable. When it is not, it takes the first of
`~/.local/bin` and `~/bin` that exists and is already on your `PATH`, and falls
back to `~/.local/bin` when neither is. A checksum that does not match stops it
without installing anything, and there is no flag to skip that step. When
`cosign` 2.4.2 or newer is already on the machine it also verifies that the
checksum file itself came from the release workflow, and a signature cosign
does not confirm stops it, with what cosign said. An older cosign cannot read
the signature bundle, so then, as with no cosign at all, it says that only the
checksum was verified. It ends by running what it installed, so
the version you see is the file it just wrote, and it says so when another
`ghchronicle` earlier in your `PATH` still wins the name.

Pin a version, or choose where it goes:

```sh
curl -fsSL https://raw.githubusercontent.com/jmrplens/ghchronicle/main/install.sh | VERSION=2.6.5 BIN_DIR=~/bin bash
```

> **Reading it first is the whole point of a short script**
>
> Piping anything into a shell means running whatever that URL answers with
> today. `curl -fsSL <url> -o install.sh`, read it, then `bash install.sh`: it
> is the same script, and it is short enough to read.

The rest of this page is that same install done by hand, which is what to
follow when you want to know exactly what landed where, or when you would
rather not run a script you did not write.

## Pick the archive

Release archives are named
`ghchronicle_<version>_linux_<arch>.tar.gz`, with `<arch>` either `amd64` or
`arm64`. `uname -m` answers which.

| `uname -m` reports | The archive to take |
| ------------------ | ------------------- |
| `x86_64`           | `linux_amd64`       |
| `aarch64`          | `linux_arm64`       |

```sh
VERSION=2.6.5
arch=$(uname -m); case "$arch" in x86_64) arch=amd64 ;; aarch64) arch=arm64 ;; esac
base=https://github.com/jmrplens/ghchronicle/releases/download/v$VERSION
curl -fsSLO "$base/ghchronicle_${VERSION}_linux_${arch}.tar.gz"
```

> **Name the version rather than asking for the newest**
>
> The repository publishes a moving major tag beside the numbered releases,
> because the Action is listed on the Marketplace and that listing needs one.
> That tag's release carries **no files at all**, so never build a download URL
> from the major tag: there is nothing behind it to download. Take the version
> from the
> [releases page](https://github.com/jmrplens/ghchronicle/releases) and write
> it down, as above.

## Check what you downloaded

Two files are published beside the archives: `checksums.txt`, which holds the
SHA-256 of every archive, and `checksums.txt.sigstore.json`, which is a
signature over that file. So the chain is one signature and a digest: verify
the file, then verify the archive against the file.

1. Take the checksum file and its signature.

    ```sh
    curl -fsSLO "$base/checksums.txt"
    curl -fsSLO "$base/checksums.txt.sigstore.json"
    ```

2. Check the archive against it. `--ignore-missing` is what lets one line of a
   twelve-line file be checked without the other eleven archives being present.

    ```sh
    sha256sum --ignore-missing -c checksums.txt
    ```

    ```text
    ghchronicle_2.6.5_linux_amd64.tar.gz: OK
    ```

3. Check the checksum file itself, if you have
   [cosign](https://docs.sigstore.dev/cosign/system_config/installation/)
   2.4.2 or newer. An older one cannot read the bundle and fails whatever the
   file says.

    ```sh
    cosign verify-blob \
      --certificate-identity-regexp 'https://github.com/jmrplens/ghchronicle/.github/workflows/release.yml@refs/tags/.*' \
      --certificate-oidc-issuer https://token.actions.githubusercontent.com \
      --bundle checksums.txt.sigstore.json \
      checksums.txt
    ```

    ```text
    Verified OK
    ```

The signing is keyless: there is no public key to fetch and no private key for
anyone to lose, because the identity being verified is the workflow that ran,
recorded in a public transparency log. That is what the two `--certificate`
flags say, and why they are not optional: without them cosign would confirm
that somebody signed the file, which is not the question.

Then let it write the configuration:

```sh
ghchronicle -setup
```

It asks for a token and where the numbers go, checks each answer against the
thing it names, and writes a `config.yaml` and, if you want one, a systemd
unit. The installer above offers to run it as its last step.

## Put it on the PATH

The archive holds three files and no directory, so extract it somewhere you
meant to.

- ghchronicle_VERSION_linux_ARCH.tar.gz
  - ghchronicle the binary
  - LICENSE
  - README.md

- **For everyone**

  ```sh
  tar -xzf "ghchronicle_${VERSION}_linux_${arch}.tar.gz" ghchronicle
  sudo install -m 755 ghchronicle /usr/local/bin/
  ghchronicle -version
  ```

- **For one account**

  ```sh
  mkdir -p ~/.local/bin
  tar -xzf "ghchronicle_${VERSION}_linux_${arch}.tar.gz" -C ~/.local/bin ghchronicle
  chmod 755 ~/.local/bin/ghchronicle
  ghchronicle -version
  ```

  `~/.local/bin` is on the `PATH` of most distributions already. If
  `ghchronicle -version` answers "command not found", it is not on yours.

`-version` answers with one line: the release number, then the commit and
the build date of that release.

```text
ghchronicle 2.6.5 (commit <commit>, built <date>)
```

## Run it once

The binary needs a configuration file and a token, and
[the quickstart](https://docs.jmrp.io/ghchronicle/start/quickstart/) writes both in six steps. With
those in place:

```sh
ghchronicle -config config.yaml -list   # what would be collected
ghchronicle -config config.yaml -once   # one sweep, then exit
```

## Keep it running

[systemd](https://docs.jmrp.io/ghchronicle/install/systemd/) is the arrangement this documentation
treats as the default on Linux, and the unit there is hardened rather than
minimal, because this is very likely the only process on the host holding a
GitHub token with read access to every repository of an account. A service
started on a state file nothing has written yet brings its eleven families of
six hours or more into the store over its first two and a half hours, one a
sweep, and only that once; the systemd page says why.

A scheduler works too:
[cron with `-once`](https://docs.jmrp.io/ghchronicle/install/systemd/#cron-instead-of-a-service) is
a single line, at the cost of giving every family the same cadence.

## Build it from source

Go 1.27.2 or newer is what the module declares. Nothing else is needed: the
build sets `CGO_ENABLED=0`, so there is no compiler and no header package to
find.

- **go install**

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

  Lands in `$(go env GOPATH)/bin`, which is `~/go/bin` unless you moved it,
  and that directory has to be on your `PATH`.

  A binary built this way has no commit or build date to report: those two
  are stamped by the release build and by nothing else, and a module
  downloaded through the proxy carries no checkout to read them from.
  `-version` names what the build does record instead, the module version
  the go command fetched and the Go release that compiled it:

  ```text
  ghchronicle 2.6.5 (module v2.6.5, built with <go version>)
  ```

  The first version comes from the `VERSION` file the module embeds.

- **make**

  ```sh
  git clone https://github.com/jmrplens/ghchronicle
  cd ghchronicle
  make build      # into bin/ghchronicle
  make install    # into GOBIN, stamped like a release build
  ```

  `make build` stamps the version, the short commit and the commit date, so
  `-version` says exactly which tree it came from. `make` with no target
  lists every target there is.

## Where the files go

The collector looks for a configuration file in no particular place: `-config`
defaults to `config.yaml` **relative to the working directory**, and there is
no search path behind it. So the path is a decision you make once and then pass
on every invocation. What the rest of this documentation assumes:

| File               | Path                               | Mode                        |
| ------------------ | ---------------------------------- | --------------------------- |
| Configuration      | `/etc/ghchronicle/config.yaml`     | world readable, no secrets  |
| Tokens             | `/etc/ghchronicle/ghchronicle.env` | `600`                       |
| State, ledger, cache | `/var/lib/ghchronicle/`          | written by the service user |

`state_file` has a default of its own, `ghchronicle-state.json` in the working
directory, with the write ledger beside it as
`ghchronicle-state-written.bin` and the cache as `ghchronicle-state-cache.bin`.
That default is fine for a first run in a directory you made, and wrong for a
service, whose working directory is not something to rely on. Set it.