Open-source status page, incident response and uptime monitoring
TypeScript alertingincident-managementmcpmcp-servermonitoringmonitoring-as-codeobservabilityon-callopen-sourcesrestatus-pagestatuspagesynthetic-monitoringterraformtinybirdtursouptimeuptime-checkeruptime-monitor
improve setup docs for dashboard (#2150)
Colin Ozannef5e0ff5cb7d4
diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MDindex fb531bd01..1f0b9e606 100644--- a/CONTRIBUTING.MD+++ b/CONTRIBUTING.MD@@ -23,6 +23,8 @@ If you have ideas for new features or improvements, you can submit a GitHub issu## Submitting Changes+For local dashboard setup, see [apps/dashboard/README.md](apps/dashboard/README.md).+To contribute code changes, follow these steps:1. Fork the repository and create a new branch for your changes.diff --git a/README.md b/README.mdindex 4f4984d56..05984d7a1 100644--- a/README.md+++ b/README.md@@ -95,51 +95,34 @@ ghcr.io/openstatushq/openstatus-checker:latest#### Requirements- [Node.js](https://nodejs.org/en/) >= 20.0.0-- [pnpm](https://pnpm.io/) >= 8.6.2+- [pnpm](https://pnpm.io/) >= 10.26.0- [Bun](https://bun.sh/)-- [Turso CLI](https://docs.turso.tech/quickstart)+- [Turso CLI](https://docs.turso.tech/quickstart).-#### Setup+#### Dashboard-1. Clone the repository+See [apps/dashboard/README.md](apps/dashboard/README.md) for full steps (env, db, login, troubleshooting).-```sh-git clone https://github.com/openstatushq/openstatus.git-```--2. Install dependencies--```sh-pnpm install-```+#### Status page-3. Initialize the development environment+1. Install dependencies-Launch the database in one terminal:+`pnpm install`-```sh-turso dev --db-file openstatus-dev.db-```+2. Run the server-In another terminal, run the following command:+`pnpm -w dev:status-page`.-```sh-pnpm dx-```+#### Web (marketing site)-4. Launch whatever app you wish to:+1. Install dependencies-```sh-pnpm dev:web-pnpm dev:status-page-pnpm dev:dashboard-```+`pnpm install`-The above commands will automatically run the libSQL client on `8080` so you might want to kill the turso command from step 3.+2. Run the server-5. See the results:+`pnpm -w dev:web`.-- open [http://localhost:3000](http://localhost:3000) (default port)## Tech Stackdiff --git a/apps/dashboard/.env.example b/apps/dashboard/.env.exampleindex acb817ac4..ba4253dd5 100644--- a/apps/dashboard/.env.example+++ b/apps/dashboard/.env.example@@ -50,7 +50,7 @@ GCP_CLIENT_EMAIL=GCP_PRIVATE_KEY=CRON_SECRET=-VERCEL_URL=https://app.openstatus.dev+VERCEL_URL=PLAYGROUND_UNKEY_API_KEY=diff --git a/apps/dashboard/README.md b/apps/dashboard/README.mdnew file mode 100644index 000000000..e67fd6a63--- /dev/null+++ b/apps/dashboard/README.md@@ -0,0 +1,91 @@+# OpenStatus Dashboard++## Manual Setup++### Requirements++- [Node.js](https://nodejs.org/en/) >= 20.0.0 — runtime+- [pnpm](https://pnpm.io/) >= 8 — monorepo package manager (see root `package.json` for pinned version)+- [Bun](https://bun.sh/) — runs the db env/migrate/seed scripts in `packages/db`+- [Turso CLI](https://docs.turso.tech/quickstart) — starts the local libSQL server via `pnpm --filter '@openstatus/db' dev`++### Environment++Two `.env` files are involved:++- `apps/dashboard/.env` — copy manually now (this step)+- `packages/db/.env` — copied automatically by `pnpm dx` in step 3 below++```sh+cp apps/dashboard/.env.example apps/dashboard/.env+```++The defaults in `.env.example` are dummy values that work for local dev — no real API keys needed.+Fill them in before deployment to enable optional functionality (Resend for real magic-link emails, Stripe, Tinybird analytics, Sentry, GitHub/Google OAuth, etc.).+Email/Magic Link login is only available in dev.++### Startup++1. Install dependencies++```sh+pnpm install+```++2. Start the libSQL server (keep this terminal running)++```sh+pnpm --filter '@openstatus/db' dev+```++3. In a second terminal, set up the dev database++```sh+pnpm -w dx+```++This chains three turbo tasks (`env → migrate → seed`):++- `env` copies `packages/db/.env.example` → `packages/db/.env`+- `migrate` runs Drizzle migrations against the libSQL server+- `seed` inserts a default workspace, user (`[email protected]`), monitors, and a status page++4. Stop the terminal from step 2++`pnpm -w dev:dashboard` starts its own libSQL on port `8080` — leaving the step-2 server running causes a port conflict.++5. Start the dashboard from the repo root++```sh+pnpm -w dev:dashboard+```++Turbo runs the dashboard (`apps/dashboard`) and `@openstatus/db` together.++6. Open [http://localhost:3000](http://localhost:3000)++## Logging in++The dashboard uses NextAuth with GitHub, Google, and — in dev mode — a Resend magic-link provider.++In `NODE_ENV=development` or `SELF_HOST=true`, `src/lib/auth/providers.ts` configures the Resend provider with `apiKey: undefined` and overrides `sendVerificationRequest` to **print the magic link to the dashboard's terminal stdout** instead of sending an email. No OAuth credentials required.++To log in:++1. Open [http://localhost:3000/login](http://localhost:3000/login)+2. Enter `[email protected]` (the seeded user, bound to workspace 1) in the magic-link form+3. Watch the dashboard terminal — the magic link is logged there. Open it in your browser.++## Troubleshooting++- **Port 8080 already in use** — a leftover libSQL server from step 2. Kill that terminal and re-run `pnpm -w dev:dashboard`.+- **Magic link doesn't arrive** — it isn't emailed in dev. Look in the dashboard terminal stdout for `>>> Magic Link: ...`.+- **Reset the dev DB** — stop the libSQL server, delete `openstatus-dev.db` at the repo root, restart libSQL, re-run `pnpm -w dx`.++## Related services (optional for dashboard development)++The dashboard's tRPC API runs on its own Next.js edge routes, so basic CRUD works without the other apps. You may also want to run:++- `apps/server` (Hono) — for API-key features and operations that go through the public HTTP API+- `apps/checker` (Go) — actually executes scheduled monitor checks; without it, monitors are listed but never probed+- Tinybird — uptime / latency time-series graphs; without it, those charts stay empty