Add deployment documentation with cron and systemd examples
This commit is contained in:
@@ -0,0 +1,252 @@
|
||||
# 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/hhofmann/.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/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`:
|
||||
|
||||
```ini
|
||||
[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
|
||||
|
||||
```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/hhofmann/.local/bin/ghrel check --since 6h
|
||||
User=hhofmann
|
||||
Group=hhofmann
|
||||
```
|
||||
|
||||
### 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/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
|
||||
|
||||
```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
|
||||
- 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
|
||||
```
|
||||
|
||||
<dcp-message-id>
|
||||
</dcp-message-id>
|
||||
Reference in New Issue
Block a user