-
Notifications
You must be signed in to change notification settings - Fork 0
Getting Started Script
The install.sh script is the fastest way to get Piro running. It handles dependency checks, clones the repository, generates a secure configuration, and starts the stack — all in one command.
- Git — to clone the repository
- Docker 24+ — on Linux, the script can install it automatically if missing
- Docker Compose v2 — included with Docker Desktop; install separately on Linux servers
- Repository access — the repository must be accessible via your configured Git credentials (SSH key or GitHub token)
The script operates in three modes selected with --mode.
Installs and starts the complete Piro platform: database, API, and frontend.
bash install.sh --mode apiWhat it does:
- Checks that Git, Docker, and Docker Compose v2 are installed
- Clones the repository into
~/.piro(or--dirif specified) - Prompts for your public URL, then generates a
.envfile with random secrets - Runs
docker compose up -dfor thedb,api, andfrontendservices - Prints the setup URL to complete first-time configuration
Interactive prompt:
Public URL of your status page [http://localhost:3000]:
Enter the public URL where Piro will be accessible (e.g. https://status.example.com). Press Enter to use http://localhost:3000 for local testing.
Starts a Piro worker connected to an existing API. Does not require cloning the repository — pulls the Docker image directly from GHCR.
bash install.sh --mode worker \
--api-url https://api.example.com \
--token <worker-token> \
--region eu-westRequired options:
| Option | Description |
|---|---|
--api-url |
Base URL of your Piro API |
--token |
Worker token from Configuration → Workers → Register Worker |
Optional options:
| Option | Default | Description |
|---|---|---|
--region |
default |
Region label attached to all check results from this worker |
Pulls the latest source and rebuilds the stack in place.
bash install.sh --mode updateRuns git pull on the installation directory, then docker compose up -d --build. Data volumes are preserved.
| Option | Applies to | Default | Description |
|---|---|---|---|
--mode |
all | (required) |
api, worker, or update
|
--api-url |
worker |
(required) | URL of the Piro API |
--token |
worker |
(required) | Worker authentication token |
--region |
worker |
default |
Region label for this worker |
--dir |
api, update
|
~/.piro |
Directory where Piro is installed |
On first run, --mode api creates ~/.piro/.env with the following variables:
# Database
POSTGRES_PASSWORD=<random>
# Authentication — do not share this value
JWT_SECRET=<random>
# Public URL of the frontend
ORIGIN=http://localhost:3000
# Worker token — set after first login under Configuration → Workers
WORKER_TOKEN=
# Email alerts (optional)
# EMAIL_HOST=smtp.example.com
# EMAIL_PORT=587
# EMAIL_USERNAME=noreply@example.com
# EMAIL_PASSWORD=
# EMAIL_FROM=Piro <noreply@example.com>POSTGRES_PASSWORD and JWT_SECRET are generated randomly on every fresh install. Never share JWT_SECRET — it signs all authentication tokens.
The worker is not started automatically because it requires a token that only exists after you complete the setup wizard.
Once you have a token:
- Edit
~/.piro/.envand setWORKER_TOKEN=<your-token> - Start the worker:
docker compose --profile worker -f ~/.piro/docker-compose.yml up -d workerbash install.sh --mode updateOr manually:
git -C ~/.piro pull
docker compose -f ~/.piro/docker-compose.yml up -d --buildMigrations run automatically on API startup. No manual steps required.
# Stop and remove containers
docker compose -f ~/.piro/docker-compose.yml down
# Remove installation directory
rm -rf ~/.piro
# Remove data volumes (WARNING: deletes all data)
docker volume rm piro_postgres_data piro_api_uploadsYou can override the default installation directory with the PIRO_DIR environment variable instead of passing --dir every time:
PIRO_DIR=/opt/piro bash install.sh --mode api