Skip to content
Guide

Monitoring a small backend: uptime, logs, and Telegram alerts

By Fayez AlshamiPublished: Updated: 7 min read
TL;DR

For one or two apps on a VPS, skip the full metrics stack at first. Hit the public URL from outside the machine, watch disk and systemd jobs locally, and ping a private Telegram chat only when state flips - not on every cron run.

A backend that looks fine over SSH can still be unreachable to customers. Nginx is up, the process is not. The disk is full, Postgres is in read-only, and you find out when someone writes on WhatsApp. For a small VPS I do not start with a full metrics stack. I start with three things: a check from outside the machine, a look at logs and disk on the machine, and a Telegram message when the state changes.

This sits on a server you already run, and on the deploy pipeline in Deploy to a VPS with GitHub Actions. It also watches the backup job from نسخ احتياطي تلقائي لقاعدة بيانات PostgreSQL. If the app accepts payments, pair this with Building reliable payment webhooks: an alert tells you the path is down, it does not replace idempotent handlers.

Use a private Telegram chat for ops, not the customer-facing Telegram payment bot. Mixing those chats is how a disk warning ends up in front of a buyer.

What is worth watching on a small backend

  • The public URL, over HTTPS, from a network that is not the VPS itself.
  • The app health route, for example GET /health, which should return 200 only if the process can talk to the database.
  • Disk space, especially the volume that holds Postgres and the backup directory.
  • Failures of systemd jobs you already rely on, such as the nightly dump.
  • Process crashes visible in docker compose logs or journalctl.

I do not page myself for a single 404, or for a CPU spike that lasts ten seconds, or for every warning line in the log. An alert that fires all day gets muted, and then the useful one is missed.

A check that runs only on the VPS will stay silent when the machine is down, when the network path is broken, or when Docker starts and the process never binds to the port. That is why the uptime check has to live somewhere else.

A Telegram bot that only talks to you

Create a bot with BotFather and copy the token. Then start a chat with the bot and get a chat id. For a private alert channel, add the bot to a small group you control and use that group's chat id (usually a negative number).

``bash # after you have sent the bot a message: curl -sS "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates" ``

Look for "chat":{"id": ...}. Store the token and the chat id on the VPS in a file that is not in Git, and in GitHub Actions secrets if the external check runs there.

``bash # /etc/ops-notify.env TELEGRAM_BOT_TOKEN=123456:replace-me TELEGRAM_CHAT_ID=-1001234567890 ``

``bash sudo chmod 600 /etc/ops-notify.env sudo chown root:root /etc/ops-notify.env ``

A tiny notifier, /usr/local/sbin/notify-telegram.sh:

``bash #!/usr/bin/env bash set -euo pipefail . /etc/ops-notify.env text=${1:?usage: notify-telegram.sh "message"} # Telegram caps a text message; keep alerts short. curl -sS -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \ --data-urlencode "chat_id=${TELEGRAM_CHAT_ID}" \ --data-urlencode "text=${text}" \ --data-urlencode "disable_web_page_preview=true" \ >/dev/null ``

``bash sudo chmod 700 /usr/local/sbin/notify-telegram.sh sudo /usr/local/sbin/notify-telegram.sh "ops notify is wired on $(hostname)" ``

If that message does not arrive, fix the token, the chat id, and whether the bot is a member of the group before you build anything else on top.

An uptime check that does not live on the VPS

The check should request the same URL customers use, and it should fail on a redirect to an error page, a timeout, or a certificate problem. A script I run from GitHub Actions on a schedule, and from a second machine if I have one:

```bash #!/usr/bin/env bash set -euo pipefail

URL=${URL:?set URL} TIMEOUT=${TIMEOUT:-15} STATE_FILE=${STATE_FILE:-/tmp/uptime-state} NOTIFY=${NOTIFY:-}

code=$(curl -sS -o /tmp/uptime-body -w "%{http_code}" \ --max-time "$TIMEOUT" "$URL" || true)

if [[ "$code" =~ ^2 ]]; then status=up else status=down fi

prev=unknown if [[ -f "$STATE_FILE" ]]; then prev=$(cat "$STATE_FILE") fi echo "$status" > "$STATE_FILE"

if [[ "$status" == "$prev" ]]; then exit 0 fi

host=$(echo "$URL" | awk -F/ '{print $3}') msg="uptime ${status}: ${host} (http ${code:-none})" echo "$msg"

if [[ -n "$NOTIFY" ]]; then "$NOTIFY" "$msg" fi

if [[ "$status" != up ]]; then exit 1 fi ```

Alert on the change, not on every run. You want one message when it goes down, and one when it comes back. A check that repeats "still down" every few minutes is noise. GitHub-hosted runners start with a fresh disk, so the state file does not survive between jobs. For many of the projects I run, a second machine holds that file and cron runs the script. Actions is the fallback when there is no second machine yet.

A workflow that runs the check from outside, .github/workflows/uptime.yml:

```yaml name: Uptime check

on: schedule:

  • cron: "/10 * * *"

workflow_dispatch:

jobs: check: runs-on: ubuntu-latest steps:

  • name: Hit /health

env: URL: https://example.com/health TELEGRAM_BOT_TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }} TELEGRAM_CHAT_ID: ${{ secrets.TELEGRAM_CHAT_ID }} run: | set -euo pipefail code=$(curl -sS -o /tmp/uptime-body -w "%{http_code}" \ --max-time 15 "$URL" || true) if [[ "$code" =~ ^2 ]]; then echo "up ($code)" exit 0 fi echo "down ($code)" curl -sS -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \ --data-urlencode "chat_id=${TELEGRAM_CHAT_ID}" \ --data-urlencode "text=uptime down: ${URL} (http ${code})" \ --data-urlencode "disable_web_page_preview=true" \ >/dev/null exit 1 ```

That workflow is blunt: it notifies whenever the job fails, so a long outage can repeat the message. I still use it as a first external signal. When the noise starts, I move the state file to a second host and leave Actions as a backup path.

Replace https://example.com/health with your real URL. /health should not require a cookie or a login. If you only check the homepage, a static Nginx error page can look "up" while the app is dead. Check the route that talks to the database.

Scheduled workflows can be delayed when GitHub is busy, and they pause on a repo that has had no activity for a long stretch. If uptime is important, do not rely on Actions alone. A cron job on another VPS, or a small uptime service you already pay for, should be the primary check. I am not naming a vendor here; the requirement is "from another network," not a particular logo.

Disk, memory, and jobs on the machine itself

When the server is up but the disk is not, the external check may still pass for a while. A local timer catches that.

``bash #!/usr/bin/env bash set -euo pipefail # alert if the data partition is at or above 85% used path=${1:-/} pct=$(df -P "$path" | awk 'NR==2 {gsub("%","",$5); print $5}') state=/var/lib/ops/disk-${path//\//_}.state mkdir -p /var/lib/ops prev=$(cat "$state" 2>/dev/null || echo ok) if (( pct >= 85 )); then echo alert > "$state" if [[ "$prev" != alert ]]; then /usr/local/sbin/notify-telegram.sh "disk ${pct}% on $(hostname):$path" fi exit 1 fi echo ok > "$state" if [[ "$prev" == alert ]]; then /usr/local/sbin/notify-telegram.sh "disk recovered ${pct}% on $(hostname):$path" fi ``

Point it at the volume that holds Docker and Postgres, which is not always /. Hook the backup service's OnFailure= from the PostgreSQL article to the same notifier. One quiet message at 02:20 is better than discovering a week later that no dump left the machine.

For logs, I do not tail production into Telegram. I keep docker compose logs --since 1h and journalctl -u docker -S "1 hour ago" as the first place I look after an alert. If a process restarts in a loop, docker compose ps and the restart count show it. You can add a short check that notifies when a container's RestartCount climbs, but start by reading the log after the uptime alert, not by piping every error line to your phone.

After a deploy, and after a payment path fails

A deploy from GitHub Actions can look green and still leave /health broken for a minute. The uptime check will catch that if it runs often enough. If you already fail the deploy script on a local health check, the external alert should stay quiet. When it does not, you have a case the script does not cover: TLS, DNS, or Nginx pointing at the old socket.

For payments, a 200 on /health does not prove the webhook path works. After an incident, send a test event or place a small transfer in a sandbox if you have one. The monitoring here tells you the site is reachable. The webhook article covers what to do with events that arrive twice or late.

Frequently asked questions

Is Prometheus or Grafana required?

No. They are useful when you have many machines or need history you query often. For one or two apps on a single VPS, an external HTTP check, a disk timer, and Telegram on state change get you the news that matters. You can add a metrics stack later without throwing this away.

How often should the check run?

I start at five or ten minutes. A one-minute check is possible, and it will also multiply false alarms from a short deploy. Match the interval to how long you can accept not knowing.

What if Telegram itself is down?

Then the alert does not arrive, and you still have the Actions job history and journalctl on the server. If that risk bothers you, add a second path later, such as email. I do not pretend a single chat is unbreakable.

Can the customer payment bot send these alerts?

It can, technically. I still keep them apart. An ops token and an ops chat can be revoked without touching the checkout conversation, and you will not paste a disk warning next to a transaction id.

Guides & comparisons

Need this built or connected for your business?

See services