119 lines
4.4 KiB
Markdown
119 lines
4.4 KiB
Markdown
# 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
|
|
|
|
```text
|
|
pnpm install
|
|
docker compose up -d postgres
|
|
pnpm dev
|
|
```
|
|
|
|
Development URLs:
|
|
|
|
```text
|
|
Frontend: http://127.0.0.1:5173/
|
|
API: http://127.0.0.1:3000
|
|
```
|
|
|
|
## Docker Compose
|
|
|
|
Production-like startup:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
|
|
```
|
|
|
|
Development URLs:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
pnpm monitor:once
|
|
```
|
|
|
|
Run the certificate monitor worker every hour:
|
|
|
|
```text
|
|
pnpm monitor:worker
|
|
```
|
|
|
|
Run quality checks:
|
|
|
|
```text
|
|
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.
|
|
- Existing browser Push subscriptions require valid VAPID keys to deliver successfully.
|