---

The app is feature complete and works as intended for tracking domain registration and SSL certificate expiry. Feel free to use it, but as of now, no new features will be added. ✌️

---

Domain Watch

A self-hosted dashboard for monitoring domain registration and SSL certificate expiry, with scheduled checks, configurable alerts, and SQLite storage - deployable as a single Docker container.

Table of Contents

1. About The Project
   • Built With
   • Features
2. Getting Started
   • Running with Docker (recommended)
   • Running without Docker
3. How checks work
   • SSL
   • Registration expiry
   • Scheduled vs manual checks
   • Errors
4. Settings and API (in-app)
   • In-app settings
   • API overview
5. Notes
6. License

About The Project

Domain Watch is a self-hosted dashboard for tracking domain registration and SSL certificate expiry. Add the domains you care about and the app keeps an eye on renewal dates, surfaces what needs attention, and runs checks on a schedule you control.

No external database required - everything runs in a single Node.js process with SQLite.

Built With

• better-sqlite3 — embedded SQLite storage
• whoiser — WHOIS registration lookups
• Node.js tls — live SSL certificate checks
• RDAP over HTTPS — registration lookup fallback when WHOIS fails

Features

Domain tracking

• Add domains individually or in bulk, with optional alias, client/description, notes, and renewal link
• Optional SSL monitoring per domain (disable for parked or non-HTTPS domains)
• Hide domains without deleting them
• Snooze alerts while you renew
• Manual registration expiry date when WHOIS/RDAP is unavailable
• Mark domains as renewed (with undo)
• Per-domain check interval override (24h, 48h, 72h, or weekly — or use the global default)

Organization

• Groups with custom sort order (drag-and-drop in custom sort mode)
• Collapsible group sections
• Group filter and search across domains, aliases, and descriptions
• Group defaults for renewal links and description prefixes
• Bulk actions: move to group, snooze, hide/unhide, toggle SSL monitoring

Checks & alerts

• Automatic checks on a configurable interval (1–24 hours, default 24h)
• SSL via live TLS handshake (issuer, expiry, hostname mismatch detection)
• Registration expiry via WHOIS with RDAP fallback
• 24-hour cache for successful registration lookups (reduces registry rate limits)
• Manual “Check now” per domain, per group, or for everything
• Configurable warning/critical day thresholds
• Configurable “check failures” threshold (days without a successful check)
• “Needs attention” panel for expiring/critical domains
• “Check failures” panel for domains past the failing-check threshold
• Scheduler health banner when global checks may have stopped (dismissible)
• “Expiring this month” calendar panel (SSL + domain dates)

Dashboard

• Stat cards: total, SSL valid %, expiring soon, critical, healthy, average days left
• Registrar and SSL issuer breakdown panels
• Status filters, smart filters (lookup failed, manual expiry, SSL off, snoozed, renewed), and multiple sort modes
• Customize dashboard (grid icon): show/hide and reorder panels, stat cards, toolbar items, and domain list options
• Custom accent colors for light and dark mode
• Domain detail panel with check history chart, renewal detection, and lookup freshness
• Privacy mode (masks domain names in the UI)
• Light/dark theme

Backup & restore

• Export full backup as JSON (v3, includes check history) or spreadsheet-friendly CSV
• Import JSON with merge (skip duplicates) or replace all data (with confirmation)
• Import preview before applying; v2/v3 backups supported (nickname or alias field)
• Settings included in JSON export

Deployment

• Single Docker container with health check
• PWA support (installable; offline shell and cached domain/group data via service worker)
• GET /api/health for Docker HEALTHCHECK and external uptime monitors

(back to top)

Getting Started

Running with Docker (recommended)

1. Run the following command

docker compose up -d --build

2. Open http://localhost:3000.

Data is stored in the named Docker volume domain_data, so it survives container restarts and rebuilds.

Docker configuration

Variable	Default	Description
PORT	3000	Port the app listens on inside the container
DATA_DIR	/app/data	Directory for the SQLite database
NODE_ENV	production	Set automatically in the image

Check interval, alert thresholds, timezone, failing-check days, and other runtime options are configured in the app under Settings (gear icon). They are stored in SQLite and persist across restarts. Dashboard layout and theme accents are stored in the browser (localStorage).

The compose file includes a health check that polls GET /api/health every 30 seconds.

Example: custom host port

services:
  domain-tracker:
    ports:
      - "8080:3000"

Running without Docker

Requires Node.js 18+ (the Docker image uses Node 20).

1. Install dependencies and start the server:

npm install
npm start

The app listens on http://localhost:3000 by default. The database is stored in ./data unless you set DATA_DIR.

2. To store the database elsewhere (optional):

DATA_DIR=/var/lib/domain-watch npm start

(back to top)

How checks work

SSL

Opens a TLS connection to domain:443, reads the certificate, and computes days until expiry. Also records the issuer and flags hostname mismatches.

Registration expiry

1. Queries WHOIS (throttled to avoid hammering registries)
2. Falls back to RDAP if WHOIS fails
3. Caches successful lookups for 24 hours on scheduled runs

Manual checks (“Check now”, “Check all”) always bypass the cache so renewals are picked up immediately.

If both WHOIS and RDAP fail, you can set a manual expiry date. The domain’s SSL status is still tracked normally.

Scheduled vs manual checks

• Scheduled: runs every N hours (configured in Settings), uses registration cache, respects per-domain check intervals, and staggers domains to avoid rate limits
• Manual: forces a fresh registration lookup and runs immediately

Errors

Failed checks store the error on the domain row. The UI shows the error inline - stale data is not presented as current.

Settings and API (in-app)

In-app settings

Setting	Default	Description
Check interval	24 hours	How often scheduled checks run (min 1 hour)
Warning threshold	30 days	Days left before “expiring” status
Critical threshold	7 days	Days left before “critical” status
Failing check days	7 days	Flag domains with no successful check in this many days
Time format	24-hour	12-hour AM/PM also available
Timezone	Browser default	Used for displayed dates
Check history max	30 per domain	Rolling log size
Check history retention	90 days	How long log entries are kept

API overview

Endpoint	Description
GET /api/health	{ ok, lastCheck, domainCount } — for monitoring
GET /api/meta	Scheduler info, thresholds, schedulerStale flag
GET /api/domains	All domains
GET /api/domains/failing	Domains with failing checks
GET /api/stats	Dashboard statistics (includes registrar/issuer breakdown)
PATCH /api/domains/bulk	Bulk update domains (ids, groupId, snoozeDays, isHidden, monitorSsl)
GET /api/export	Full JSON backup (v3: domains, groups, settings, check history)
GET /api/export/csv	CSV export
POST /api/import/preview	Preview import counts before applying
POST /api/import	Import backup (mode: "merge" or "replace")
POST /api/check-all	Run checks now (optional groupId)

All other CRUD routes for domains, groups, settings, and history are available under /api/.

(back to top)

Notes

• No authentication — intended for trusted local or private network use. Do not expose directly to the internet without a reverse proxy and access control.
• WHOIS/RDAP limits — some registries rate-limit or hide expiry dates (especially with privacy protection). Manual expiry and the registration cache help here.
• Renewal detection — if expiry jumps by 60+ days between checks, a renewal is auto-detected and surfaced in the detail panel.

(back to top)

License

Distributed under the GPL-3.0 License. See LICENSE.txt for more information.

(back to top)