# Deployment This document contains deployment examples for the GitHub Release Monitor (`ghrel`). ## Prerequisites Ensure `ghrel` is installed and accessible in your PATH: ```bash which ghrel # Example: /home/youruser/.local/bin/ghrel ``` Set your GitHub token: ```bash export GH_TOKEN=ghp_your_token_here ``` Add repositories to monitor: ```bash 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 ```bash crontab -e ``` ### Examples ```cron # 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: > ```bash > echo 'GH_TOKEN=ghp_your_token_here' | sudo tee /etc/ghrel/token.env > sudo chmod 600 /etc/ghrel/token.env > ``` > Then in crontab: > ```cron > 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: > ```bash > 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: > ```cron > 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`: ```ini [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 ```bash 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: ```ini # /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`: ```ini [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`: ```ini [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 ```bash sudo systemctl daemon-reload sudo systemctl enable --now ghrel-check.timer sudo systemctl list-timers ghrel-check.timer ``` ### Check logs ```bash 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`: ```ini [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 ```bash 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: ```nginx # 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: ```bash # 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: ```bash systemctl status ghrel-check.service ghrel-serve.service journalctl -u ghrel-check.service -u ghrel-serve.service --since today ```