Dead Man Notifier

A REST service for monitoring service health with email notifications.

Quick Start

1. Install dependencies:

   npm install

2. Configure the service: Edit config.yaml with your server, database, email settings and services.

3. Start the server:

   npm start
   # or
   node src/index.js serve

4. Test a service ping:

   curl -X PUT http://localhost:3000/438c41d2-f4d8-4697-aaa6-ab7bfd02b07d/ok

5. Send logs with a file:

   # Correct way - preserves newlines and special characters
   curl -X PUT http://localhost:3000/438c41d2-f4d8-4697-aaa6-ab7bfd02b07d/ok --data-binary @logfile.txt
   
   # Alternative - with explicit content type
   curl -X PUT http://localhost:3000/438c41d2-f4d8-4697-aaa6-ab7bfd02b07d/ok \
     -H "Content-Type: text/plain" \
     --data-binary @logfile.txt

   Note: Using -d @file will URL-encode the content and convert newlines to literal \n characters, which may not display correctly in logs.

CLI Commands

• dms serve - Start the REST server
• dms list - Show current service states
• dms logs - Show latest events
• dms cron - Start cron job service
• dms cron --init - Setup system cron entry

Command Line Options

All commands support the -c, --config <path> option to specify a custom config file:

dms serve --config /data/config.yaml
dms list --config /etc/deadman/config.yaml
dms logs --config /data/config.yaml
dms cron --config /data/config.yaml

The serve command also supports:

• -h, --host <host> - Override the host from config
• -p, --port <port> - Override the port from config
• --with-cron - Enable embedded cron job (overrides config setting)
• --watch - Watch config file for changes and reload automatically

dms serve --host 127.0.0.1 --port 8080
dms serve --config /data/config.yaml --host 0.0.0.0 --port 3000
dms serve --with-cron  # Enable embedded cron job
dms serve --watch      # Watch config file for changes

Config File Watching

When using the --watch flag, the server will automatically reload the configuration when the config file changes:

dms serve --watch

Features:

• Automatic reload: Config changes are detected and applied without restarting the server
• Debounced updates: Rapid file changes are debounced to prevent excessive reloads
• Cron service restart: Embedded cron service is restarted with new config
• Error handling: Invalid config changes are logged but don't crash the server
• Visual feedback: Clear status messages show when config is being reloaded

Example output:

Starting Dead Man Notifier server...
Config Watch: enabled
Watching config file: /path/to/config.yaml

🔄 Config file changed, reloading...
✅ Config reloaded successfully
🔄 Restarting embedded cron service...
✅ Embedded cron service restarted
✅ Server reloaded successfully

Embedded Cron Service

The server can run with an embedded cron service that automatically sends status emails at the configured schedule. This can be enabled in two ways:

1. Via config file - Set with_cron: true in the server section
2. Via command line - Use the --with-cron flag

When enabled, the server will:

• Start the REST API server
• Automatically run cron jobs at the configured schedule
• Send email reports with service status
• Handle graceful shutdown of both services

Docker

Building the Image

Build the Docker image:

docker build -t deadmannotifier .

Or use the provided Makefile:

make docker-build

Running with Docker

Image is available at: ghcr.io/coralbits/deadmannotifier:latest

Run the container with volume mounts for configuration and data persistence:

docker run -d \
  --name deadman-notifier \
  -p 3000:3000 \
  -v $(pwd)/data:/app/data \
  ghcr.io/coralbits/deadmannotifier:latest

Or use the Makefile:

make docker-run

Docker Compose

For easier management, use Docker Compose. You can use the provided docker-compose.yml file as an example to start the service.

Start with Docker Compose:

docker-compose up -d

Stop the services:

docker-compose down

Using Pre-built Images

You can also use pre-built images from GitHub Container Registry:

version: "3.8"

services:
  deadman-notifier:
    image: ghcr.io/your-username/deadmannotifier:latest
    container_name: deadman-notifier
    ports:
      - "3000:3000"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
      - ./data:/app/data
    environment:
      - NODE_ENV=production
    restart: unless-stopped

Docker Management Commands

The Makefile provides convenient Docker management commands:

make docker-build          # Build the image
make docker-run            # Run the container
make docker-run-interactive # Run interactively
make docker-stop           # Stop the container
make docker-start          # Start the container
make docker-remove         # Remove the container
make docker-logs           # Show container logs
make docker-shell          # Open shell in container
make docker-clean          # Stop and remove container
make docker-clean-all      # Remove container and image
make docker-list           # List service status

Testing

Run tests:

npm test
npm run test:unit
npm run test:integration

Configuration

See config.yaml for configuration options. The file includes:

• Server settings: host, port, embedded cron option, and external URL
• Database settings: SQLite database path
• Email SMTP settings: SMTP server configuration for notifications
• Cron schedule: When to send periodic reports
• Service definitions: UUIDs and names for monitored services

Example configuration:

server:
  host: "0.0.0.0"
  port: 3000
  with_cron: false # Enable embedded cron service
  external_url: "https://deadman.example.com" # Optional external URL for service pings

database:
  path: "deadman.db"

email:
  from: "alerts@example.com"
  to: "admin@example.com"
  subject: "Service Status Report"
  smtp:
    host: "smtp.example.com"
    port: 587
    user: "alerts@example.com"
    password: "your-password"

cron: "0 */6 * * *" # Every 6 hours

services:
  - id: "550e8400-e29b-41d4-a716-446655440000"
    name: "Database Backup"
  - id: "550e8400-e29b-41d4-a716-446655440001"
    name: "File Sync Service"

Usage

Services ping the notifier with:

• PUT /[service-id]/ok - Service is healthy
• PUT /[service-id]/nok - Service has issues

The cron job sends periodic email reports and marks services as "nak" (not acknowledged) if they haven't pinged within the cron period.