Skip to content

Development Setup

Jump to bottom
Arael Espinosa edited this page Jul 13, 2026 · 2 revisions

Development Setup

How to run Piro locally for development.

Prerequisites

  • .NET 10 SDK
  • Node.js 20+ and pnpm (never npm or yarn)
  • PostgreSQL (local install, or via Docker)
  • (Optional) Docker & Docker Compose — for the database or full-stack mode

Architecture

Piro has two separate frontend apps, not one:

Component Tech Location Port
API ASP.NET Core 10 src/Piro.Api/ 5117
Worker (optional) ASP.NET Core 10 src/Piro.Worker/ —
Public status page Next.js 16 + React 19 apps/web/ 3000
Admin panel Vite + React (SPA) apps/admin/ 5173

The API runs checks in-process when PIRO_API_WORKER=true (the default in development). The standalone Worker is only needed for multi-region setups.

Running locally

1. Database

Piro requires PostgreSQL — there is no SQLite fallback. The easiest way to get one running locally:

docker run -d --name piro-postgres -e POSTGRES_PASSWORD=piro -e POSTGRES_DB=piro -p 5432:5432 postgres:16

2. API

cd src/Piro.Api
ASPNETCORE_ENVIRONMENT=Development dotnet run
# http://localhost:5117

appsettings.Development.json is loaded automatically. Migrations run on startup — no manual migration step needed.

3. Public status page (Next.js)

cd apps/web
pnpm install
pnpm dev
# http://localhost:3000

4. Admin panel (Vite SPA)

cd apps/admin
pnpm install
pnpm dev
# http://localhost:5173

Open http://localhost:5173 — on first run you'll be redirected to the Setup Wizard to create the owner account and configure the instance (including a required, verified email configuration).

Option B — Docker Compose

Runs the full stack (proxy, web, admin-served-as-static, API, PostgreSQL) with pre-built images.

docker compose up
Service Port Description
proxy (nginx) :80 Reverse proxy in front of web/API
web — Next.js public status page
api — ASP.NET Core API
db 5432 PostgreSQL

Navigate to the proxy URL on first startup — you'll be routed into the setup wizard automatically.

First-run flow

  1. Open the admin panel — you're redirected into the Setup Wizard (General → Account → Email)
  2. Sign in with the owner account you just created
  3. Services → + Add service
  4. Open the service → + Add check (HTTP type, point at a real URL)
  5. Click Run now on the check row to trigger it immediately
  6. Open the public status page — the service's health should now show
  7. Incidents → + New incident (stays private until explicitly published)
  8. Maintenances → + Schedule maintenance

Running tests

dotnet build Piro.slnx
dotnet test

For frontend type-checking, always use tsc -b (project references), not tsc --noEmit — this is what CI runs:

cd apps/web && pnpm exec tsc -b
cd apps/admin && pnpm exec tsc -b

Key environment variables

Variable Default Description
Database__ConnectionString — PostgreSQL connection string, required
Auth__JwtSecret (auto-generated in dev) JWT signing secret — set explicitly in production
PIRO_API_WORKER true in development Whether the API runs checks in-process
INTERNAL_API_URL http://localhost:5117 apps/web → API base URL (server-side)
ASPNETCORE_ENVIRONMENT Development Set to Production for prod builds

See Environment Variables for the full list used in Docker Compose deployments.

Related

Piro Wiki

Home

Concepts

Getting Started

Hosting

Configuration

Alerting

Development

Clone this wiki locally