certremind/README.md

CertRemind

CertRemind monitors the TLS/SSL certificate expiry dates of registered HTTPS sites and sends reminders through in-app alerts, webhooks, and browser push notifications.

Requirements

• Node.js v22
• pnpm
• Docker Compose
• PostgreSQL
• OpenSSL

Development Setup

pnpm install
docker compose up -d postgres
pnpm dev

Development URLs:

Frontend: http://127.0.0.1:5173/
API:      http://127.0.0.1:3000

Docker Compose

Production-like startup:

docker compose up -d --build

If your Docker CLI does not provide the Compose v2 subcommand, use docker-compose with the same arguments.

Production URL:

App: http://127.0.0.1:3000/

This starts PostgreSQL, the Web/API application, and the hourly certificate monitor worker. The application container serves the built React assets from dist through the Hono server.

Docker-based development startup:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

Development URLs:

Frontend: http://127.0.0.1:5173/
API:      http://127.0.0.1:3000

The Compose application port mappings bind to 127.0.0.1 only, so the application ports are not published on external network interfaces. PostgreSQL is not published to the host; only the app and monitor-worker services can reach it through the internal Compose network. Inside containers, the application binds to 0.0.0.0 through HOST=0.0.0.0; host exposure is controlled by Compose.

Run the one-shot certificate monitor:

pnpm monitor:once

Run the certificate monitor worker every hour:

pnpm monitor:worker

Run quality checks:

pnpm lint
pnpm test
pnpm exec vite build

Database

The initial schema is in db/schema.sql. Docker Compose loads it when the PostgreSQL volume is first created.

If an existing database volume is already present, schema changes are not reapplied automatically. Apply the relevant ALTER TABLE statements from db/schema.sql, or recreate the development volume when data loss is acceptable.

Environment Variables

Copy .env.example to .env for local development.

Name	Required	Default	Purpose
NODE_ENV	No	development	Runtime mode. production enables secure cookies.
HOST	No	127.0.0.1	Server listen host. Compose sets this to 0.0.0.0 inside containers.
PORT	No	3000	API server port.
DATABASE_URL	No	postgres://certremind:certremind@localhost:5432/certremind	PostgreSQL connection string.
COOKIE_SECRET	Reserved	none	Reserved for future signed-cookie support.
VAPID_PUBLIC_KEY	For Push	empty	Browser Push public key.
VAPID_PRIVATE_KEY	For Push	empty	Browser Push private key. Push delivery fails gracefully if missing.
VAPID_SUBJECT	For Push	mailto:admin@example.com	VAPID contact subject.
OPENSSL_PATH	No	openssl	OpenSSL executable path. On Windows, the app can also detect Git's bundled openssl.exe.
CAPTCHA_PROVIDER	No	off	Auth CAPTCHA provider. Use turnstile, hcaptcha, or off.
CAPTCHA_SITE_KEY	When CAPTCHA enabled	empty	Public site key used by the login/register widget.
CAPTCHA_SECRET_KEY	When CAPTCHA enabled	empty	Server-side secret key used to verify CAPTCHA tokens.
CAPTCHA_VERIFY_TIMEOUT_MS	No	3000	Timeout for provider verification requests.

For local host execution, DATABASE_URL normally points to localhost:5432. For Docker Compose services, it points to the internal service name: postgres://certremind:certremind@postgres:5432/certremind.

CAPTCHA is disabled by default. To enable it, set CAPTCHA_PROVIDER to turnstile or hcaptcha and provide both keys. Login and registration then require a provider token, and TOTP logins require a fresh token for each POST.

Operational Notes

• Run pnpm monitor:worker as a long-lived Node process for hourly certificate checks.
• docker compose up -d --build runs the monitor worker as the monitor-worker service.
• pnpm monitor:once remains available for manual checks or external schedulers.
• The monitor limits concurrent external certificate checks and records per-site failures without stopping the whole run.
• Webhook URLs and monitored site URLs must be HTTPS and reject localhost/private IPv4 targets.
• The account profile timezone is used when formatting user-facing dates such as webhook alert expiry times. Webhook alert messages can be customized per user from the notification methods screen; if unset, CertRemind uses the default template.
• Existing browser Push subscriptions require valid VAPID keys to deliver successfully.