Getting Started Docker

Getting Started with Docker

This guide gets Piro running locally using Docker Compose in under 5 minutes.

---

Prerequisites

• Docker 24+
• Docker Compose v2

---

1. Clone the repository

git clone https://github.com/Heva-Co/piro.git
cd piro

---

2. Configure environment

Copy the example env file and fill in the required values:

cp .env.example .env

At minimum, set:

# Required
DATABASE__CONNECTIONSTRING=Host=db;Port=5432;Database=piro;Username=piro;Password=changeme
AUTH__JWTSECRET=replace-with-a-long-random-secret-at-least-32-chars

# Optional — public URL shown in OpenAPI spec
PUBLIC_URL=https://status.example.com

See Environment Variables for the full reference.

---

3. Start the stack

docker compose up -d

This starts:

Service	Port	Description
api	5117	Piro API (ASP.NET Core)
frontend	5173	Admin & public status page (SvelteKit)
db	5432	PostgreSQL 16

The API applies database migrations automatically on startup.

---

4. First-time setup

Open http://localhost:5173/setup and create your owner account.

After that, sign in at http://localhost:5173/auth/sign-in.

---

5. (Optional) Run a remote worker

To monitor from a second location, register a worker in the admin UI under Configuration → Workers → Register Worker, then run:

docker run --rm \
  -e PIRO_API_URL=http://localhost:5117 \
  -e PIRO_WORKER_TOKEN=<token-from-registration> \
  -e PIRO_WORKER_REGION=eu-west \
  ghcr.io/heva-co/piro-worker:latest

---

6. (Optional) Enable the API as a local worker

If you don't need separate worker processes, set PIRO_API_WORKER=true on the API container. This makes the API itself participate in multi-region check execution:

# docker-compose.yml
services:
  api:
    environment:
      PIRO_API_WORKER: "true"
      PIRO_WORKER_REGION: "primary"

---

Updating

docker compose pull
docker compose up -d

Migrations run automatically on each startup.