mirror of
https://github.com/TwiN/gatus.git
synced 2026-05-01 14:15:43 +00:00
85 lines
4.6 KiB
Markdown
85 lines
4.6 KiB
Markdown
# 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.
|