iron/docs/development.md

Development

This document captures the development workflow, test expectations, and UI quality rules for Iron.

Setup

UV_CACHE_DIR=.uv-cache uv venv .venv
UV_CACHE_DIR=.uv-cache uv pip install --python .venv/bin/python -e '.[dev]'
npm install

Run Locally

npm run build
.venv/bin/python -m uvicorn app.main:app --reload

Open:

http://127.0.0.1:8000/app

Default development credentials:

username: admin
password: changeme-iron

Tests

Full suite:

.venv/bin/python -m pytest

Current expected result:

78 passed

Browser E2E:

.venv/bin/python scripts/ui_playwright_smoke.py

Real deployment acceptance against a live local OpenList + Iron environment:

.venv/bin/python scripts/real_openlist_suite.py

Optional focused scenarios:

• scripts/real_openlist_acceptance.py: baseline upload, reconcile, download, direct WebDAV read
• scripts/real_openlist_chaos_acceptance.py: large file, range reads, forced remote recovery, OpenList flap, recycle-bin restore
• scripts/real_openlist_multi_backend_acceptance.py: multi-backend placement and enable/disable behavior
• scripts/real_openlist_multi_backend_chaos.py: degraded multi-backend recovery and replica healing

Pytest E2E entry:

.venv/bin/python -m pytest tests/e2e/test_web_ui_playwright.py

UI Change Standard

Any meaningful Web UI change must be validated against a real running service.

Required workflow:

1. build frontend assets with npm run build
2. run ./.venv/bin/python scripts/ui_playwright_smoke.py
3. review screenshots in output/playwright/
4. fix layout, spacing, overflow, or interaction issues
5. rerun the Playwright flow

The E2E flow currently covers:

• login
• files page render
• create folder
• upload text file
• authenticated file download
• upload image file
• authenticated inline image preview
• file storage replica inspector
• search
• uploads, recycle bin, storage batch checks, backend edit dialog, policies save, and jobs page render
• browser /api 4xx/5xx failures during the flow

Secrets

Backend credentials are encrypted before they are stored in SQLite. Local development uses a default IRON_SECRET_KEY, but real deployments should set a stable private value before creating S3 or WebDAV backends.

Runtime Artifacts

Do not commit:

• .venv/
• .uv-cache/
• node_modules/
• output/
• .iron-storage/
• .iron-temp/
• .iron-cache/
• local databases
• Python caches

Documentation Rules

• Keep README.md concise and user-facing.
• Keep contributor instructions in CONTRIBUTING.md.
• Keep coding-agent instructions in AGENTS.md.
• Keep deeper project docs in docs/.
• Use relative links in Markdown.
• Update docs when changing setup, commands, architecture, or user-visible behavior.