# Status page

Farsight publishes a status page at `/status`. It lists only the monitors you mark **public**, under their **public name** and **public group**, so hosts, addresses and error messages never show. It is server-made HTML, cached for 30 seconds, small (about 15 KB on the wire for 19 services), and it works from a small phone to a wide screen. One small script of its own makes it quicker and friendlier (below); without it, everything still works.

## What it shows

- The overall state, and (optionally) a summary: uptime across the page, incidents, the longest outage and the typical response time for the chosen range.
- **Range tabs**: 24 hours (one bar per hour), 7 days (one bar per 6 hours), 30 days and 90 days (one bar per day), 12 months (one bar per month). Each is its own address (`/status?range=7d`); you choose which tabs exist and which one opens first.
- Each **section** (public group) with its services. A service shows its state, a small response-time line, its bars and its uptime for the range. Hover or tap a bar for its period, uptime and any downtime.
- **Down now**, when a service is down, and the last 14 days of incidents, with a link to the full history.

Bars: green; amber when the period had any confirmed outage or fell below 99.9% (months: below 99.9% only, so one short blip leaves a month green; the label still says how long it was down); red below 99%. Before a service was first watched, its bars are a thin line and the label under them says "Since 1 Oct" instead of pretending the time was up or down. A figure never reads 100% for a period that had downtime.

## The script

The page carries one script, from Farsight itself (nothing inline, nothing from elsewhere; the page's security policy allows nothing more). It does three things:

- **Instant range tabs.** Once the page has loaded, it fetches the other ranges in the background (a few KB each), so a tab switches at once, in place. Back and the address still work, so a range can be shared.
- **The visitor's own time.** Every time on the page (updated at, incidents, the hours of the 24 h and 7 d bars) shows in the visitor's time zone, in the same format. Day and month bars are counted midnight to midnight in the page's time zone (the one in Settings), so they stay as they are, and the footer says so: "Times in your time zone (UTC-07:00), days in UTC+05:30". Visitors in the page's own zone see no change.
- **Refreshing in place.** When the page comes back to the front after a minute or more (a phone unlocked, an installed app reopened), it refreshes without a reload; with **Refresh** on, it does so every minute too. Sections a visitor opened stay open. Offline, the page keeps what it showed and says "offline" beside its "Updated" time, which names the day when it is not today. When you save a new look, open pages reload whole.

Without scripts, tabs are plain links, times are in the page's time zone, and **Refresh** reloads the page.

## On a phone's home screen

Visitors can add the page to a phone's home screen (Share, Add to Home Screen on an iPhone; Install app on Android), and it opens as an app of its own, with no browser bars. Its icon is Farsight's, or one made from your logo: the dashboard draws it when you upload a logo (your logo on the page's background, square, as phones want), and **Make it again** draws it anew after you change the theme. The name under the icon is the title, or a shorter **Name** you set under **Page**, **Home screen** (phones show about 12 characters). A phone keeps the icon and name it was given when the page was added: remove and add the page again to see a change.

## More pages

- `/status/<name>`: one service: its bars, a response-time chart, the uptime of each of the last 12 months and its incidents. Service names on the main page link here; `<name>` comes from the public name.
- `/status/history`: every incident of a public service, newest first, three months a page with an **Older** link.

## Editing it

**Status page** in the dashboard has three tabs over one set of changes, and one **Save**:

- **Look**: the layout (three picture cards), colours, typeface, bars, the time ranges and what to show.
- **Services**: what the public sees, by section. Type a public name in place (empty means the monitor's own name), switch a service off, move it up, down or to another section from its menu, and move or rename whole sections. **Add services** picks more from a searchable list of the rest, into their own groups or into one section.
- **Page**: on or off, title, intro, logo, website, header links, the home screen (its icon and name) and custom domains.

Beside the tabs (or behind **Preview** on a narrower screen) is a live preview: the real page with your changes, drawn by the same code as the public page, as a desktop or a phone, light or dark, at any range. Nothing is public until you save, and the page shows it within 30 seconds. The logo is the one exception: it is saved as soon as you choose it.

Unsaved changes are kept on this device until you save or discard them, so going Back, reloading or closing the app never loses them (the editor says so when they come back); leaving by a link reminds you they are not live yet. Signing out clears them. A save sends only what you changed, so it never undoes a change made elsewhere in the meantime, and it is all or nothing.

Agents and scripts get the same preview from `POST /api/v1/status-page/preview` (see the API reference).

## How it looks

Under **Status page** in the dashboard (or `PUT /api/v1/status-page`):

| Setting | Choices |
|---|---|
| Layout | **Horizon** (a summary panel, sections that fold away while all is fine), **Classic** (a large state line, a card per section), **Ledger** (dense rows, one per service, everything on about one screen) |
| Theme | follow the visitor, light, dark |
| Accent | any colour (links, tabs, response lines) |
| Status colours | green and red, or blue and orange (easier for colour-blind readers) |
| Typeface | Geist, IBM Plex Sans, or the visitor's system font |
| Bars | the worst moment of each period, or how much of each period was down; rounded, square or slim |
| Ranges | which of 24 h, 7 d, 30 d, 90 d, 12 mo, and the default |
| Show | response times, uptime figures, the summary (turning a figure off removes it everywhere, the JSON too) |
| Sections | fold the ones that are all fine (they open by themselves when a service has trouble) |
| Refresh | refresh every minute, for a screen on a wall |
| Logo | a PNG, JPEG, WebP or SVG of 256 KB at most, also the page's icon in browser tabs and, made into a square, on the home screen (`PUT /api/v1/status-page/logo`, then `PUT /api/v1/status-page/icon`) |
| Home screen name | the name under the icon, 30 characters at most; empty means the title |
| Website and links | your site (the logo links there and the footer names it) and up to 3 links in the header |

The title and the intro line sit at the top; the footer names your site and says the page is powered by Farsight.

## Your own domain

Add the name (for example `status.example.com`) under **Page**, **Custom domains** and save. Farsight shows the one DNS record to add: an `A` record (and `AAAA` when the server has IPv6) pointing at the server, with the proxy off. When the domain's DNS is at Cloudflare, **Open Cloudflare DNS** opens the zone's records page. Farsight then watches the domain's own nameservers (every 30 seconds until it is live, at once after a save), so a record added a minute ago is seen at once; when it points here, Farsight gets a certificate for it from Let's Encrypt by itself, in about a minute, with nothing to restart. Each domain shows where it stands: waiting for DNS, points elsewhere, proxied by Cloudflare (switch the orange cloud to DNS only), getting a certificate, live, or certificate failed (with Let's Encrypt's reason; after three failures in a row Farsight waits an hour, then longer each time up to a day, under Let's Encrypt's limits). A live domain whose renewal fails keeps its certificate and says so. Requests for the domain get the status page at `/`, and the page installed from there opens at `/`. Removing the domain stops its certificate's renewals.

Farsight can only do this when it serves HTTPS itself (the default). Behind your own proxy, the proxy needs the certificate, and the editor says so.

## JSON

The same data is public at `/api/public/status?range=90d` for embedding elsewhere (bars, uptime, typical response, page links; never monitor ids or hosts).