Environment Variables

Environment Variables

Piro's required configuration is minimal — only secrets and credentials go in environment variables. Everything else (site name, email, OIDC/SAML, etc.) is configured through the admin panel and stored in the database.

In Docker Compose, set variables under environment: or in a .env file at the same level as docker-compose.yml.

---

docker-compose.yml variables

These are the only variables read by the Compose file itself:

Variable	Required	Default	Description
POSTGRES_PASSWORD	✅	piro	Password for the PostgreSQL piro user
JWT_SECRET	✅	—	Secret used to sign JWT tokens. Must be at least 32 characters
ACCESS_TOKEN_EXPIRY_MINUTES		60	Access token lifetime in minutes
REFRESH_TOKEN_EXPIRY_DAYS		30	Refresh token lifetime in days
PROXY_VERSION		latest	Tag for ghcr.io/heva-co/piro-proxy
WEB_VERSION		latest	Tag for ghcr.io/heva-co/piro-web
API_VERSION		latest	Tag for ghcr.io/heva-co/piro-api

---

Example .env

# Image versions (pin for reproducible deployments)
PROXY_VERSION=v0.2.0
WEB_VERSION=v0.2.0
API_VERSION=v0.2.0

# Required
POSTGRES_PASSWORD=a_strong_random_password
JWT_SECRET=a_long_random_string_at_least_32_chars

# Optional
ACCESS_TOKEN_EXPIRY_MINUTES=60
REFRESH_TOKEN_EXPIRY_DAYS=30

---

Admin panel configuration

The following settings are not env vars — they are configured through the admin panel under Configuration and stored in the database:

Setting	Where
Site name and public URL	Configuration → General
SMTP / email alerts	Configuration → Email
OIDC (OpenID Connect) SSO	Configuration → SSO
SAML SSO	Configuration → SSO
Notification triggers	Configuration → Triggers

This means you can change email or SSO settings at any time without restarting containers.

⚠️ Email is required at first-run, not optional. The Setup Wizard will not let you finish onboarding without a working SMTP (or Resend) configuration — the owner account must verify a 6-digit code sent to their email before setup can complete. This guarantees notification and invitation delivery work from day one. If the code doesn't arrive, check spam, double-check the SMTP host/port, and use "Resend code" — note that changing any email field invalidates the pending code (it's a stateless HMAC-signed code tied to the exact SMTP config).