github_release_monitor/docs/deployment.md

Deployment

This document contains deployment examples for the GitHub Release Monitor (ghrel).

Prerequisites

Ensure ghrel is installed and accessible in your PATH:

which ghrel
# Example: /home/hhofmann/.local/bin/ghrel

Set your GitHub token:

export GH_TOKEN=ghp_your_token_here

Add repositories to monitor:

ghrel add signoz/signoz --mode releases
ghrel add zammad/zammad --mode tags

---

Cron / Crontab Check Deployment

Run periodic checks via cron to fetch new releases and tags.

Edit crontab

crontab -e

Examples

# Run check every 6 hours
0 */6 * * * GH_TOKEN=ghp_your_token_here /home/hhofmann/.local/bin/ghrel check --since 6h >> /opt/nicible/ghrel.log 2>&1

# Run check every 5 minutes
*/5 * * * * GH_TOKEN=ghp_your_token_here /home/hhofmann/.local/bin/ghrel check --since 5m >> /opt/nicible/ghrel.log 2>&1

# Run check daily at midnight
0 0 * * * GH_TOKEN=ghp_your_token_here /home/hhofmann/.local/bin/ghrel check --since 1d >> /opt/nicible/ghrel.log 2>&1

Notes

• Always use the full path to ghrel — cron runs with a minimal $PATH
• Use 2>&1 to capture both stdout and stderr in the log file
• Ensure the log directory exists and is writable: sudo mkdir -p /opt/nicible && sudo chown $USER /opt/nicible
• The --since flag should match or slightly exceed your cron interval to avoid missing entries
• Consider storing GH_TOKEN in a separate file and sourcing it from cron to avoid plaintext exposure

---

Systemd Daemon Service

Run ghrel as a background daemon that periodically checks for updates.

Service file

Create /etc/systemd/system/ghrel-daemon.service:

[Unit]
Description=GitHub Release Monitor Daemon
After=network-online.target

[Service]
Type=simple
Environment=GH_TOKEN=ghp_your_token_here
ExecStart=/home/hhofmann/.local/bin/ghrel daemon --interval 6h --pid-file /run/ghrel-daemon.pid --since 6h
Restart=on-failure
RestartSec=30
User=hhofmann
Group=hhofmann

[Install]
WantedBy=multi-user.target

Enable and start

sudo systemctl daemon-reload
sudo systemctl enable --now ghrel-daemon.service
sudo systemctl status ghrel-daemon.service

Notes

• --interval sets how often the daemon runs checks
• --since should match or slightly exceed --interval
• Adjust User and Group to match your system
• For better security, store the token in an environment file:

# /etc/systemd/system/ghrel-daemon.service.d/env.conf
[Service]
EnvironmentFile=/etc/ghrel/token.env

Then create /etc/ghrel/token.env:

GH_TOKEN=ghp_your_token_here

Set permissions: sudo chmod 600 /etc/ghrel/token.env

---

Systemd Timer Check Service

Run periodic checks using a systemd timer (preferred over cron for better logging and reliability).

Service file

Create /etc/systemd/system/ghrel-check.service:

[Unit]
Description=GitHub Release Monitor Check

[Service]
Type=oneshot
Environment=GH_TOKEN=ghp_your_token_here
ExecStart=/home/hhofmann/.local/bin/ghrel check --since 6h
User=hhofmann
Group=hhofmann

Timer file

Create /etc/systemd/system/ghrel-check.timer:

[Unit]
Description=Run GitHub Release Monitor Check every 6 hours

[Timer]
OnCalendar=*-*-* 00/6:00:00
Persistent=true

[Install]
WantedBy=timers.target

Enable and start

sudo systemctl daemon-reload
sudo systemctl enable --now ghrel-check.timer
sudo systemctl list-timers ghrel-check.timer

Check logs

journalctl -u ghrel-check.service

Notes

• OnCalendar=*-*-* 00/6:00:00 runs at 00:00, 06:00, 12:00, 18:00
• Persistent=true ensures missed runs execute after boot
• Use EnvironmentFile for token storage (see daemon section above)
• Common timer schedules:
  • Every 5 minutes: OnCalendar=*:0/5
  • Every hour: OnCalendar=*:00
  • Daily at midnight: OnCalendar=*-*-* 00:00:00

---

Systemd Serve Service

Run the RSS feed server as a persistent systemd service.

Service file

Create /etc/systemd/system/ghrel-serve.service:

[Unit]
Description=GitHub Release Monitor RSS Server
After=network-online.target

[Service]
Type=simple
ExecStart=/home/hhofmann/.local/bin/ghrel serve --host 127.0.0.1 --port 8765
Restart=on-failure
RestartSec=10
User=hhofmann
Group=hhofmann

[Install]
WantedBy=multi-user.target

Enable and start

sudo systemctl daemon-reload
sudo systemctl enable --now ghrel-serve.service
sudo systemctl status ghrel-serve.service

Notes

• The server reads the database on every request — no restart needed after ghrel check or daemon updates
• Use --host 127.0.0.1 for local-only access, or 0.0.0.0 for network access
• Combine with a reverse proxy (nginx, caddy) for external access:

# Example nginx location block
location /feed.xml {
    proxy_pass http://127.0.0.1:8765/feed.xml;
    proxy_set_header Host $host;
}

• Check logs with: journalctl -u ghrel-serve.service

---

Combined Deployment

A typical production setup combines the timer check service with the serve service:

# Periodic checks every 6 hours
sudo systemctl enable --now ghrel-check.timer

# Persistent RSS server
sudo systemctl enable --now ghrel-serve.service

Monitor both services:

systemctl status ghrel-check.service ghrel-serve.service
journalctl -u ghrel-check.service -u ghrel-serve.service --since today