Alert System Troubleshooting Guide

This guide helps diagnose and fix common issues with the DitDashDot alert system.

Error: "Error saving alert settings"

This error typically occurs when there are database connectivity issues or table schema problems.

Troubleshooting Steps

Check if containers are running:
```
docker compose ps
```
All services (dashboard, api, db) should be "Up"
Check API server logs:
```
docker compose logs api
```
Look for database connection errors or SQL errors
Check database logs:
```
docker compose logs db
```
Look for PostgreSQL startup issues

Restart the containers:

docker compose down
docker compose up -d

Check database connection:

docker compose exec db psql -U ditdashdot -d ditdashdot -c "SELECT version();"

Manual Database Setup

If automatic table creation fails, you can manually create the tables:

Connect to database:

docker compose exec db psql -U ditdashdot -d ditdashdot

Create alert_settings table:

CREATE TABLE IF NOT EXISTS alert_settings (
    id SERIAL PRIMARY KEY,
    enabled BOOLEAN DEFAULT true,
    webhook_url TEXT,
    webhook_enabled BOOLEAN DEFAULT false,
    down_threshold_minutes INTEGER DEFAULT 5,
    paused_until TIMESTAMP NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Create alert_history table:

CREATE TABLE IF NOT EXISTS alert_history (
    id SERIAL PRIMARY KEY,
    service_id INTEGER,
    service_name TEXT NOT NULL,
    service_ip TEXT,
    service_port INTEGER,
    alert_type VARCHAR(50) NOT NULL,
    message TEXT,
    webhook_sent BOOLEAN DEFAULT false,
    webhook_response TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Add alert columns to services table:

ALTER TABLE services ADD COLUMN IF NOT EXISTS alert_enabled BOOLEAN DEFAULT true;
ALTER TABLE services ADD COLUMN IF NOT EXISTS down_threshold_minutes INTEGER NULL;

Exit database:
```
\q
```

Test API Endpoints

Use the included test script to verify API functionality:

# Make sure containers are running first
docker compose up -d

# Wait for services to start
sleep 10

# Run the test script
node test-alerts.js

Common Error Messages

"Database error: relation 'alert_settings' does not exist"

The alert_settings table hasn't been created
Follow manual database setup steps above
Check if migrations ran properly: docker compose logs db | grep alert

"Error connecting to the database"

Database container might not be running
Check container status: docker compose ps
Restart containers: docker compose restart

"Internal server error"

Check API server logs: docker compose logs api
Verify all environment variables are set correctly
Ensure database is accessible from API container

"Network error" or "ERR_NETWORK"

API server might not be running on port 3001
Check if port is bound: docker compose ps
Verify nginx configuration is routing /api requests correctly

Browser Developer Tools

Open browser developer tools (F12)
Go to Network tab
Try saving alert settings
Check the API request:
- URL should be /api/alert-settings
- Method should be PUT
- Status should be 200 for success
- Response should contain the saved settings

Reset Alert System

If all else fails, you can reset the alert system:

Stop containers:
```
docker compose down
```
Remove database volume (WARNING: This deletes all data!):
```
docker volume rm ditdashdot_postgres_data
```
Start fresh:
```
docker compose up -d
```
Wait for initialization:
```
docker compose logs -f db
```
Wait for "database system is ready to accept connections"
Reconfigure dashboard:
- Go to http://localhost/config
- Set up your services again
- Configure alerts in the Alerts tab

Getting Help

If problems persist:

Collect the following information:
- Output of docker compose ps
- Output of docker compose logs api
- Output of docker compose logs db
- Browser console errors (F12 → Console)
- Network errors (F12 → Network)
Check the GitHub issues page for similar problems
Create a new issue with all the collected information