Open-source status page, incident response and uptime monitoring
TypeScript alertingincident-managementmcpmcp-servermonitoringmonitoring-as-codeobservabilityon-callopen-sourcesrestatus-pagestatuspagesynthetic-monitoringterraformtinybirdtursouptimeuptime-checkeruptime-monitor
chore: docs theme-store with feedback (#2282)
Maximilian Kaske17217011c136
diff --git a/apps/web/.env.example b/apps/web/.env.exampleindex 9c7b7dd2d..67626ddf1 100644--- a/apps/web/.env.example+++ b/apps/web/.env.example@@ -69,7 +69,7 @@ AUTH_GOOGLE_SECRET=PAGERDUTY_APP_ID=-SLACK_SUPPORT_WEBHOOK_URL=+SLACK_FEEDBACK_WEBHOOK_URL=WORKSPACES_LOOKBACK_30=WORKSPACES_HIDE_URL=diff --git a/apps/web/src/app/(docs)/docs/[[...slug]]/page.tsx b/apps/web/src/app/(docs)/docs/[[...slug]]/page.tsxindex 287e5664b..fc9dc97ae 100644--- a/apps/web/src/app/(docs)/docs/[[...slug]]/page.tsx+++ b/apps/web/src/app/(docs)/docs/[[...slug]]/page.tsx@@ -14,6 +14,7 @@ import {gitLastModified,validateDocsNav,} from "@/content/docs";+import { DocsFeedback } from "@/content/docs-feedback";import { DocsSubNav } from "@/content/docs-sub-nav";import { TableOfContents } from "@/content/docs-toc";import {@@ -241,8 +242,9 @@ export default async function DocsPage({</div><aside className="hidden w-56 shrink-0 xl:block">- <div className="sticky top-4 max-h-[calc(100vh-2rem)] overflow-y-auto">+ <div className="sticky top-4 max-h-[calc(100vh-2rem)] space-y-2 overflow-y-auto"><TableOfContents items={toc} />+ <DocsFeedback /></div></aside></div>diff --git a/apps/web/src/app/api/feedback/docs/route.ts b/apps/web/src/app/api/feedback/docs/route.tsnew file mode 100644index 000000000..1c0b313ab--- /dev/null+++ b/apps/web/src/app/api/feedback/docs/route.ts@@ -0,0 +1,144 @@+import { redis } from "@openstatus/upstash";+import { z } from "zod";++import { getClientIP, ratelimit } from "@/lib/ratelimit";+import { hashIP } from "@/lib/utils";++export const runtime = "edge";++const RATE_LIMIT_WINDOW = 60; // seconds+const MAX_REQUESTS_PER_WINDOW = 5;++// a docs pathname (from usePathname); constrained so it can't craft arbitrary Redis keys+const path = z+ .string()+ .min(1)+ .max(512)+ .regex(/^\/[a-zA-Z0-9/_-]*$/);++// rating-only (thumbs) and message-only (feedback) are separate actions+const schema = z.discriminatedUnion("kind", [+ z.object({+ kind: z.literal("rating"),+ path,+ rating: z.enum(["up", "down"]),+ }),+ z.object({+ kind: z.literal("message"),+ path,+ message: z.string().trim().min(1).max(2000),+ }),+]);++type Rating = "up" | "down";++const countsKey = (path: string) => `docs-feedback:counts:${path}`;+const voterKey = (path: string, id: string) =>+ `docs-feedback:voter:${path}:${id}`;+// bound voter-key storage; after expiry a re-vote may double count (acceptable)+const VOTER_TTL = 60 * 60 * 24 * 180; // 180 days, seconds++// Slack mrkdwn treats & < > as control chars; escape user text before interpolation+const escapeSlack = (text: string) =>+ text.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">");++export async function POST(request: Request) {+ let data: z.infer<typeof schema>;+ try {+ data = schema.parse(await request.json());+ } catch {+ return Response.json({ error: "Invalid request" }, { status: 400 });+ }++ const clientIP = getClientIP(request.headers);+ if (!clientIP) {+ return Response.json(+ { error: "Unable to determine client IP" },+ { status: 400 },+ );+ }+ const voterId = await hashIP(clientIP);++ const limit = await ratelimit(`docs-feedback:${voterId}`, {+ window: RATE_LIMIT_WINDOW,+ limit: MAX_REQUESTS_PER_WINDOW,+ });+ if (!limit.success) {+ return Response.json(+ { error: "Too many requests" },+ {+ status: 429,+ headers: {+ "Retry-After": Math.ceil(+ (limit.reset - Date.now()) / 1000,+ ).toString(),+ },+ },+ );+ }++ // dev: skip external writes (Redis tally + Slack) so local runs don't pollute prod+ if (process.env.NODE_ENV === "development") {+ console.log("docs feedback", data);+ return Response.json({ success: true });+ }++ // historical tally of up/down votes per path; best-effort, never blocks Slack+ if (data.kind === "rating") {+ try {+ // one vote per (path, voter); SET ... GET atomically claims the new vote and+ // returns the prior one in a single round-trip, so concurrent requests can't+ // both read a stale value and double-count. The delta derives from that prior+ // value server-side, so a tampered count needs both a real prior vote and the IP.+ const previous = (await redis.set(+ voterKey(data.path, voterId),+ data.rating,+ { ex: VOTER_TTL, get: true },+ )) as Rating | null;+ if (previous !== data.rating) {+ await redis.hincrby(countsKey(data.path), data.rating, 1);+ if (previous) {+ await redis.hincrby(countsKey(data.path), previous, -1);+ }+ }+ } catch (err) {+ console.error("Docs feedback: failed to record vote", err);+ }+ }++ const webhook = process.env.SLACK_FEEDBACK_WEBHOOK_URL;+ if (!webhook) {+ console.error("Docs feedback: SLACK_FEEDBACK_WEBHOOK_URL not configured.");+ return Response.json({ success: true });+ }++ const lines = [+ data.kind === "rating"+ ? `*Docs feedback:* ${data.rating === "up" ? "π helpful" : "π not helpful"}`+ : "*Docs feedback:* π¬ comment",+ `*Path:* ${escapeSlack(data.path)}`,+ ];+ if (data.kind === "message") {+ lines.push(+ "--------------------------------",+ `*Message:* ${escapeSlack(data.message)}`,+ );+ }++ try {+ const response = await fetch(webhook, {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({ text: lines.join("\n") }),+ });+ if (!response.ok) {+ console.error(+ `Docs feedback: Slack webhook responded ${response.status}`,+ );+ }+ } catch (err) {+ console.error("Docs feedback: failed to post to Slack", err);+ }++ return Response.json({ success: true });+}diff --git a/apps/web/src/content/docs-feedback.tsx b/apps/web/src/content/docs-feedback.tsxnew file mode 100644index 000000000..c57310f87--- /dev/null+++ b/apps/web/src/content/docs-feedback.tsx@@ -0,0 +1,210 @@+"use client";++import { zodResolver } from "@hookform/resolvers/zod";+import {+ Form,+ FormControl,+ FormField,+ FormItem,+ FormLabel,+} from "@openstatus/ui/components/ui/form";+import { Kbd } from "@openstatus/ui/components/ui/kbd";+import {+ Popover,+ PopoverContent,+ PopoverTrigger,+} from "@openstatus/ui/components/ui/popover";+import { Textarea } from "@openstatus/ui/components/ui/textarea";+import { Inbox, LoaderCircle } from "lucide-react";+import { usePathname } from "next/navigation";+import { useEffect, useState } from "react";+import { useForm } from "react-hook-form";+import { z } from "zod";++import { toastAction } from "@/lib/toast";++type Rating = "up" | "down";++const ratingKey = (path: string) => `docs-rating:${path}`;++const schema = z.object({+ message: z.string().trim().min(1).max(2000),+});++type FeedbackBody =+ | { kind: "rating"; path: string; rating: Rating; previous?: Rating }+ | { kind: "message"; path: string; message: string };++// never throws; returns whether the server accepted the submission+async function postFeedback(body: FeedbackBody): Promise<boolean> {+ try {+ const res = await fetch("/api/feedback/docs", {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify(body),+ });+ return res.ok;+ } catch {+ return false;+ }+}++function DocsFeedbackBar({ path }: { path: string }) {+ const [rating, setRating] = useState<Rating>();+ const [open, setOpen] = useState(false);+ const [sent, setSent] = useState(false);+ const form = useForm<z.infer<typeof schema>>({+ resolver: zodResolver(schema),+ defaultValues: { message: "" },+ });++ // rehydrate a prior vote so the chosen arrow stays highlighted across loads+ useEffect(() => {+ const stored = window.localStorage.getItem(ratingKey(path));+ if (stored === "up" || stored === "down") setRating(stored);+ }, [path]);++ // reset the popover contents shortly after it closes (300ms = close anim)+ useEffect(() => {+ if (!open && sent) {+ const t = setTimeout(() => {+ setSent(false);+ form.reset();+ }, 300);+ return () => clearTimeout(t);+ }+ }, [open, sent, form]);++ function rate(value: Rating) {+ // read the prior vote from localStorage (not state) so a click before the+ // hydration effect still reports the correct `previous` to the server+ const stored = window.localStorage.getItem(ratingKey(path));+ const previous = stored === "up" || stored === "down" ? stored : undefined;+ if (previous === value) return;+ setRating(value);+ window.localStorage.setItem(ratingKey(path), value);+ void postFeedback({ kind: "rating", path, rating: value, previous });+ }++ async function onSubmit(values: z.infer<typeof schema>) {+ const ok = await postFeedback({+ kind: "message",+ path,+ message: values.message,+ });+ if (ok) {+ setSent(true);+ } else {+ toastAction("error");+ }+ }++ return (+ <div className="text-sm">+ <p className="text-foreground py-2 font-mono font-medium">+ Was this helpful?+ </p>+ <Popover open={open} onOpenChange={setOpen}>+ <div className="bg-border text-muted-foreground [&>*]:bg-background [&>*]:hover:bg-muted flex items-stretch gap-px border font-mono [&>*]:flex [&>*]:items-center [&>*]:justify-center [&>*]:py-2 [&>*]:transition-colors [&>*]:disabled:pointer-events-none">+ <button+ type="button"+ aria-label="Yes, this page was helpful"+ data-active={rating === "up"}+ onClick={() => rate("up")}+ className="hover:text-success data-[active=true]:bg-muted data-[active=true]:text-success w-10"+ >+ <span className="leading-none" aria-hidden="true">+ β²+ </span>+ </button>+ <button+ type="button"+ aria-label="No, this page was not helpful"+ data-active={rating === "down"}+ onClick={() => rate("down")}+ className="hover:text-destructive data-[active=true]:bg-muted data-[active=true]:text-destructive w-10"+ >+ <span className="leading-none" aria-hidden="true">+ βΌ+ </span>+ </button>+ <PopoverTrigger asChild>+ <button+ type="button"+ data-active={open}+ className="hover:text-foreground data-[active=true]:bg-muted data-[active=true]:text-foreground flex-1"+ >+ Send feedback+ </button>+ </PopoverTrigger>+ </div>+ <PopoverContent+ align="end"+ side="bottom"+ className="w-64 rounded-none p-0"+ >+ {sent ? (+ <div className="flex flex-col items-center justify-center gap-1 p-3">+ <Inbox className="size-4 shrink-0" />+ <p className="text-center text-sm font-medium">+ Thanks for sharing!+ </p>+ <p className="text-muted-foreground text-center text-xs">+ We read every note.+ </p>+ </div>+ ) : (+ <Form {...form}>+ <form className="relative" onSubmit={form.handleSubmit(onSubmit)}>+ <FormField+ control={form.control}+ name="message"+ render={({ field }) => (+ <FormItem>+ <FormLabel className="sr-only">Feedback</FormLabel>+ <FormControl>+ <Textarea+ placeholder="Ideas, corrections, or anything missing..."+ className="field-sizing-fixed h-[110px] resize-none rounded-none p-3"+ rows={4}+ onKeyDown={(e) => {+ if ((e.metaKey || e.ctrlKey) && e.key === "Enter") {+ e.preventDefault();+ void form.handleSubmit(onSubmit)();+ }+ }}+ {...field}+ />+ </FormControl>+ </FormItem>+ )}+ />+ <button+ type="submit"+ className="text-muted-foreground hover:text-foreground absolute right-2 bottom-2 flex items-center font-mono text-sm disabled:opacity-50"+ disabled={form.formState.isSubmitting}+ >+ {form.formState.isSubmitting ? (+ <LoaderCircle className="size-4 animate-spin" />+ ) : (+ <>+ Send+ <Kbd className="ml-1 font-mono">β</Kbd>+ <Kbd className="ml-1 font-mono">β΅</Kbd>+ </>+ )}+ </button>+ </form>+ </Form>+ )}+ </PopoverContent>+ </Popover>+ </div>+ );+}++export function DocsFeedback() {+ const pathname = usePathname();+ // key by path so rating + popover state reset when navigating between docs+ return <DocsFeedbackBar key={pathname} path={pathname} />;+}diff --git a/apps/web/src/content/docs.config.ts b/apps/web/src/content/docs.config.tsindex e32b83f2b..01703c2b3 100644--- a/apps/web/src/content/docs.config.ts+++ b/apps/web/src/content/docs.config.ts@@ -108,6 +108,10 @@ export const docsNav: DocsNavSection[] = [slug: "guides/how-to-configure-status-page",label: "How to Configure Your Status Page",},+ {+ slug: "guides/how-to-create-status-page-theme",+ label: "How to Create Your Own Status Page Theme",+ },{slug: "guides/how-to-import-status-page",label: "How to Import a Status Page from Another Provider",diff --git a/apps/web/src/content/pages/docs/guides/how-to-configure-status-page.mdx b/apps/web/src/content/pages/docs/guides/how-to-configure-status-page.mdxindex e50760c90..e4e1aad28 100644--- a/apps/web/src/content/pages/docs/guides/how-to-configure-status-page.mdx+++ b/apps/web/src/content/pages/docs/guides/how-to-configure-status-page.mdx@@ -84,7 +84,7 @@ You can choose between different themes. The starting set is:- `supabase`- `github-high-contrast`-Visit [themes.openstatus.dev](https://themes.openstatus.dev) to see the list of supported themes. You can also contribute your own.+Visit [themes.openstatus.dev](https://themes.openstatus.dev) to see the list of supported themes. You can also [create and contribute your own](/docs/guides/how-to-create-status-page-theme).If you use AI agents, install the [`openstatus-theme` skill](https://github.com/openstatusHQ/skills/tree/main/skills/openstatus-theme) with `npx skills add openstatushq/skills --skill openstatus-theme` for guided help through palette design, accessibility checks, file scaffolding, and PR submission.diff --git a/apps/web/src/content/pages/docs/guides/how-to-create-status-page-theme.mdx b/apps/web/src/content/pages/docs/guides/how-to-create-status-page-theme.mdxnew file mode 100644index 000000000..c4f22ce8b--- /dev/null+++ b/apps/web/src/content/pages/docs/guides/how-to-create-status-page-theme.mdx@@ -0,0 +1,157 @@+---+category: Guides+title: Create Your Own Status Page Theme+description: "A step-by-step guide to designing, testing, and contributing a community theme for openstatus status pages."+---++++| | |+|---|---|+| **Prerequisites** | a GitHub account, Node.js and pnpm installed, basic familiarity with CSS custom properties |++Community themes let you restyle a status page with your own colors and design β and once merged, everyone can pick your theme from the [theme explorer](/docs/guides/how-to-configure-status-page#2-theme-explorer). This guide walks you through designing a palette, testing it locally, and opening a pull request.++Themes are contributed through GitHub. We keep them in version control so every theme stays reviewable, accessible, and consistent across the platform.++<Aside type="tip">+If you use AI agents, install the [`openstatus-theme` skill](https://github.com/openstatusHQ/skills/tree/main/skills/openstatus-theme) with `npx skills add openstatushq/skills --skill openstatus-theme` for guided help through palette design, accessibility checks, file scaffolding, and PR submission.+</Aside>++## Two ways to build a theme++<Grid cols={2}>+<Card title="Visual builder">+Configure a palette at [themes.openstatus.dev](https://themes.openstatus.dev/?b=true) and copy the generated configuration. Fastest way to get a starting point.+</Card>+<Card title="Local development">+Run the status page app locally and iterate against real, seeded content. Best for fine-tuning and final testing.+</Card>+</Grid>++Most contributors start in the builder, then test locally before submitting.++## 1. Run the project locally++Fork the [openstatus repository](https://github.com/openstatusHQ/openstatus) to your GitHub account, then follow the [Getting Started](https://github.com/openstatusHQ/openstatus?tab=readme-ov-file#getting-started-) steps. From the repository root, start the status page app:++```bash+pnpm dev:status-page+```++Then open one of:++- [localhost:3000](http://localhost:3000) β the theme explorer+- [localhost:3000/status](http://localhost:3000/status) β a status page with seeded entries++A configuration button in the bottom-right corner gives you access to settings, including the community theme switcher.++## 2. Create your theme file++Theme files live in `packages/theme-store/src`. Create a new TypeScript file there (for example `my-theme.ts`). The easiest start is to copy an existing theme such as `github.ts` and edit the values.++## 3. Define your theme++Export a constant that satisfies the `Theme` interface. Each theme has an `id`, a display `name`, an `author`, and `light` / `dark` color maps:++```typescript+import type { Theme } from "./types";++export const MY_THEME = {+ id: "my-theme", // unique, kebab-case+ name: "My Awesome Theme", // display name+ author: {+ name: "@yourusername",+ url: "https://github.com/yourusername", // website or social link+ },+ light: {+ "--background": "oklch(100% 0 0)",+ "--foreground": "oklch(20% 0 0)",+ "--success": "oklch(60.81% 0.1567 142.5)", // operational+ "--destructive": "oklch(58.79% 0.1577 22.18)", // outage+ // ...more variables+ },+ dark: {+ "--background": "oklch(10% 0 0)",+ "--foreground": "oklch(90% 0 0)",+ // ...more variables+ },+} as const satisfies Theme;+```++<Aside type="note">+You don't need to set every variable. Anything you leave out falls back to the default openstatus theme, so you can override only the colors that matter for your design.+</Aside>++### Status colors++These four drive the meaning of a status page, so set them deliberately and make sure they're distinguishable:++| Variable | Meaning |+|---|---|+| `--success` | resolved / operational (green) |+| `--warning` | identified / degraded (yellow) |+| `--info` | monitoring / maintenance (blue) |+| `--destructive` | investigating / outage / error (red) |++The remaining variables follow the [shadcn/ui](https://ui.shadcn.com/) naming convention β `--background`, `--foreground`, `--primary`, `--secondary`, `--accent`, `--muted`, `--border`, `--input`, `--ring`, the `--chart-*` series, and more. The complete list lives in [`packages/theme-store/src/types.ts`](https://github.com/openstatusHQ/openstatus/blob/main/packages/theme-store/src/types.ts) as `THEME_VAR_NAMES`.++<Details summary="What about the --rainbow-* variables?">+The `--rainbow-1` through `--rainbow-17` variables color the per-region series in the public monitor charts. They're optional β if you skip them, the [defaults](https://github.com/openstatusHQ/openstatus/blob/main/apps/status-page/src/app/globals.css) apply.+</Details>++## 4. Register your theme++Add your theme to the `THEMES_LIST` array in `packages/theme-store/src/index.ts`. Keep the list ordered:++```typescript+const THEMES_LIST = [+ OPENSTATUS_THEME,+ OPENSTATUS_ROUNDED_THEME,+ // ...+ MY_THEME,+] satisfies Theme[];+```++Theme IDs are validated at runtime to be unique, so a duplicate `id` will throw β pick something descriptive.++## 5. Test your theme++Before submitting, verify the theme against a real page:++1. Apply it on a status page via the configuration button.+2. Confirm both **light** and **dark** modes look correct.+3. Check contrast with your browser dev tools.+4. Make sure every status indicator (operational, degraded, monitoring, outage) is clearly distinguishable.++<Aside type="tip">+To preview themes outside local development, run `sessionStorage.setItem("community-theme", "true")` in the browser console. A floating button appears that lets you switch between themes and light/dark mode.+</Aside>++## 6. Submit a pull request++Open a pull request against the openstatus repository with your new theme file and the `index.ts` change. We'll review it for design consistency and accessibility.++## Design guidelines++- **Use OKLCH** for better perceptual uniformity β though any valid CSS color is supported.+- **Support both modes.** A theme must define a coherent `light` and `dark` variant.+- **Meet WCAG contrast guidelines.** Test readability in both modes.+- **Keep it cohesive.** All components should feel like one design.+- **No "Christmas tree."** Avoid overly colorful or distracting palettes.++## What you've accomplished++- Designed a light and dark color palette+- Created and registered a theme in the theme store+- Tested it against a real status page in both modes+- Opened a pull request to share it with the community++## What's next++- **[Configure your status page](/docs/guides/how-to-configure-status-page)** β apply themes and other display options.+- **[Building trust with status pages](/docs/concept/best-practices-status-page)** β communicate incidents effectively.++## Questions?++Need help building a theme? [Open an issue](https://github.com/openstatusHQ/openstatus/issues), join our Discord, or reach out to the openstatus community.diff --git a/apps/web/src/env.ts b/apps/web/src/env.tsindex 59374b137..55569d22e 100644--- a/apps/web/src/env.ts+++ b/apps/web/src/env.ts@@ -22,7 +22,7 @@ export const env = createEnv({CLICKHOUSE_USERNAME: z.string(),CLICKHOUSE_PASSWORD: z.string(),PAGERDUTY_APP_ID: z.string().optional(),- SLACK_SUPPORT_WEBHOOK_URL: z.string().optional(),+ SLACK_FEEDBACK_WEBHOOK_URL: z.string().optional(),},client: {NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: z.string(),@@ -54,7 +54,7 @@ export const env = createEnv({CLICKHOUSE_USERNAME: process.env.CLICKHOUSE_USERNAME,CLICKHOUSE_PASSWORD: process.env.CLICKHOUSE_PASSWORD,PAGERDUTY_APP_ID: process.env.PAGERDUTY_APP_ID,- SLACK_SUPPORT_WEBHOOK_URL: process.env.SLACK_SUPPORT_WEBHOOK_URL,+ SLACK_FEEDBACK_WEBHOOK_URL: process.env.SLACK_FEEDBACK_WEBHOOK_URL,},skipValidation: true,});diff --git a/apps/web/src/lib/utils.ts b/apps/web/src/lib/utils.tsindex f833a1e90..c40c3bdb5 100644--- a/apps/web/src/lib/utils.ts+++ b/apps/web/src/lib/utils.ts@@ -92,3 +92,22 @@ export function toCapitalize(inputString: string) {.map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()).join("");}++// pseudonymize a value (e.g. an IP) before it reaches storage: HMAC with a+// server secret so the digest can't be brute-forced back (the IPv4 space is tiny).+export async function hashIP(ip: string): Promise<string> {+ const secret = process.env.FEEDBACK_IP_SALT ?? process.env.CRON_SECRET ?? "";+ const enc = new TextEncoder();+ const key = await crypto.subtle.importKey(+ "raw",+ enc.encode(secret),+ { name: "HMAC", hash: "SHA-256" },+ false,+ ["sign"],+ );+ const sig = await crypto.subtle.sign("HMAC", key, enc.encode(ip));+ return [...new Uint8Array(sig)]+ .map((b) => b.toString(16).padStart(2, "0"))+ .join("")+ .slice(0, 32);+}