diff --git a/docs/deployment.md b/docs/deployment.md
new file mode 100644
index 0000000..c7c24c3
--- /dev/null
+++ b/docs/deployment.md
@@ -0,0 +1,282 @@
+# 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>