Iron

Iron is a self-hosted personal cloud drive gateway. It provides one logical file namespace over local storage and pluggable backends, with a browser UI for daily file management and operational visibility.

The project is currently a Product MVP Candidate: the core backend and Web app exist, but the release still needs hardening, broader browser regression coverage, and more real-world usage.

Features

• FastAPI backend with SQLite, SQLAlchemy, and Alembic migrations
• Local authentication with persisted bearer-token sessions
• Directory and file operations: browse, create folder, rename, move, delete, restore, download, and preview
• tus upload flow with local object persistence
• Desktop-first React Web app at /app
• Storage backend management for local directories, S3 storage, and OpenList/WebDAV runtime paths
• Placement policies, reconcile jobs, health checks, and retryable background jobs
• Metadata export, validation, integrity checks, restore plans, and guarded import
• Python Playwright end-to-end coverage for core browser flows
• Real-environment OpenList acceptance scripts for deployment validation

Quick Start

Iron uses uv for local Python environment 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
npm run build
.venv/bin/python -m uvicorn app.main:app --reload

Open the Web app:

http://127.0.0.1:8000/app

Default local bootstrap credentials:

username: admin
password: changeme-iron

For a practical local deployment with OpenList and Aliyun Drive, start with docs/openlist-local-deployment-sop.md.

Configuration

Common environment variables:

• IRON_DATABASE_URL
• IRON_BOOTSTRAP_USERNAME
• IRON_BOOTSTRAP_PASSWORD
• IRON_SECRET_KEY
• IRON_AUTH_SESSION_TTL_HOURS
• IRON_UPLOAD_TEMP_DIR
• IRON_LOCAL_STORAGE_DIR
• IRON_CACHE_DIR
• IRON_JOB_POLL_INTERVAL_SECONDS
• IRON_JOB_BATCH_SIZE

Runtime data is intentionally ignored by Git. By default, local development may create .iron-storage/, .iron-temp/, iron.db, and output/.

IRON_SECRET_KEY encrypts stored backend credentials such as S3 keys and WebDAV passwords. Override the development default before using real storage credentials.

Development

Build the frontend:

npm run build

Run the full test suite:

.venv/bin/python -m pytest

Current expected result:

78 passed

Run the real OpenList acceptance suite against a live local deployment:

.venv/bin/python scripts/real_openlist_suite.py

Run the browser E2E flow directly:

.venv/bin/python scripts/ui_playwright_smoke.py

Regenerate the README demo GIF:

.venv/bin/python scripts/generate_readme_demo.py

Or through pytest:

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

Playwright screenshots and runtime artifacts are written to output/playwright/.

Repository Layout

app/                 FastAPI application, services, repositories, schemas
alembic/             Database migrations
frontend/            Vite + React + TypeScript source
app/web/dist/        Built frontend assets served by FastAPI
scripts/             Local automation and E2E scripts
deploy/              OpenList compose, Iron env templates, and systemd examples
tests/               Backend, API, and browser E2E tests
docs/                Product, architecture, API, and maintenance docs

Documentation

Start with:

• Documentation index
• Product
• Architecture
• API
• Development
• OpenList + Iron Local Deployment SOP

For contribution workflow, see CONTRIBUTING.md. For AI/coding-agent guidance, see AGENTS.md.

Security Notes

Iron is not yet a hardened public Internet service. Treat the current credentials and local bearer-token session model as development-oriented defaults. Change the bootstrap password and review deployment boundaries before exposing the service.

Metadata import is guarded and requires both:

• confirm_replace=true
• a fresh validation token from POST /api/exports/metadata/restore-plan

License

No open source license has been selected yet. Add a LICENSE file before publishing or accepting external contributions.