Skip to content

INSTALL.md

Latest commit

 

History

History
121 lines (85 loc) · 5.35 KB

INSTALL.md

File metadata and controls

121 lines (85 loc) · 5.35 KB
Raw

Installation

Package requirements

Debian and Ubuntu:

sudo apt-get update
sudo apt-get install perl libio-socket-ssl-perl ca-certificates

For source validation or contribution work, also install the developer-only tools:

sudo apt-get install make nodejs git

Verify the source before installing:

make check

That command runs the full public release gate. During development, make test-targeted and make test-fast provide shorter feedback loops; see the main README for the exact coverage of each profile. The targeted profile uses only synthetic local fixtures while proving webhook admission, reconciliation, persistent IRC fan-out and state recovery across process restarts.

Automated systemd installation

The installer creates an unprivileged irc-gitwatch service account, installs the executable under /opt/irc-gitwatch, installs the hardened unit, and creates /etc/irc-gitwatch.env only when it does not already exist. It does not enable or start the service.

sudo ./scripts/install.sh
sudoedit /etc/irc-gitwatch.env
sudo systemctl enable --now irc-gitwatch.service

The unit runs --config-check as ExecStartPre; a configuration error prevents the daemon from starting and is recorded in the journal:

sudo systemctl status irc-gitwatch.service
sudo journalctl -u irc-gitwatch.service -n 50 --no-pager

Manual systemd installation

sudo useradd --system --home-dir /var/lib/irc-gitwatch \
  --create-home --shell /usr/sbin/nologin irc-gitwatch
sudo install -d -m 0755 /opt/irc-gitwatch
sudo install -m 0755 irc-gitwatch.pl /opt/irc-gitwatch/irc-gitwatch.pl
sudo install -m 0644 systemd/irc-gitwatch.service /etc/systemd/system/
sudo install -m 0600 .env.example /etc/irc-gitwatch.env
sudo chown root:root /etc/irc-gitwatch.env
sudoedit /etc/irc-gitwatch.env
sudo systemctl daemon-reload
sudo systemctl enable --now irc-gitwatch.service

The unit's StateDirectory=irc-gitwatch creates /var/lib/irc-gitwatch with the correct service ownership.

To use only one Undernet channel, set the secondary explicitly empty in the environment file:

UNDERNET_CHANNEL_PRIMARY='#your-channel'
UNDERNET_CHANNEL_SECONDARY=
IRC_REQUIRED_TARGETS='undernet:#your-channel'

Add EpiKnet or Libera target ids to IRC_REQUIRED_TARGETS when those networks are enabled. --config-check prints the effective target ids and fails closed if a required one is absent.

GitHub token

Create a token for the account that can read the monitored repository. Use the narrowest repository selection and permissions compatible with the features you enable:

  • repository metadata/events for polling;
  • Actions read access for workflow monitoring and job enrichment;
  • repository traffic access for clone/view statistics.

GitHub's traffic endpoints require the token owner to have suitable access to the repository. IRC GitWatch degrades visibly when an optional endpoint returns 403; it does not silently relabel missing data.

Place the token only in /etc/irc-gitwatch.env, then enforce:

sudo chown root:root /etc/irc-gitwatch.env
sudo chmod 0600 /etc/irc-gitwatch.env

Webhook and TLS proxy

The daemon listens on loopback by default. Configure your reverse proxy to forward only the chosen webhook path and, if desired, separately protect dashboard routes with an ACL or authentication layer. When exposing the multi-repository dashboard, forward both its root and /repo/ so selector-generated deep links reach the same listener.

GitHub webhook settings (repeat on every repository named by GITHUB_REPO and GITHUB_REPOS):

  • URL: https://your-host.example/githubhook
  • Content type: application/json
  • Secret: same value as GITHUB_WEBHOOK_SECRET

Never terminate public TLS directly in the Perl daemon. Its HTTP server is intentionally compact and designed for a trusted local boundary.

First diagnostics

sudo systemctl status irc-gitwatch.service
sudo journalctl -u irc-gitwatch.service -n 100 --no-pager
curl --fail http://127.0.0.1:9510/livez
curl --fail http://127.0.0.1:9510/readyz
curl --fail http://127.0.0.1:9510/status.json

Useful one-shot checks are listed in the main README. --doctor performs network calls; --selftest is deterministic and does not require credentials.

Migrating or upgrading an existing GitHubWatch v0.29 instance

  1. Stop the old service cleanly so its latest state is saved.
  2. Run --state-check, then back up the primary state, its validated .bak copy when present, and the environment file.
  3. Install IRC GitWatch without starting it.
  4. Set GITHUB_REPO, optional GITHUB_REPOS, GITHUB_ACCOUNT and GITHUB_STATE_FILE explicitly.
  5. Copy the state file to /var/lib/irc-gitwatch/state.json, owner irc-gitwatch, mode 0600.
  6. Run --state-check, --config-check, --selftest and the packaged validation gate before starting the service.
  7. Start only the new service.

Do not run two instances against the same state file or IRC targets. Version 0.33 retains the v0.29 state schema and metrics prefix specifically to make migration uneventful. Existing state becomes the primary repository's state; each new repository establishes its own Events and Actions baseline without replay. If an optional secondary IRC channel is removed, saved pending records are reconciled against the remaining targets at startup without replaying acknowledgements already recorded for them.