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/youruser/.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/youruser/.local/bin/ghrel check --since 6h >> /var/log/ghrel/ghrel.log 2>&1

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

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

Warning

Never store your GitHub token as plaintext in crontab. Crontab files may be readable by other users on the system. Use one of these alternatives instead:

Option 1: Environment file (recommended) Create a restricted environment file and source it from cron:

echo 'GH_TOKEN=ghp_your_token_here' | sudo tee /etc/ghrel/token.env
sudo chmod 600 /etc/ghrel/token.env

Then in crontab:

0 */6 * * * . /etc/ghrel/token.env && /home/youruser/.local/bin/ghrel check --since 6h >> /var/log/ghrel/ghrel.log 2>&1

Option 2: Wrapper script Create a script with restricted permissions:

cat > /var/log/ghrel/ghrel-check.sh << 'EOF'
#!/bin/bash
export GH_TOKEN="ghp_your_token_here"
exec /home/youruser/.local/bin/ghrel check --since 6h
EOF
chmod 700 /var/log/ghrel/ghrel-check.sh

Then in crontab:

0 */6 * * * /var/log/ghrel/ghrel-check.sh >> /var/log/ghrel/ghrel.log 2>&1

Option 3: Use systemd timer instead (see below — preferred over cron)

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 /var/log/ghrel && sudo chown $USER /var/log/ghrel
• The --since flag should match or slightly exceed your cron interval to avoid missing entries

---

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/youruser/.local/bin/ghrel daemon --interval 6h --pid-file /run/ghrel-daemon.pid --since 6h
Restart=on-failure
RestartSec=30
User=youruser
Group=youruser

[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/youruser/.local/bin/ghrel check --since 6h
User=youruser
Group=youruser

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/youruser/.local/bin/ghrel serve --host 0.0.0.0 --port 8765 --base-url http://your-server-ip
Restart=on-failure
RestartSec=10
User=youruser
Group=youruser

[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
• When binding to 0.0.0.0, use --base-url to set the correct hostname in feed links. The port is auto-appended from --port, so only the scheme and host are needed (e.g., http://192.168.1.100)
• 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