P—04 · DevelopmentIn progress

Website Health Monitor

A Go service that checks around the clock that my projects are up and actually working — with a web UI, an API and history in PostgreSQL.

Code

Role: Requirements, architecture, Go development with Claude Code
Period: 2026.01 → …
Status: In progress
Stack: Go · PostgreSQL · Docker · GitHub Actions · Grafana

Interface

01 / 05

Project overviewDown targets on top, the summary "Down: 1 of 7", last check, response time and 24-hour uptime. The targets are real addresses of this portfolio.

Problem

Links to my pet projects go to employers, and a link must never open a dead service. The projects live on a VPS and free hosting — they fall asleep, respond after a cold start, and a free Supabase database pauses after a week without requests. Learning about an outage from a recruiter is too late.

Solution

The monitor checks every target on a schedule — not just the response code but also a keyword on the page — writes the result to PostgreSQL and shows an "all green / something is down" summary with 24-hour uptime. Targets are added, changed and disabled in the web UI or via the API and are picked up without a restart.

I wrote the first version in January as a Go learning project. In October I came back to it with a new goal — watching the projects in this portfolio — ran an audit, found 10 issues and drew up a 7-stage plan. The code is written with Claude Code along that plan with a decision log; three stages are done.

Goals

01Learn about an outage before an employer does
02Check that a project works, not just that it responds
03Add and disable projects without rebuilding
04Keep free-tier services awake

Features

Response code and keyword checksPer-target interval, timeout and headersChanges apply on the flyWeb UI with a summary and 24-hour uptimeJSON API for targetsBasic Auth and CSRF protectionEmbedded PostgreSQL migrationsDocker, a healthcheck and CI with tests

Key requirements

ID	Requirement	Priority
FR-01	A target is up if the response has the expected code (any 2xx after redirects by default) and, if set, contains the keyword.	Must
FR-02	Adding, changing and disabling a target apply without restarting the service.	Must
FR-03	A target is never checked in parallel with itself.	Must
FR-04	Interval at least 30 s; timeout at most 120 s and less than the interval.	Must
FR-05	Telegram alerts on outage and recovery — without spam.	Should
NFR-01	Stopping or deploying the service produces no false outages.	Must
NFR-02	UI and API require a password; /healthz is open for external monitoring.	Must
NFR-03	The DB schema changes only through new migrations; old data is carried over.	Must

Scenarios

OwnerA project goes down

01A check does not find the keyword: the page returned 200 but it is an error stub
02The result with the reason is written to health_checks
03In the UI the target moves to the top in red; the summary says "1 down"
04After stage 5 — a Telegram message, and another on recovery

OwnerA new portfolio project

01Adds a target in the form: URL, keyword, a timeout for cold starts
02The server validates the settings and saves the target
03The scheduler starts checking right away — no restart

Timeline

2026.01First versionChecks from a list in code, PostgreSQL, Docker, CI with tests, Grafana output.
2026.10Stage 0: audit and planA new goal — monitoring the portfolio; 10 issues found and a 7-stage plan.
2026.10Stages 1–2: core and targets in the DBStatus logic, timeouts, migrations, pgx, graceful shutdown; a targets table, keywords, headers, live reload.
2026.10Stage 3: UI and APIA web UI without JS frameworks, a JSON API, validation, Basic Auth, CSRF protection, /healthz.
NextStages 4–7Grafana as code, Telegram alerts, quality and CI, deployment to the VPS with external monitoring of the checker itself.

Challenges

"Responds" is not "works"A broken app may return 200 with an error page. So a target has a keyword searched for in the first megabyte of the response.

False outages on deployChecks interrupted by a service stop or a target change are discarded, and the processor writes every result before the channel closes.

Target changes without a restartA goroutine per target plus a semaphore instead of a worker pool: the scheduler reconciles the list with the DB and starts, stops or restarts checks precisely.

Basic Auth and CSRFBrowsers attach Basic Auth to requests from other sites by themselves. Forms and the API are guarded by http.CrossOriginProtection from Go 1.25.

Outcome

Three of seven stages are done — about 3,200 lines of Go including 34 tests, integration ones on PostgreSQL among them. The service checks targets, applies changes on the fly and shows a summary with uptime.

Next — a Grafana dashboard from the repository, Telegram alerts and deployment to the VPS next to the projects it watches.

Technologies

#Go #PostgreSQL #Docker #GitHub Actions #Grafana

§ 2.1

Components

A single Go binary. The scheduler keeps a goroutine per target, and a semaphore caps concurrent checks. Results go through a channel to the processor and are saved to PostgreSQL; the web UI and API work with the same database and notify the scheduler of changes.

FIG. 04 — components

X 000 · Y 000

01
WEB · APITarget list with status and uptime, forms, JSON API; after a change it asks the scheduler to reload targets.
02
SCHEDULERReconciles goroutines with the target list in the DB; a semaphore caps concurrent checks.
03
PROJECTSPortfolio projects: the response code and a keyword in the body are checked.
04
POSTGRESTargets and check history; embedded migrations.
05
PROCESSORReceives results from the channel and writes them to the database until the channel closes.
06
GRAFANAUptime, response time and outage history.

§ 2.2

One check

Participants

01 · SCHEDULERTime to checkThe target's ticker with its interval or the default.
02 · SCHEDULERTake a slotA semaphore limits concurrent checks (WORKERS).
03 · WORKERRequestGET with the target's headers and a context timeout.
04 · WORKERVerdictExpected code and the keyword in the first megabyte; the body is drained for keep-alive.
05 · PROCESSORSaveCode, response time and error reason; failures interrupted by shutdown are discarded.
06 · WEBShowDown targets first, 24-hour uptime.

§ 2.3

Changing a target on the fly

Participants

01 · OWNEREdit a targetThe form or PUT /api/targets/{id}.
02 · WEBValidateErrors — 422 with the input kept.
03 · POSTGRESSaveupdated_at is bumped.
04 · SCHEDULERReloadA non-blocking request; several calls collapse into one.
05 · SCHEDULERReconcileNew — start, deleted and disabled — stop, changed — restart.

§ 2.4

Data model

NULL in target settings means "use the default". The URL is stored with every check on purpose — the history shows what was checked at the time. Deleting a target deletes its history; to keep it, the target is disabled instead.

TARGETS10 f.

idserialPK

nametext

urltext

expected_statusint?

keywordtext?

headersjsonb

interval_secondsint?

timeout_secondsint?

enabledbool

updated_attimestamptz

HEALTH_CHECKS8 f.

idserialPK

target_idintFK

urltext

is_upbool

status_codeint?

response_time_msint

errortext?

checked_attimestamptz

SCHEMA_MIGRATIONS3 f.

versionintPK

nametext

applied_attimestamptz

Relations · 1

TARGETS— 1 : N →HEALTH_CHECKS

§ 2.5

API and integrations

GET/healthzNo password: database ping, 200 or 503 — for Docker and external monitoring
GET/api/targetsTargets with status: up, down, pending or disabled, last check, 24-hour uptime
POST/api/targetsCreate a target: 201, unknown fields — 400, validation errors — 422
PUT/api/targets/{id}Replace a target entirely; the scheduler applies it at once
DELETE/api/targets/{id}Delete a target with its history

PostgreSQLpgx/v5 · pgxpoolEmbedded migrations with an advisory lock, check history and targets.
GrafanaSQLUptime and response-time charts; stage 4 brings a dashboard as code and a read-only user.
Telegram (stage 5)Bot APIDown after N consecutive failures, and recovery.

§ 2.6

Key decisions

Decision 01

A goroutine per target and a semaphore

Choice: Each target is checked sequentially in its own goroutine; a semaphore sets the overall limit.
Rationale: A target is never checked in parallel with itself, and adding, stopping or restarting one target is simple.
Alternatives: A worker pool with a job queue — more channels and a harder shutdown.

Decision 02

Own migrations on embed

Choice: About 100 lines instead of goose or golang-migrate; migrations live in the binary and run on start.
Rationale: No extra dependencies, and the database created by the first version migrated without data loss.

Decision 03

UI on html/template

+ Pros: One binary, no frontend build; The only JS is a delete confirmation
− Trade-offs: The list refreshes by reloading the page every 30 s

Decision 04

The target list is re-read, not listened to

Choice: Every 10 s and right after an API change, instead of LISTEN/NOTIFY.
Rationale: Simpler, and survives a database reconnect.

Next · P—01Mito