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

Edit .env:

# Required
POSTGRES_PASSWORD=a_strong_random_password
JWT_SECRET=a_long_random_string_at_least_32_chars

# Optional — defaults shown
ACCESS_TOKEN_EXPIRY_MINUTES=60
REFRESH_TOKEN_EXPIRY_DAYS=30

All other configuration (site name, email, SMTP, OIDC) is done through the admin panel after setup. No additional env vars are required.

---

3. Start the stack

docker compose -f docker-compose.local.yml up -d --build

This builds images from source and starts:

Service	Port	Description
proxy	80	Nginx reverse proxy + admin SPA (static)
web	internal	Next.js public status page
api	internal	Piro API (ASP.NET Core)
db	internal	PostgreSQL 17

The API applies database migrations automatically on startup.

---

4. First-time setup

Open http://localhost/admin/ in your browser. If the database is empty you will be automatically redirected to the setup wizard.

After completing setup, sign in at http://localhost/admin/auth/sign-in.

The public status page is available at http://localhost/.

---

Updating

docker compose -f docker-compose.local.yml pull
docker compose -f docker-compose.local.yml up -d --build

Migrations run automatically on each API startup.