Configuration Guide

Learn how to configure Sky Puppy for your specific health monitoring needs. This guide covers all configuration options, environment variables, and best practices.

Basic Configuration

Sky Puppy uses a simple JSON configuration system that can be customized through environment variables or configuration files.

{
  "skypuppy": {
    "version": "1.3.8",
    "log": {
      "enable": true,
      "colors": true,
      "level": "info"
    }
  },
  "checkers": {
    "request": {},
    "sky-puppy-checker-template": {
      "foo": "bar",
      "code_messages": {
        "200": "Override me plz",
        "500": "Yikes its down"
      }
    }
  },
  "alerters": {
    "discord_alert": {
      "uri": "https://discord.com/api/webhooks/YOUR_WEBHOOK_URL",
      "json": true,
      "method": "POST",
      "body": {
        "embeds": [{
          "title": "🚨 {{service_name}} is {{alert_type}}!",
          "description": "Service was healthy for {{last_healthy_total_duration}} seconds",
          "color": 14828098,
          "timestamp": "{{timestamp}}"
        }],
        "username": "Sky Puppy"
      }
    }
  },
  "services": {
    "my-website": {
      "interval": 30,
      "start_delay": 0,
      "expected_response_time": 1000,
      "checker": {
        "name": "request",
        "settings": {
          "uri": "https://httpbin.org/status/200",
          "timeout": 10
        },
        "code_messages": {
          "200": "Service is healthy",
          "500": "Service is down"
        }
      },
      "alerts": [
        {
          "type": "down",
          "alerter": "discord_alert"
        },
        {
          "type": "unhealthy_response_time",
          "for": 2,
          "alerter": "discord_alert"
        },
        {
          "type": "unhealthy_status",
          "for": 1,
          "alerter": "discord_alert"
        },
        {
          "type": "healthy",
          "alerter": "discord_alert"
        }
      ]
    }
  }
}

Environment Variables

Sky Puppy supports configuration through environment variables for easy deployment and containerization.

Variable	Default	Description
`SKY_PUPPY_PORT`	8069	Port to run the server on
`SKY_PUPPY_IP`	0.0.0.0	Host to bind the server to
`SKY_PUPPY_CONFIG_PATH`	./	Path to configuration directory

Service Configuration

Configure individual services with specific check intervals, timeouts, and alerting rules.

Basic Service Configuration

{
  "services": {
    "web-frontend": {
      "interval": 30,
      "checker": {
        "name": "request",
        "settings": {
          "uri": "https://myapp.com/health",
          "timeout": 10,
          "method": "GET"
        }
      },
      "alerts": [
        {
          "type": "down",
          "alerter": "your_defined_alerter"
        }
      ]
    }
  }
}

Service Configuration Options

Option	Type	Default	Description
`interval`	number	5	Check interval in seconds
`start_delay`	number	0	Initial delay before first check
`expected_status`	number	200	Expected HTTP status code
`expected_response_time`	number	timeout	Expected response time in milliseconds

Checker Configuration

Configure individual health checkers with specific settings and thresholds.

Global Checker Configuration

Define global settings for checkers that can be used across multiple services:

{
  "checkers": {
    "request": {
      "timeout": 60,
      "method": "GET"
    },
    "sky-puppy-checker-template": {
      "foo": "bar",
      "code_messages": {
        "200": "Override me plz",
        "500": "Yikes its down"
      }
    }
  }
}

Service-Level Checker Configuration

Configure checkers with service-specific settings:

{
  "services": {
    "api-health": {
      "interval": 30,
      "checker": {
        "name": "request",
        "settings": {
          "uri": "https://api.example.com/health",
          "method": "GET",
          "timeout": 10,
          "headers": {
            "Authorization": "Bearer your-token"
          }
        },
        "code_messages": {
          "200": "API is healthy",
          "500": "API is down",
          "503": "API is temporarily unavailable"
        }
      },
      "alerts": [
        {
          "type": "down",
          "alerter": "your_defined_alerter"
        }
      ]
    }
  }
}

Checker Configuration Options

Option	Type	Default	Description
`name`	string	required	Name of the checker to use
`settings`	object	{}	Checker-specific settings
`code_messages`	object	{}	Custom messages for different status codes

Alerting Configuration

Set up alerting rules and notification channels for health check failures.

Basic Alerting Setup

{
  "alerters": {
    "discord_critical": {
      "uri": "https://discord.com/api/webhooks/YOUR_WEBHOOK_URL",
      "json": true,
      "method": "POST",
      "timeout": 60,
      "body": {
        "embeds": [{
          "title": "🚨 {{service_name}} is {{alert_type}}!",
          "description": "Service was healthy for {{last_healthy_total_duration}} seconds",
          "color": 14828098,
          "timestamp": "{{timestamp}}"
        }],
        "username": "Sky Puppy"
      }
    }
  },
  
  "services": {
    "my-website": {
      "interval": 30,
      "checker": {
        "name": "request",
        "settings": {
          "uri": "https://myapp.com/health",
          "timeout": 10
        }
      },
      "alerts": [
        {
          "type": "down",
          "alerter": "discord_critical",
          "for": 2
        },
        {
          "type": "unhealthy_response_time",
          "for": 3,
          "alerter": "discord_critical"
        },
        {
          "type": "unhealthy_status",
          "for": 1,
          "alerter": "discord_critical"
        },
        {
          "type": "unhealthy",
          "for": 1,
          "alerter": "discord_critical"
        },
        {
          "type": "healthy",
          "alerter": "discord_critical"
        }
      ]
    }
  }
}

Alert Types

Type	Description	When Triggered
`down`	Service is completely unavailable	Connection timeout, network error, or status code -1
`unhealthy`	Service is responding but with issues	Status code 0 (general unhealthy state)
`unhealthy_status`	Service returned unexpected status code	HTTP status code other than expected (default: 200)
`unhealthy_response_time`	Service is responding too slowly	Response time exceeds expected_response_time
`healthy`	Service has recovered	Service returns to healthy state after being unhealthy

Alert Configuration Options

Option	Type	Default	Description
`type`	string	required	Alert type: down, unhealthy, unhealthy_status, unhealthy_response_time, healthy
`alerter`	string	required	Name of the alerter to use
`for`	number	1	Number of consecutive failures before alerting
`overrides`	object	{}	Override alerter settings for this specific alert

Logging Configuration

Configure logging levels and formats for monitoring and debugging.

{
  "skypuppy": {
    "log": {
      "enable": true,
      "colors": true,
      "level": "info"  // debug, info, warn, error
    }
  }
}

Log Levels

Level	Description
`debug`	Detailed debug information
`info`	General information messages
`warn`	Warning messages
`error`	Error messages only

Security Configuration

Configure security settings for production deployments.

Security Best Practices:

Bind to localhost only in production: SKY_PUPPY_IP=127.0.0.1
Use environment variables for sensitive data
Run behind a reverse proxy with authentication
Keep Sky Puppy updated to the latest version

Performance Tuning

Optimize Sky Puppy performance for high-traffic environments.

{
  "services": {
    "high-frequency-service": {
      "interval": 5,  // Check every 5 seconds
      "checker": {
        "name": "request",
        "settings": {
          "uri": "https://api.example.com/health",
          "timeout": 5,  // Short timeout for fast checks
          "method": "GET"
        }
      }
    },
    
    "low-frequency-service": {
      "interval": 300,  // Check every 5 minutes
      "checker": {
        "name": "request",
        "settings": {
          "uri": "https://slow-api.example.com/health",
          "timeout": 30,  // Longer timeout for slow services
          "method": "GET"
        }
      }
    }
  },
  
  "skypuppy": {
    "log": {
      "level": "warn"  // Reduce logging overhead
    }
  }
}

Performance Tips

Optimize intervals - Use longer intervals for stable services, shorter for critical ones
Set appropriate timeouts - Match timeout to expected response time
Reduce logging - Use higher log levels in production
Monitor resource usage - Watch CPU and memory consumption
Use efficient checkers - Custom checkers can be optimized for specific services

Need Help? Join our Discussions or report issues on GitHub.