Skip to content

Open-source status page, incident response and uptime monitoring

improve setup docs for dashboard (#2150)

Colin Ozannef5e0ff5cb7d4
diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD
index 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.md
index 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 Stack
diff --git a/apps/dashboard/.env.example b/apps/dashboard/.env.example
index 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.md
new file mode 100644
index 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