From 83a4df17d12ef1d73819108b5357fb5c31d2fff0 Mon Sep 17 00:00:00 2001 From: James Brooks Date: Fri, 24 Jul 2026 18:43:39 +0100 Subject: [PATCH] docs: correct and expand v3.x feature documentation Reconcile the v3.x docs with cachet/core: Corrections - components: fix status count (six, not five) and add Under Maintenance (6) - beacon: telemetry is enabled by default (opt out via CACHET_BEACON=false) - cachet: drop the stale "metrics not supported" warning - dashboard: user management is supported; link to the Users guide New/expanded coverage - add an Environment variables reference page - components: group visibility, collapse behaviour, and ordering strategies - incidents: stickied/pinned incidents - schedules: affected components and subscriber notifications - metrics: "show when empty" and reordering - cachet: language/localization, recent incidents only, dynamic favicon - api-keys: enumerate the resource abilities - api filtering: includes and metadata filtering --- api-reference/filtering.mdx | 22 +++++++++ docs.json | 3 +- v3.x/configuration/api-keys.mdx | 24 +++++++++- v3.x/configuration/beacon.mdx | 9 ++-- v3.x/configuration/cachet.mdx | 26 ++++++++--- v3.x/configuration/environment.mdx | 71 ++++++++++++++++++++++++++++++ v3.x/guide/components.mdx | 41 ++++++++++++++++- v3.x/guide/dashboard.mdx | 5 ++- v3.x/guide/incidents.mdx | 3 +- v3.x/guide/metrics.mdx | 8 +++- v3.x/guide/schedules.mdx | 4 +- 11 files changed, 197 insertions(+), 19 deletions(-) create mode 100644 v3.x/configuration/environment.mdx diff --git a/api-reference/filtering.mdx b/api-reference/filtering.mdx index 328382b..9deb86a 100644 --- a/api-reference/filtering.mdx +++ b/api-reference/filtering.mdx @@ -15,6 +15,28 @@ GET /api/incidents?filter[status]=1 Each endpoint may support different fields for filtering. Check the documentation for the specific endpoint you are working with. +## Including related resources + +Many endpoints can embed related resources in the response using the `include` parameter. Pass a comma-separated list +of the relationships you want to include: + +```http +GET /api/incidents?include=components,updates +``` + + + Each endpoint supports a different set of includes. Check the documentation for the specific endpoint you are + working with. + + +## Filtering by metadata + +Resources that support metadata can be filtered by their metadata keys using the `filter[meta][key]` syntax: + +```http +GET /api/incidents?filter[meta][region]=us-east-1 +``` + ## Sorting You can sort the results of an endpoint by passing the `sort` parameter. The `sort` parameter should be a comma-separated list of fields to sort by. You can also specify the sort order by appending `asc` or `desc` to the field name. diff --git a/docs.json b/docs.json index 8d15f7d..c27b313 100644 --- a/docs.json +++ b/docs.json @@ -46,6 +46,7 @@ "group": "Configuration", "pages": [ "v3.x/configuration/cachet", + "v3.x/configuration/environment", "v3.x/configuration/customization", "v3.x/configuration/theme", "v3.x/configuration/beacon", @@ -223,4 +224,4 @@ "vscode" ] } -} \ No newline at end of file +} diff --git a/v3.x/configuration/api-keys.mdx b/v3.x/configuration/api-keys.mdx index cd95648..ccd1591 100644 --- a/v3.x/configuration/api-keys.mdx +++ b/v3.x/configuration/api-keys.mdx @@ -33,6 +33,28 @@ To create an API key, follow these steps: +## Permissions + +Each API key is granted a set of abilities. Leaving the permissions empty when creating a key grants full access. +Otherwise, you can grant the `manage` and/or `delete` ability for each resource type: + +| Resource | Abilities | +| --- | --- | +| Components | `manage`, `delete` | +| Component groups | `manage`, `delete` | +| Incidents | `manage`, `delete` | +| Incident updates | `manage`, `delete` | +| Incident templates | `manage`, `delete` | +| Metrics | `manage`, `delete` | +| Metric points | `manage`, `delete` | +| Schedules | `manage`, `delete` | +| Schedule updates | `manage`, `delete` | +| Subscribers | `manage`, `delete` | + +The `manage` ability allows creating and updating the resource, while `delete` allows deleting it. Read-only endpoints +are available to any valid API key and, depending on your [API settings](/v3.x/configuration/cachet#api-access), may be +public. + ## Revoking tokens If you no longer need an API key, you can revoke it. To revoke an API key, click the "Revoke" button next to the key. @@ -40,4 +62,4 @@ If you no longer need an API key, you can revoke it. To revoke an API key, click Revoking an API key is irreversible. Once you revoke a key, you can no longer use it to authenticate requests to the Cachet API. - \ No newline at end of file + diff --git a/v3.x/configuration/beacon.mdx b/v3.x/configuration/beacon.mdx index 4877893..b1a736c 100644 --- a/v3.x/configuration/beacon.mdx +++ b/v3.x/configuration/beacon.mdx @@ -9,14 +9,15 @@ This data helps us understand how you use Cachet and how we can improve it. ## Configuration -By default, Cachet's beacon is turned off. You can opt in by setting the `CACHET_BEACON` environment variable to `true`. +Cachet's beacon is **enabled by default**. If you'd prefer not to send any usage data, you can opt out by setting the +`CACHET_BEACON` environment variable to `false`. ```ini .env -CACHET_BEACON=true +CACHET_BEACON=false ``` - If you're limiting outbound requests on your server and you'd like to opt into the beacon, you'll need to allow outbound requests to `https://cachethq.io`. + If you're limiting outbound requests on your server and you'd like to keep the beacon enabled, you'll need to allow outbound requests to `https://cachethq.io`. ### Configuring the scheduler @@ -40,4 +41,4 @@ The beacon collects the following data: - **Cachet Version**: The version of Cachet you're running. - **Docker**: Whether you're running Cachet in a Docker container. - **Database**: The type of database you're using. -- **Usage Data**: How you're using Cachet, such as the number of incidents, components, subscribers, etc. \ No newline at end of file +- **Usage Data**: How you're using Cachet, such as the number of incidents, components, subscribers, etc. diff --git a/v3.x/configuration/cachet.mdx b/v3.x/configuration/cachet.mdx index d18c988..bc6702e 100644 --- a/v3.x/configuration/cachet.mdx +++ b/v3.x/configuration/cachet.mdx @@ -26,6 +26,14 @@ information about your organization, services, or status page. The "Timezone" setting allows you to set the timezone for your status page. Cachet uses it to display the correct time for incidents and scheduled maintenance. The status page will always display timestamps in the user's local time. +## Language + +Cachet can display your status page in a number of languages. The "Language" selector, along with the +[Timezone](#timezone) settings, can be found on the "Manage Localization" page under the "Settings" navigation group. + +Cachet currently ships with the following locales: Deutsch (DE), Deutsch (AT), Deutsch (CH), English, English (UK), +Spanish (ES), 한국어, Nederlands, Filipino, Português (BR), 简体中文, and 繁體中文. + ## Incident days This setting allows you to specify the number of days to display incidents on your status page. Cachet pushes incidents @@ -90,12 +98,13 @@ We’d really appreciate it if you could leave this enabled to help spread the w ### Display graphs -Enable the "Display Graphs" setting to display graphs for metrics, such as uptime and response time, on your status -page. +Enable the "Display Graphs" setting to display [metric](/v3.x/guide/metrics) graphs, such as uptime and response time, +on your status page. This setting is enabled by default. - - Metrics are not fully supported in Cachet v3.x. This setting will have no effect until metrics are implemented. - +### Recent incidents only + +Enable the "Recent Incidents Only" setting to show only recent incidents on your status page. When enabled, you can +set the number of days to include, and Cachet hides any incidents older than that window. ### Show timezone @@ -106,6 +115,11 @@ When enabled, the "Show Timezone" setting displays your status page's timezone i Enable the "Only Show Disrupted Days" setting to show only the days with incidents on your status page. By default, the status page displays all days. +### Dynamic favicon + +When the "Dynamic Favicon" setting is enabled, your status page's favicon reflects the current system status, so a +browser tab shows at a glance whether everything is operational or there's an ongoing issue. + ### Show dashboard link -The "Show Dashboard Link" setting controls the "Dashboard" link in the header of your status page. When enabled, the status page displays a link to the Cachet dashboard. \ No newline at end of file +The "Show Dashboard Link" setting controls the "Dashboard" link in the header of your status page. When enabled, the status page displays a link to the Cachet dashboard. diff --git a/v3.x/configuration/environment.mdx b/v3.x/configuration/environment.mdx new file mode 100644 index 0000000..cb01279 --- /dev/null +++ b/v3.x/configuration/environment.mdx @@ -0,0 +1,71 @@ +--- +title: 'Environment variables' +description: 'Configure Cachet using environment variables.' +icon: 'sliders' +--- + +Cachet reads a number of settings from your environment, defined in your `.env` file (or your server's environment). +These sit alongside the dashboard [settings](/v3.x/configuration/cachet) and generally control how Cachet is installed +and served, rather than the content of your status page. + + + Every variable has a sensible default, so you only need to set the ones you want to change. + + +## Application + +| Variable | Default | Description | +| --- | --- | --- | +| `CACHET_PATH` | `/` | The URI path Cachet is served from. | +| `CACHET_DOMAIN` | _(none)_ | The domain Cachet is served from. Leave unset to serve from the application's default domain. | +| `CACHET_TITLE` | `"${APP_NAME} - Status"` | The title of your status page. | +| `CACHET_TRUSTED_PROXIES` | _(empty)_ | Comma-separated list of trusted proxy IPs. See [Theme](/v3.x/configuration/theme) for details. | +| `CACHET_DOCKER` | `false` | Whether Cachet is running inside a Docker container. Set automatically by the official Docker image. | +| `CACHET_DEMO_MODE` | `false` | Runs Cachet in [demo](/v3.x/demo) mode, adjusting some defaults for a demo environment. | + +## API & MCP + +| Variable | Default | Description | +| --- | --- | --- | +| `CACHET_API_RATE_LIMIT` | `300` | Requests per minute allowed against the [API](/api-reference/rate-limiting). | +| `CACHET_MCP_RATE_LIMIT` | `300` | Requests per minute allowed against the [MCP server](/v3.x/guide/mcp). | + +## Telemetry & performance + +| Variable | Default | Description | +| --- | --- | --- | +| `CACHET_BEACON` | `true` | Whether Cachet sends anonymous [telemetry](/v3.x/configuration/beacon). Set to `false` to opt out. | +| `CACHET_SETTINGS_CACHE` | `true` | Cache Cachet's settings instead of reading them from the database on every request. | + +## Maintenance & retention + +| Variable | Default | Description | +| --- | --- | --- | +| `CACHET_PRUNE_CHECKS_AFTER_DAYS` | `30` | Number of days to keep component check results before they are pruned. | + +## Webhooks + +| Variable | Default | Description | +| --- | --- | --- | +| `CACHET_WEBHOOK_QUEUE_CONNECTION` | _(app default)_ | The queue connection used to dispatch [webhooks](/v3.x/guide/webhooks). | +| `CACHET_WEBHOOK_QUEUE_NAME` | _(app default)_ | The queue name used to dispatch webhooks. | + +## Blog feed + +| Variable | Default | Description | +| --- | --- | --- | +| `CACHET_FEED_URI` | `https://blog.cachethq.io/rss` | The RSS feed used to display blog posts on your status page. | +| `CACHET_FEED_CACHE` | `3600` | How long, in seconds, to cache the blog feed. | + +## Package integration + +When running Cachet as a package inside an existing Laravel application, the following variables control how it +integrates with your host application: + +| Variable | Default | Description | +| --- | --- | --- | +| `CACHET_GUARD` | _(default guard)_ | The authentication guard Cachet uses. | +| `CACHET_USER_MODEL` | `App\Models\User` | The user model Cachet authenticates against. | +| `CACHET_USER_MIGRATIONS` | `true` | Whether Cachet loads the default user migrations. | +| `CACHET_RUN_MIGRATIONS` | `true` | Whether Cachet loads its migrations. Disable if your application manages them itself. | +| `CACHET_REGISTER_SCHEDULES` | `true` | Whether Cachet registers its scheduled tasks. Disable if your application schedules them itself. | diff --git a/v3.x/guide/components.mdx b/v3.x/guide/components.mdx index 72807c7..cf3ad59 100644 --- a/v3.x/guide/components.mdx +++ b/v3.x/guide/components.mdx @@ -31,13 +31,14 @@ Cachet also provides a simple way of updating your component statuses directly f ### Component statuses -Components can have one of five statuses: +Components can have one of six statuses: - **Operational**: The component is working as expected. - **Performance Issues**: The component is experiencing performance issues. - **Partial Outage**: The component is experiencing partial outage. - **Major Outage**: The component is experiencing a major outage. - **Unknown**: The component status is unknown. +- **Under Maintenance**: The component is undergoing maintenance. [Schedules](/v3.x/guide/schedules) can set this status automatically. ## Component groups @@ -47,6 +48,29 @@ To help organize your components, you can group them together into component gro Cachet will automatically group any ungrouped components together. Cachet displays ungrouped components beneath any component groups on your status page. +A component group has the following properties: + +- **Name**: The name of the group. +- **Visibility**: Whether the group is visible to users, guests, or always hidden. +- **Collapsed**: How the group behaves on the status page (see [Collapse behavior](#collapse-behavior)). +- **Order by**: How components within the group are ordered (see [Ordering strategies](#ordering-strategies)). + +### Group visibility + +Like other resources, each component group has a visibility setting that controls who can see it: + +- **Authenticated**: Only visible to authenticated dashboard users. +- **Guest**: Visible to everyone, including guests. +- **Hidden**: Never displayed on the status page. + +### Collapse behavior + +You can control whether a group appears expanded or collapsed on your status page. Each group can be set to one of: + +- **Expanded**: The group is always expanded, showing all of its components. +- **Collapsed**: The group is always collapsed. +- **Collapsed unless a component is in an incident**: The group stays collapsed until one of its components is not operational, at which point Cachet expands it automatically. This keeps large status pages tidy while still drawing attention to problems. + ## Reordering components You may reorder components via the dashboard by dragging and dropping them into the desired order. To do this, @@ -59,4 +83,17 @@ You can also reorder components when editing a component group. The order will r Reorder Components Reorder Components - \ No newline at end of file + + +### Ordering strategies + +By default, components follow the manual drag-and-drop order described above. Component groups can also order their +components automatically. When editing a group, set "Order by" to one of: + +- **Manual**: Respect the manual drag-and-drop order. +- **Name**: Order alphabetically by name. +- **Status**: Order by component status. +- **Last updated**: Order by when the component was last updated. +- **ID**: Order by the component's ID. + +For every strategy except manual, you can also choose the direction (ascending or descending). diff --git a/v3.x/guide/dashboard.mdx b/v3.x/guide/dashboard.mdx index 5402b01..7fa0c47 100644 --- a/v3.x/guide/dashboard.mdx +++ b/v3.x/guide/dashboard.mdx @@ -10,7 +10,8 @@ including managing incidents, components, and subscribers. ## User management -Cachet currently does not support user management from the dashboard. +You can manage the users who have access to your Cachet dashboard directly from the dashboard. See the +[Users](/v3.x/guide/users) guide for more information. ## Markdown @@ -22,4 +23,4 @@ using a tool by the same name. # Incident Title This is my **first incident**. It's _really_ [serious](https://www.youtube.com/shorts/1LOQOKXTDLY). -``` \ No newline at end of file +``` diff --git a/v3.x/guide/incidents.mdx b/v3.x/guide/incidents.mdx index e36e78f..ed23010 100644 --- a/v3.x/guide/incidents.mdx +++ b/v3.x/guide/incidents.mdx @@ -12,6 +12,7 @@ the dashboard. Incidents consist of: - **Message**: A detailed description of the incident. - **Occurred At**: The time the incident occurred. This can be left empty if the incident happened at the time of reporting. - **Visibility**: Whether the incident should be visible to users, guests or always be hidden. +- **Stickied**: Whether the incident is pinned to the top of your status page. Stickied incidents remain prominently displayed until you unsticky them. The Cachet dashboard provides a simple interface to manage incidents. You can quickly record a new incident by clicking the "New Incident" link in the top navigation bar. You can also view and manage existing incidents by clicking the "Incidents" @@ -67,4 +68,4 @@ templates with two templating languages: Incident templates are particularly powerful when combined with the API as they allow you to create a new incident by passing -a template and variables. Cachet creates the incident from the template, filled in with the variables you provide. \ No newline at end of file +a template and variables. Cachet creates the incident from the template, filled in with the variables you provide. diff --git a/v3.x/guide/metrics.mdx b/v3.x/guide/metrics.mdx index 5f800fa..d5ac6e9 100644 --- a/v3.x/guide/metrics.mdx +++ b/v3.x/guide/metrics.mdx @@ -19,6 +19,7 @@ A metric consists of: - **Places**: The number of decimal places to display. - **Metric Type**: The type of calculation to perform on the metric, e.g. sum or average. - **Threshold**: The threshold determines when a new point should be created or the last point updated. +- **Show when empty**: Whether Cachet displays the metric on your status page when it has no points. When disabled, the metric is hidden until it has data. - **Visible**: Whether the metric is visible to users, guests or always hidden. ## Metric points @@ -28,4 +29,9 @@ A metric is made up of multiple points that you add over time. Each point consis - **Value**: The value of the metric at this point in time. - **Timestamp**: The time the metric was recorded. -For performance, if you create a metric point within the threshold of an existing point, Cachet updates the existing point with the new value. \ No newline at end of file +For performance, if you create a metric point within the threshold of an existing point, Cachet updates the existing point with the new value. + +## Reordering metrics + +You can reorder metrics to control the order they appear in on your status page, in the same way you +[reorder components](/v3.x/guide/components#reordering-components). diff --git a/v3.x/guide/schedules.mdx b/v3.x/guide/schedules.mdx index 75efafb..b21dff8 100644 --- a/v3.x/guide/schedules.mdx +++ b/v3.x/guide/schedules.mdx @@ -13,6 +13,8 @@ A scheduled maintenance event consists of: - **Message**: A detailed description of the maintenance. - **Scheduled At**: The date and time when the maintenance will start. - **Completed At**: The date and time when the maintenance was completed. +- **Components**: The [components](/v3.x/guide/components) affected by the maintenance, along with the status each should display while it's underway (typically **Under Maintenance**). +- **Notify subscribers**: Whether to notify your [subscribers](/v3.x/guide/subscribers) about this maintenance, for example when it's rescheduled or completed. ### Schedule statuses @@ -36,4 +38,4 @@ To update a schedule, head to the "Schedules" panel in the dashboard and click " You cannot add updates to "Completed" schedules. - \ No newline at end of file +