Ciao is an open source HTTP monitoring application written in Ruby that checks the status of URL endpoints and sends notifications when status changes occur. The project is maintained by brotandgames and is designed to be lightweight and easy to deploy without requiring external dependencies like databases or caches. The application serves both public and private monitoring environments and is available at https://www.brotandgames.com/ciao/.
The core functionality of ciao involves periodically checking HTTP and HTTPS endpoints for specific status codes or TCP stack errors. Users define check intervals using standard Cron syntax, supporting expressions like every minute, every 15 minutes, or predefined schedules such as hourly and daily. The application tracks status changes over time and includes a feature to monitor TLS certificate expiration, alerting users when certificates will expire within 30 days. This certificate monitoring capability was added in version 1.9.0.
Ciao provides multiple interfaces for users to interact with the monitoring system. A web UI allows users to manage and view checks through a browser, while a RESTful JSON API enables programmatic access. The API supports standard operations including retrieving all checks or specific checks, creating new checks, updating existing checks, and deleting checks through GET, POST, PATCH, PUT, and DELETE endpoints at the /checks.json path.
Notification capabilities are central to ciao's design. When status changes occur, the application can send notifications via email through SMTP providers like Gmail, Sendgrid, and MailChimp, or through webhooks to services like Rocket.Chat and Slack. These notification features are optional and configurable based on user needs. Additionally, ciao exposes a Prometheus metrics endpoint at /metrics for integration with monitoring tools like Grafana.
Configuration is handled entirely through environment variables following the twelve-factor app methodology, making deployment flexible across different platforms. Users can configure the time zone, enable HTTP Basic authentication for the application, set up SMTP for email notifications, configure webhooks, and adjust log levels. The application stores state in an internal SQLite database located at db/sqlite/production.sqlite3, allowing for straightforward backup and restore operations.
Deployment options are extensive. Ciao provides official Docker images under brotandgames/ciao and supports deployment via Docker Compose, Kubernetes with Helm charts, kubectl manifests, and Dokku. The project includes comprehensive documentation for each deployment method. A Terraform provider is also available, maintained separately by autonubil, enabling infrastructure-as-code deployments.
The repository shows help wanted and dependencies as the most active issue labels.
The project follows semantic versioning and is released under the MIT License. The application is designed with security in mind, recommending that users enable HTTP Basic authentication and TLS certificates when serving ciao publicly.
