phenx/piwitests-server repository overview

⁠Piwi Dashboard

Your Playwright results, kept and explained. CI throws away every report it makes. Piwi keeps them — then groups the failures by root cause, scores the flaky tests, and finds the locator you should have used. Self-hosted, MIT, zero telemetry.

📖 Full documentation⁠ · 🎮 Live demo⁠ · 💬 GitHub⁠

⁠Quick start

# Linux / macOS
mkdir -p .data && chown -R 1001:1001 .data # the container runs as non-root UID 1001
docker run -d --name piwi-dashboard -p 3000:3000 -v $(pwd)/.data:/app/.data phenx/piwitests-server:latest

# Windows (PowerShell)
docker run -d --name piwi-dashboard -p 3000:3000 -v ${PWD}/.data:/app/.data phenx/piwitests-server:latest

Open http://localhost:3000. The SQLite database and file storage are created automatically inside .data/.

Then point the Playwright reporter⁠ at it — one npm install and four lines in playwright.config.ts, covered in the getting started guide⁠.

⁠Image details

/app/.data holds piwi.db (the SQLite database, skipped when PIWI_DATABASE_URL is set) and storage/ (HTML reports and trace files, skipped when S3 is configured). Mount it, or the container loses everything on restart.

⁠Tags

The same multi-arch image is mirrored to the GitHub Container Registry as ghcr.io/piwitests/platform, which additionally carries an edge tag built from main (no release testing — not for production).

Read Upgrading⁠ before bumping a tag: migrations run automatically on startup and are forward-only, so rolling back means restoring a backup.

⁠Configuration

Piwi runs with zero configuration — set variables only to change a default. The full list, with defaults and which ones the Settings UI can override, is the configuration reference⁠; the configuration generator⁠ builds a ready-to-paste .env, Compose, Kubernetes or systemd block in your browser.

The three worth knowing before you expose the container to a network:

Generate a value for the latter two with node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))".

Beyond those: PIWI_DATABASE_URL switches to PostgreSQL, PIWI_STORAGE_TYPE=s3 plus the PIWI_S3_* variables switch artifact storage to any S3-compatible service, and PIWI_RETENTION_DAYS turns on nightly pruning of old runs.

⁠Docker Compose

services:
  piwi-dashboard:
    image: phenx/piwitests-server:latest
    ports:
      - "3000:3000"
    volumes:
      - ./.data:/app/.data
    environment:
      PIWI_SECRET_KEY: "replace-with-a-32-byte-hex-string"
      PIWI_AUTH_ENABLED: "true"
      PIWI_AUTH_SECRET: "replace-with-a-different-32-byte-hex-string"
    restart: unless-stopped

PostgreSQL, S3 and MinIO variants are in the deployment guide⁠, alongside Kubernetes manifests, reverse-proxy configuration and backups.

⁠Troubleshooting

Volume permission error (Linux hosts only) — mkdir -p .data && chown -R 1001:1001 .data, then recreate the container.

Container exits immediately — docker logs piwi-dashboard.

Data not persisted after restart — the -v volume mount is missing.

SQLite locked / concurrent write errors — SQLite allows one writer at a time; set PIWI_DATABASE_URL to switch to PostgreSQL.

More, including port conflicts and reverse-proxy issues: deployment troubleshooting⁠.

⁠License

MIT — source code on GitHub⁠