Development Setup

Development Setup

How to run Piro locally for development.

Prerequisites

• .NET 9 SDK
• Node.js 20+ and npm
• (Optional) Docker & Docker Compose — for the database or full-stack mode

---

Option A — Local (no Docker)

This is the fastest way to get a hot-reloading dev environment.

1. Start the API

cd src/Piro.Api
dotnet run
# Listening on http://localhost:5117

SQLite is used by default — the database file piro.db is created automatically on first run. No database setup required.

2. Start the frontend

cd frontend
cp .env.example .env   # PIRO_API_URL defaults to http://localhost:5117
npm install
npm run dev
# http://localhost:5173

Open http://localhost:5173 — you'll be redirected to /setup to create the owner account and configure the instance.

---

Option B — Docker Compose

Runs the full stack (API + frontend + PostgreSQL) with pre-built images.

docker compose up --build

Service	URL
Frontend	http://localhost:3000
API	http://localhost:8080
Postgres	localhost:5432

Navigate to http://localhost:3000/setup on first startup.

---

First-run flow

1. /setup — set instance name, create the owner account
2. /auth/sign-in — sign in
3. /admin/services → + Add service
4. Click the service → + Add check (HTTP type, point at a real URL)
5. Click Run now on the check row to trigger it immediately
6. / — public status page shows service health
7. /admin/incidents → + New incident
8. /admin/maintenances → + Schedule maintenance

---

Running tests

cd tests/Piro.UnitTests
dotnet test

Unit tests cover status propagation, cycle detection, and DAG cascade logic.

---

Key environment variables

Variable	Default	Description
Database__ConnectionString	Data Source=piro.db	SQLite (dev) or Postgres (prod) connection string
Auth__JwtSecret	(auto-generated)	JWT signing secret — set explicitly in production
PIRO_API_URL	http://localhost:5117	Frontend → API base URL
ASPNETCORE_ENVIRONMENT	Development	Set to Production for prod builds