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:

```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 127.0.0.1 --port 8765
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
- 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>