gatus/AGENTS.md

AGENTS.md

Guidance for AI coding agents working in this repository.

Commands

• make install — Build the gatus binary
• make run — Run in dev mode (uses ./config.yaml)
• make test — Run all Go tests with coverage
• make clean — Remove built binary
• make frontend-install — Install frontend npm dependencies
• make frontend-build — Build the Vue.js frontend (must run after any web/ changes)
• make frontend-dev — Start the Vue dev server

Key Rules

• Vendored dependencies: After adding/updating a Go dependency, run go mod tidy && go mod vendor
• Frontend build artifacts: web/static/ is generated by make frontend-build and embedded into the Go binary at compile time via //go:embed. Never edit files in web/static/ directly
• Config validation order: In config/config.go parseAndValidateConfigBytes, ValidateAlertingConfig must run before ValidateEndpointsConfig because provider default alerts must be parsed before endpoint defaults are set
• Invalid configs panic at startup — validation errors are fatal, not graceful
• Hot-reload: main.go watches the config file and re-runs the full stop → save → load → init → start cycle. New startup logic must account for this

Environment Variables

• GATUS_CONFIG_PATH — Config file path (default: config/config.yaml); can be a directory of YAML files (deep-merged)
• GATUS_LOG_LEVEL — DEBUG, INFO, WARN, ERROR
• ENVIRONMENT=dev — Enables CORS for frontend dev on localhost:8081

Project Structure

• main.go — Entry point; loads config, initializes storage, starts watchdog + API server
• config/ — Central config struct (config.go) and sub-packages per config section (each with ValidateAndSetDefaults())
• alerting/ — Alerting config (config.go), alert types (alert/type.go), and one sub-package per provider under provider/
• api/ — Fiber-based HTTP API routes and SPA serving
• watchdog/ — Monitoring loop; spawns a goroutine per endpoint with semaphore-based concurrency control
• client/ — HTTP/gRPC client used for health checks
• storage/store/ — Storage abstraction with memory/, sql/ (SQLite + PostgreSQL) implementations
• security/ — Authentication (basic + OIDC) and security middleware
• web/app/ — Vue 3 frontend source; builds to web/static/ (embedded into the Go binary)
• vendor/ — Vendored Go dependencies (committed to repo)

Common Changes

Adding an Alerting Provider

Use alerting/provider/slack/ as the reference implementation. Every new provider touches 6 locations:

1. Create provider package — alerting/provider/{name}/{name}.go + {name}_test.go
   • Config struct with Validate() and Merge(*Config) methods
   • AlertProvider struct with DefaultConfig (yaml inline), DefaultAlert *alert.Alert, Overrides []Override
   • Use client.GetHTTPClient(nil) (not http.DefaultClient), always defer response.Body.Close()
2. Register type — Add Type{Name} Type = "{name}" in alerting/alert/type.go
3. Add to config struct — Add field to alerting.Config in alerting/config.go; the YAML tag must exactly match the alert.Type string (reflection-based lookup via GetAlertingProviderByAlertType)
4. Add compile-time checks — Both _ AlertProvider = (*pkg.AlertProvider)(nil) and _ Config[pkg.Config] = (*pkg.Config)(nil) in alerting/provider/provider.go
5. Register in validation — Add the type to the alertTypes slice in config/config.go ValidateAlertingConfig
6. Document — Add to README.md in alphabetical order

Adding a Config Section

1. Create package in config/ with struct + ValidateAndSetDefaults() method
2. Add field to Config struct in config/config.go
3. Add Validate* call in parseAndValidateConfigBytes — respect ordering constraints (see comments in that function)

Frontend

• Vue 3 Composition API (<script setup>) + Tailwind CSS
• Props-based data flow — do not use provide/inject
• All components must include dark: prefixed Tailwind classes for dark mode
• window.config contains server-injected UI settings (Go template placeholders)

API Routes (api/api.go)

• Unprotected routes are registered before ApplySecurityMiddleware
• Protected routes are registered after — placement order matters

Testing

• Config structs should have *_test.go files
• Use t.Parallel() where appropriate
• API tests spin up test servers (see existing *_test.go in api/)

Commits & PRs

When creating a commit or PR as an agent, state that it was made by an agent and include your model name and version.